web/docs/contracts/membership-platform-interfaces.md

EDUT Membership Platform Interfaces (v1)

This document freezes interface targets for membership-gated commerce.

Solidity Interfaces

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

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

Governance Installer

1. POST /governance/install/token
2. POST /governance/install/confirm
3. GET /governance/install/status

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 (ownership wallet)
   • payer_wallet (optional)
   • 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.