# EDUT Membership Platform Interfaces (v1)

This document freezes interface targets for membership-gated commerce.

## Solidity Interfaces

```solidity
interface IEdutMembership {
    event MembershipMinted(address indexed wallet, uint256 indexed tokenId, uint256 amountPaid, address currency);
    event MintPriceUpdated(address indexed currency, uint256 amountAtomic);
    event MembershipStatusUpdated(address indexed wallet, uint8 status);

    function mintMembership(address recipient) external payable returns (uint256 tokenId);
    function hasMembership(address wallet) external view returns (bool);
    function membershipStatus(address wallet) external view returns (uint8 status);
    function currentMintPrice() external view returns (address currency, uint256 amountAtomic);
}

interface IEdutOfferRegistry {
    event OfferUpserted(bytes32 indexed offerKey, bytes32 policyHash, address indexed issuer);
    event OfferStatusChanged(bytes32 indexed offerKey, uint8 status);

    function upsertOffer(bytes32 offerKey, bytes32 policyHash, bytes calldata encodedOffer) external;
    function setOfferStatus(bytes32 offerKey, uint8 status) external;
    function getOffer(bytes32 offerKey) external view returns (bytes memory encodedOffer);
}

interface IEdutEntitlement {
    event EntitlementMinted(bytes32 indexed entitlementId, bytes32 indexed offerKey, address indexed wallet);
    event EntitlementStateChanged(bytes32 indexed entitlementId, uint8 state);

    function mintEntitlement(bytes32 offerKey, address wallet, bytes32 policyHash) external returns (bytes32 entitlementId);
    function entitlementState(bytes32 entitlementId) external view returns (uint8 state);
}
```

## Status Enums

```text
MembershipStatus:
0 = NONE
1 = ACTIVE
2 = SUSPENDED
3 = REVOKED

OfferStatus:
0 = DRAFT
1 = ACTIVE
2 = PAUSED
3 = RETIRED

EntitlementState:
0 = ACTIVE
1 = SUSPENDED
2 = REVOKED
3 = EXPIRED
```

## API Surface (Backend)

## Wallet + Membership

1. `POST /secret/wallet/intent`
2. `POST /secret/wallet/verify`
3. `POST /secret/membership/quote`
4. `POST /secret/membership/confirm`
5. `GET /secret/membership/status?designation_code=...`

## Marketplace

1. `GET /marketplace/offers`
2. `GET /marketplace/offers/{offer_id}`
3. `POST /marketplace/checkout/quote`
4. `POST /marketplace/checkout/confirm`
5. `GET /marketplace/entitlements`

## Issuer APIs

1. `POST /issuer/offers/upsert`
2. `POST /issuer/offers/{offer_id}/status`
3. `POST /issuer/manifests/upsert`

## Deterministic Gate Requirements

1. Every checkout quote must include:
   - `quote_id`
   - `wallet`
   - `offer_id`
   - `currency`
   - `amount_atomic`
   - `policy_hash`
   - `expires_at`
2. Checkout confirm must fail closed if:
   - membership is not active,
   - quote expired,
   - tx amount/currency mismatch,
   - policy hash mismatch.
3. Entitlement activation must fail closed when state is not `ACTIVE`.

## Evidence Requirements

Each successful purchase must emit/record:

1. wallet
2. membership status snapshot
3. offer_id and policy_hash
4. quote_id
5. tx_hash and chain_id
6. entitlement_id
7. receipt timestamp

## Compatibility Rule

Interfaces can only evolve through additive changes in v1. Breaking changes require v2 namespace and migration plan.