Skip to content

feat(types): add the HashLocked output content variant - #143

Open
rsantacroce wants to merge 1 commit into
fix/swap-expiry-consensus-divergencefrom
feat/hashlocked-output
Open

feat(types): add the HashLocked output content variant#143
rsantacroce wants to merge 1 commit into
fix/swap-expiry-consensus-divergencefrom
feat/hashlocked-output

Conversation

@rsantacroce

Copy link
Copy Markdown
Collaborator

Phase 1 of ATOMIC_SWAP_PLAN. Stacked on #138 (the expiry fix), which is stacked on #137 (the build fix). Review those first.

The escrow primitive for one leg of an atomic swap:

HashLocked {
    value: bitcoin::Amount,
    hash: [u8; 32],
    claimant: Address,
    refund_to: Address,
    timeout_height: u32,
}

claimant spends it by revealing a preimage of hash; refund_to reclaims it once the chain reaches timeout_height. Both are decided from block data alone — which is the point. Completing a cross-chain swap stops requiring any node to observe the other chain, so the vulnerability in #140's sibling analysis (a miner claiming an escrow without paying on BTC) has nothing left to exploit.

Two things this PR is careful about

SHA-256, not blake3. The counterparty leg is a Bitcoin HTLC gated on OP_SHA256. Two locks that don't open to the same secret aren't a swap, they're two refunds — and the failure is silent, since both sides still look claimable until neither is. SwapId is blake3, so this is exactly where the house habit would have produced the break. The variant's doc comment says so.

Appended last, and pinned. Content is Borsh-encoded by variant index into every Output, and outputs hash into the block's merkle root. A reordered variant rewrites the encoding of every block carrying it, and surfaces as a merkle-root mismatch with nothing pointing at the cause.

output_content_borsh_discriminants_are_stable pins the numbering. Verified it has teeth — moving HashLocked above SwapPending reproduces the failure:

assertion `left == right` failed: SwapPending { .. } must encode as variant 2;
a changed index rewrites the merkle root of every block carrying this output type
  left: Some(3)
 right: Some(2)

Note this guard did not previously exist. The plan claimed ParentChainType had one to copy; it does not — that test lives only on feat/parent-chain-phase-9-docs. The plan is corrected in the same push.

Scope

Ten sites, all found by the compiler: the three Serde/Borsh representations, the four From conversions, GetValue, a predicate, and one exhaustive match in integration_tests/setup.rs that only --all-targets reaches.

No spend rules yet — an output of this type can be created but not spent. Phase 3 adds the claim and refund paths.

Verification

cargo build --workspace --all-targets, cargo fmt --all --check, cargo clippy --workspace --all-targets all clean. 56 unit tests pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Mrg9zkV9bEdAvVEjx1RKLx

Phase 1 of docs/specs/ATOMIC_SWAP_PLAN.html. The escrow primitive for one
leg of an atomic swap: `claimant` spends it by revealing a preimage of
`hash`, or the output's own address reclaims it once the chain reaches
`timeout_height`. Both are decided from block data alone, which is the
point — completing a cross-chain swap stops requiring any node to observe
the other chain.

There is deliberately no `refund_to` field. The address that authorises a
refund and the address a refund pays have to be the same one, so carrying
both would only create a way for them to disagree; the refund pays
`Output::address`, which is also the key that signs for it.

The hash is SHA-256, not blake3. The counterparty leg is a Bitcoin HTLC
gated on OP_SHA256, and two locks that do not open to the same secret are
not a swap; they are two refunds. `SwapId` is blake3, so this is the exact
place the habit would have produced a silent break, and the doc comment on
the variant says so.

Appended last. `Content` is Borsh-encoded by variant index into every
`Output`, and outputs hash into the block's merkle root, so a reordered
variant rewrites the encoding of every block carrying it — a merkle-root
mismatch with no compile error pointing at the cause. Nothing is in
production yet, so the discipline costs nothing to adopt today; the point is
that it predates the moment it starts to matter.

`output_content_borsh_discriminants_are_stable` pins the numbering. Moving
HashLocked above SwapPending reproduces the failure it exists to catch, with
the consequence named in the assertion message rather than left as a bare
index mismatch.

Ten sites updated, all found by the compiler: the three Serde/Borsh
representations, the four `From` conversions, `GetValue`, a predicate, and
one exhaustive match in `integration_tests/setup.rs` that only
`--all-targets` reaches.

No spend rules yet — an output of this type can be created but not spent.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mrg9zkV9bEdAvVEjx1RKLx
@rsantacroce
rsantacroce force-pushed the feat/hashlocked-output branch from 41dd175 to c18bb69 Compare August 30, 2026 16:52
@rsantacroce

Copy link
Copy Markdown
Collaborator Author

Updated: refund_to is gone.

Writing the refund rule in Phase 3 made it obvious the field was a second source of truth — the address that authorises a refund and the address a refund pays have to be the same one, and carrying both only creates a way for them to disagree. Refunds now pay Output::address, which is also the key that signs for them.

The branch is rebuilt to match what landed on feat/atomic-swap, so this PR and that branch no longer disagree about the variant's shape. Still Phase 1 only: the output can be created but not spent.

Verified: build/fmt/clippy clean on --all-targets, 56 unit tests pass.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant