70 lines
2.1 KiB
Markdown
70 lines
2.1 KiB
Markdown
# Backend Handoff Checklist: Marketplace Checkout and Entitlements
|
|
|
|
This checklist maps store behavior to required marketplace backend implementation.
|
|
|
|
## Required Endpoints
|
|
|
|
1. `GET /marketplace/offers`
|
|
2. `GET /marketplace/offers/{offer_id}`
|
|
3. `POST /marketplace/checkout/quote`
|
|
4. `POST /marketplace/checkout/confirm`
|
|
5. `GET /marketplace/entitlements?wallet=...`
|
|
|
|
## Required Gate Behavior
|
|
|
|
1. Quote endpoint must deny checkout when membership is not active.
|
|
2. Confirm endpoint must verify quote policy hash and tx match.
|
|
3. Entitlement state must default fail-closed for unknown values.
|
|
|
|
## Store Dependency Mapping
|
|
|
|
1. Store catalog requests `/marketplace/offers` (fallback to local JSON until live).
|
|
2. Store quote action posts selected `offer_id` and ownership wallet.
|
|
3. Optional payer wallet may differ and must include ownership proof.
|
|
4. Store expects quote payload with tx execution fields.
|
|
5. Store confirm path expects `entitlement_active` response.
|
|
|
|
## Quote Response Requirements
|
|
|
|
1. `quote_id`
|
|
2. `wallet` (ownership wallet)
|
|
3. `payer_wallet` (optional)
|
|
4. `offer_id`
|
|
5. `currency`
|
|
6. `amount` or `amount_atomic + decimals`
|
|
7. `policy_hash`
|
|
8. `expires_at`
|
|
9. `tx` execution object or equivalent fields
|
|
|
|
## Confirm Response Requirements
|
|
|
|
1. `status = entitlement_active`
|
|
2. `entitlement_id`
|
|
3. `offer_id`
|
|
4. `wallet` (ownership wallet)
|
|
5. `payer_wallet` (optional)
|
|
6. `tx_hash`
|
|
7. `policy_hash`
|
|
8. `activated_at`
|
|
|
|
## Persistence Requirements
|
|
|
|
1. Quote record with policy hash and expiry.
|
|
2. Confirm record linked to tx hash and entitlement id.
|
|
3. Entitlement lifecycle state with immutable issued event evidence.
|
|
|
|
## Security Requirements
|
|
|
|
1. Membership gate check on quote and confirm paths.
|
|
2. Quote TTL enforcement.
|
|
3. Tx chain, amount, and destination validation.
|
|
4. Idempotent confirm handling for repeated tx hash submissions.
|
|
5. Ownership wallet proof validation when payer wallet differs.
|
|
|
|
## Done Criteria
|
|
|
|
1. Store can request quotes for active members only.
|
|
2. Confirm endpoint issues active entitlements deterministically.
|
|
3. Entitlement listing endpoint returns current state records.
|
|
4. API matches `docs/api/marketplace.openapi.yaml`.
|