Integration

Everything that has to agree across the three repositories: the paymentRef bytes, the EIP-712 digest, the on-chain roles mirrored in the database, the deployment record the backend reads, and the REST surface the app consumes. Each of these is a place where two implementations can drift silently, so each has a mechanism that turns drift into a failing test rather than a stuck payout.

Boundary map

Five artefacts sit between the three repositories. Click one for what has to agree and what happens when it does not; step through them to see which pair of repos each one binds together.

Contract 1 — paymentRef

paymentRef = keccak256(abi.encode(srcChainId, txHash, outputIndex))
ABI types are exactly (uint256, bytes32, uint256)

The same value on both sides: the contract's replay nullifier and the backend's dedup key are literally the same bytes. TypeScript derives it in src/chains/ (viem encodeAbiParameters + keccak256); Solidity has a helper in test/PaymentRef.t.sol that exists only for the cross-check — CouponClaim itself never derives it, it receives bytes32 and nullifies it.

Chain id registry

Non-EVM chains have no EIP-155 id, hence the reserved ids above 2**32. outputIndex is the log index on EVM and the output index (vout) on Bitcoin and Spark. On Bitcoin and Spark, txHash is the txid as displayed — not byte-reversed into internal order. That reversal is the likeliest source of drift, so it has its own committed vector.

Contract 2 — the EIP-712 Entitlement

Solidity builds it with _hashTypedDataV4 over abi.encode(ENTITLEMENT_TYPEHASH, recipient, amount, paymentRef, deadline); TypeScript builds it with viem's hashTypedData in src/issuer/entitlement.ts. Both must produce identical bytes, and entitlement.json pins one domain, one message and the resulting digest for both.

The message deliberately contains no couponId (a backend-chosen number; two coupon rows for one payment would give the contract two ids it cannot tell apart), no nonce and no user signature — replay protection is the paymentRef nullifier, and the user's signature lives one layer up, at the API.

Signature ordering

The contract requires issuerSigs sorted by recovered signer address, strictly ascending. The backend mirrors this in the schema with UNIQUE (claim_id, issuer_address) on attestations and sorts before submitting; the relayer preflights the whole rule off-chain before spending gas.

Contract 3 — roles and the signers table

The signers table holds addresses only, never keys. Because the production image has no src/ and no ts-node, signers are reference data shipped in the SeedSigners migration rather than a seed script.

K and N are configuration, not code. The contract stores threshold (K) and derives N from getRoleMemberCount(ISSUER_ROLE); the backend has ATTESTATION_THRESHOLD. They must match — a backend threshold below the contract's produces claims that are submitted and revert with NotEnoughSignatures(); above it, gas is wasted collecting signatures the contract does not need.

Contract 4 — the deployment record

contract/deployments/11155111.json is committed on purpose. It carries the addresses, the caps, K, the issuer set, the domainSeparator and the entitlementTypehash, so the backend can cross-check the EIP-712 domain instead of hardcoding a copy, and GET /config can serve the app one consistent view.

Contract 5 — REST between app and backend

Base URL API_BASE_URL (…/api), bearer JWT from /auth/google, refreshed via /auth/refresh. Errors arrive in the GlobalExceptionFilter envelope (statusCode, timestamp, path, message, error code), which the app unwraps into ApiError.

Two request conventions the app must honour when those are wired: Idempotency-Key is required on POST /claims and POST /transactions (a retry with the same key returns the winner's stored response rather than doing the work twice), and the claim signature must be produced over the message the challenge returns verbatim — it embeds the coupon code so one signature cannot be replayed against another coupon.

End-to-end sequence

The claim half of the path, where all three repositories meet. Dashed messages are handed over as database rows and picked up by polling — there is no broker, so “sends to” means “writes a row the other one is watching for”.

The user signs exactly once, at the challenge step. Linking addresses is a declaration; the claim-time signature is the proof, and it takes the address from anyone who declared it first without being able to sign.

Drift checks

Failure matrix

What each mismatch actually looks like when it happens. Filter by an error name you are staring at — NotIssuer, Expired, NO_NODE — or by a component.