Repository navigation
feat(settlement): canonical request, policy fixture, receipt, and classifier (B02) - #12
Merged
selezenart merged 1 commit intoSep 7, 2026
Conversation
… classifier Implements B02 for the Coder B lane as pure adapter logic with no network, no durable state, and no credential. Canonical request (B02.1, B02.2). One intent produces byte-stable calldata, a keccak256 payload fingerprint, a provider idempotency key, and a reference ID. Serialization writes an explicit field order rather than relying on JSON.stringify over an object literal, whose key order depends on construction order; two workers building the same obligation must fingerprint identically or the provider key stops collapsing duplicates. Addresses are lowercased so checksummed and non-checksummed spellings cannot fingerprint apart. A golden vector pins the exact bytes, because changing any of them changes every in-flight idempotency key. The 24-hour provider window is documented as supplemental: OneShot durable state remains the authority past it. Only the direct transfer path is built. B01.3 recorded the Arc Memo forwarded call NOT_SUPPORTED, so no memo calldata builder exists to be reached by mistake. Policy fixture (B02.3). Expresses the required Privy policy as rules over the documented condition fields, terminated by an unconditional default deny. assessPolicySoundness catches the two ways such a policy silently stops protecting anything: losing its terminal deny, or dropping a constrained dimension. A keccak256 digest lets readiness detect drift, since the policy lives in Privy configuration outside this repository and can be edited without a commit. The digest ignores recipient ordering so an operator relisting the same addresses does not read as drift. Receipt verification (B02.4). Confirmation requires a final receipt and exactly one Transfer matching sender, recipient, and amount, emitted by the configured token. status: 1 alone is not confirmation, and tests cover the cases that would otherwise pass: no logs, a redirected recipient, an amount off by one atomic unit, a Transfer from an impostor contract, and two matching transfers, which would mean more value moved than was authorized. Outcome classifier (B02.5). Doubt is structural. DEFINITELY_NOT_SUBMITTED is granted only for narrow pre-flight proofs where nothing was broadcast; every ambiguous signal and every unrecognized response shape falls through to POSSIBLY_SUBMITTED, including a response kind from a future provider version. A receipt that fails to prove settlement is POSSIBLY_SUBMITTED, never DEFINITELY_NOT_SUBMITTED: absence of proof is not proof of absence.
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ❌ Deployment failed View logs |
oneshot | 031b119 | Sep 07 2026, 01:59 PM |
This was referenced Sep 7, 2026
selezenart
merged commit Sep 7, 2026
1dda3c1
into
milestone/b01-sdk-network-compatibility
3 of 4 checks passed
6 of 9 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements B02 — Canonical request, policy, and receipt verification for the
Coder B lane. Pure adapter logic: no network, no durable state, no credential.
Stacked on B01 (PR #11), which is not yet merged, so this PR targets the B01
branch. Review B01 first.
Four pieces: a byte-stable canonical settlement request with a stable provider
idempotency identity, an expected Privy policy with a drift digest, an Arc
receipt verifier, and an exhaustive submission-outcome classifier.
Scope and acceptance criteria
The change is limited to the stated milestone or issue.
Acceptance criteria are listed and satisfied.
No unrelated cleanup is included.
B02.1 correlated calldata — direct
transfer(address,uint256)with exactchain, token, method, recipient, amount, and zero native value. Golden vectors
pin calldata, canonical body, and fingerprint. The Arc Memo forwarded call is
not built: B01.3 recorded it
NOT_SUPPORTED.B02.2 Privy request identity — deterministic body, keccak256 payload
fingerprint, derived idempotency key, stable reference ID, and refusal of key
reuse under a different fingerprint. The 24-hour provider window is documented
as supplemental only.
B02.3 policy fixture — default-deny policy over the documented Privy
condition fields, a soundness check, and a digest for drift detection.
B02.4 receipt verifier — confirmation only from a final receipt plus
exactly one matching Transfer emitted by the configured token.
B02.5 outcome classifier — exhaustive mapping to
CONFIRMED,DEFINITELY_NOT_SUBMITTED, orPOSSIBLY_SUBMITTED.Product and security invariants
Invariant notes:
No durable state, table, or migration is touched, so tenant isolation and
sponsor-control rows are not applicable. The invariants this change carries:
request and one derived idempotency key, so independent workers building the
same obligation produce the identical key and a duplicate collapses at the
provider too. OneShot durable state remains the authority; the provider key is
defence in depth.
status: 1is not confirmation. A successful receipt with no matchingTransfer is
NOT_CONFIRMED, not success and not failure. Two matchingTransfers are also refused: that would mean more value moved than authorized.
DEFINITELY_NOT_SUBMITTEDallows afresh attempt without reconciliation, and it is granted only for narrow
pre-flight proofs where nothing was broadcast. Every ambiguous signal,
unrecognized response, and unmatched receipt is
POSSIBLY_SUBMITTED.bigintthroughout. Amounts are compared and encoded exactly,including values beyond IEEE-754 integer safety.
Validation
Independent review evidence
Gate A — exact candidate tree before push
Base commit SHA:
8be8d09b8ab5da19031af28fcee9da128a16f82b(develop)Candidate tree SHA:
3351a19e455024cf65de3f9fb400d8eac5df4080Candidate commit SHA:
031b119b8d97570b1247cbe37a5e42032333ef84Reviewer tool:
free-pi-cli0.2.19Reviewer model:
glm-5.3-flashVerdict:
VERDICT: PASSBlocking findings: None
The reviewed tree equals the committed tree.
Reviewed the full branch content, B01 and B02 together, against the frozen
contract pack and the security invariants.
Non-blocking findings, recorded and deferred:
packages/arc-adapter/src/receipt.ts— the verifier does not bind a receiptto an expected transaction hash; correctness currently relies on the caller
having fetched by hash. Worth tightening in B03/B04, where the hash is known.
packages/privy-adapter/src/request.ts—assertIdempotencyKeyBindingisonly reachable on a caller-supplied mismatch, because the key is derived from
the fingerprint. The code comment already says so, and the check is kept
deliberately so the invariant outlives the derivation choice.
Gate B — exact remote PR head
Risk and rollback
Residual risks:
ESLint and TypeScriptjoblooks for a root
package.jsonpluspnpm-lock.yaml, finds neither, andskips. All validation above is local. The job also hard-fails if those two
files are ever committed apart.
repo CI expects a pnpm workspace. When Coder A scaffolds the root workspace,
the three
package-lock.jsonfiles should be dropped. A owns root config, sothis is not resolved here.
B03 does that.
Rollback: additive packages on a short-lived branch. Revert or close the PR. No
migration, deployment, or durable state.
Human merge