web/docs/handoff/membership-backend-checklist.md

Backend Handoff Checklist: Membership Activation Flow

This checklist maps current web behavior to required backend implementation.

Required Endpoints

1. POST /secret/wallet/intent
2. POST /secret/wallet/verify
3. POST /secret/membership/quote
4. POST /secret/membership/confirm
5. POST /secret/notify

Web Behavior Dependency

The landing page currently executes these actions in order:

1. Connect wallet (eth_requestAccounts).
2. Get signature intent.
3. Sign typed data (eth_signTypedData_v4).
4. Verify signature.
5. Request membership quote.
6. Send wallet transaction (eth_sendTransaction) using returned tx params.
7. Confirm membership by tx hash.
8. Show acknowledged state and optional notify form.

If any endpoint is missing, flow fails closed and shows status error.

Response Requirements

Intent

Must return:

1. intent_id
2. designation_code
3. display_token
4. nonce
5. issued_at
6. expires_at
7. chain_id

Verify

Must return:

1. status = signature_verified
2. designation_code
3. display_token

Membership Quote

Must return:

1. quote_id
2. chain_id
3. currency
4. amount or amount_atomic + decimals
5. deadline
6. tx execution fields:
   • either tx object for wallet send
   • or contract_address + calldata + value

Membership Confirm

Must return:

1. status = membership_active
2. designation_code
3. display_token
4. tx_hash

Notify

Must accept:

1. email
2. designation_code
3. designation_token
4. wallet
5. locale

Security Requirements

1. Replay-safe intent nonce and quote nonce.
2. Intent and quote TTL enforcement.
3. Chain allowlist checks.
4. Origin allowlist checks.
5. Tx amount/currency/recipient exact-match checks.
6. Idempotent confirm path for repeated tx_hash submissions.

Data Persistence Requirements

Persist at minimum:

1. designation code and auth token
2. wallet and chain id
3. intent fields and verification time
4. quote fields and expiry
5. membership tx hash and activation timestamp
6. notification email link metadata

Observability Requirements

1. Correlation id per flow (intent_id preferred).
2. Structured logs for each transition.
3. Metrics counters for:
   • intent requests
   • verify success/fail
   • quote success/fail
   • confirm success/fail
   • notify success/fail

Done Criteria

1. Web flow reaches acknowledged state on successful membership tx.
2. Membership inactive wallets cannot complete flow.
3. Confirm endpoint is idempotent and deterministic.
4. API matches docs/api/secret-system.openapi.yaml.