Server Store Contract

The reference MemoryServerChannelStore is for tests and examples. Production servers need a durable implementation of ServerStateStore with the semantics below.

Required Guarantees

• Writes are durable before the method resolves.
• Failed writes leave no partial replay, idempotency, channel, or claim-attempt state.
• Compare-and-set checks and uniqueness checks happen in the same transaction as the write they protect.
• Records survive process restart and can be reloaded before retry recovery.

Runtime serialization is a separate adapter contract. Deployments with multiple server processes must also provide a shared ChannelLockManager as described in server-runtime-lock-contract.md.

Replay And Idempotency

commitExactPayment consumes a transaction id once per server or facilitator trust domain. paymentOutputIndex remains receipt evidence, but a second output from the same transaction is a replay conflict. A cached exact retry is the same verifier-derived transaction id, same output index, and same request fingerprint; payload byte equality is not required because transactionId is an optional hint.

PaymentIdentifierRecord.id must be globally unique inside the same trust domain. Reusing an id with a different request fingerprint, payload hash, or payment scope must fail atomically.

Settlement State

commitSettlement must atomically write the batch commitment, optional payment identifier, and next channel state only when the current channel still matches the expected snapshot.

saveClaimAttempt must allow only one open claim attempt per channel. applyClaimAttempt must update channel state only when the channel still matches the attempt snapshot.

Handler Side Effects

Payment verification happens before the protected handler. Durable payment commit happens after the handler returns, and a commit failure can return 500 after application work has already run.

Handlers that perform non-repeatable work should require payment-identifier and keep an application-owned idempotency or outbox table keyed by paymentIdentifier and requestFingerprint. The handler should return the cached application result on retry, while the server store retries payment settlement or replay commit.

Source: /docs/server-store-contract.md