Add frozen membership-platform interfaces and API surface doc

README.md

@@ -28,6 +28,8 @@ docs/
   roadmap-membership-platform.md
   review-notes.md
   platform-spec-alignment-review.md
+  contracts/
+    membership-platform-interfaces.md
   schemas/
     offer.v1.schema.json
     entitlement.v1.schema.json

docs/contracts/membership-platform-interfaces.md

@@ -0,0 +1,114 @@
+# 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.