contracts: sign a contract spend only as the wallet showed it

README.md

@@ -124,11 +124,11 @@ Sequentia example in `lwk_simplicity`.
 | `lwk_wollet` | The watch-only wallet core (CT descriptors, scanning, balances, PSET create/finalize). Sequentia additions: explicit-output handling, any-asset fees + RBF/CPFP rescue, staking output and two-step unbonding, SeqDEX swap/HTLC builders, SeqOB covenant fill/refund, staking-pool delegation, CoinJoin input signing, the OpenAMP client (feature `openamp`), adaptor signatures (feature `adaptor`), the Arca leaf module (feature `ark`, `src/ark/`), and the whole Bitcoin parent-chain module (`src/btc/`). |
 | `lwk_common` | Shared types. Sequentia addition: `Network::sequentia_testnet()` and Sequentia address parameters. |
 | `lwk_signer` | Software signer (BIP39 mnemonic to PSET signatures); signs Sequentia PSETs as-is. Sequentia additions: `sign_tapscript`, a script-path signature at any leaf version over the Elements signature hash, for covenant leaves whose signature opcodes check the wallet's key, under `SIGHASH_DEFAULT` or `SIGHASH_ALL` unless the caller names another type; `sign_csfs`, a message signature for `OP_CHECKSIGFROMSTACK` over Arca's three messages, which rebuilds the digest from the message's fields, refuses a mismatch or another chain than the wallet's, and caps what a rebind leaves to whoever broadcasts. Each has a `describe` for the approval screen. |
-| `lwk_wasm` | WebAssembly bindings (wasm-bindgen). Sequentia additions: `Network.sequentiaTestnet()`, `BtcWallet`, the `xchain*` HTLC helpers, SeqDEX bindings, `buildCovenantFillTx` / `buildCovenantRefundTx`, delegation (`buildDelegationCreateTx`, `buildDelegationSpendTx`, `findDelegationRecords`), unbonding (`buildUnbondTx`, `buildUnbondClaimTx`), the contract engine (`ContractTemplate`, `ContractInstance`, `ContractSpend`), `coinjoinSignInputs` / `coinjoinUnblindOutputs`, the `Openamp` client and enclave helpers, `adaptor*`, `Signer.signTapscript` / `tapscriptSighash` / `tapscriptDescribe`, `Signer.signCsfs` / `csfsDigest` / `csfsDescribe`, Arca leaves (`ArkVerifier`, `ArkStore`, `arkParseRecord`, `Signer.arkLeafKey`), staking and any-asset-fee bindings. |
+| `lwk_wasm` | WebAssembly bindings (wasm-bindgen). Sequentia additions: `Network.sequentiaTestnet()`, `BtcWallet`, the `xchain*` HTLC helpers, SeqDEX bindings, `buildCovenantFillTx` / `buildCovenantRefundTx`, delegation (`buildDelegationCreateTx`, `buildDelegationSpendTx`, `findDelegationRecords`), unbonding (`buildUnbondTx`, `buildUnbondClaimTx`), the contract engine (`ContractTemplate`, `ContractInstance`, `ContractSpend`, `ContractApproval`, `Signer.signContractSpend`), `coinjoinSignInputs` / `coinjoinUnblindOutputs`, the `Openamp` client and enclave helpers, `adaptor*`, `Signer.signTapscript` / `tapscriptSighash` / `tapscriptDescribe`, `Signer.signCsfs` / `csfsDigest` / `csfsDescribe`, Arca leaves (`ArkVerifier`, `ArkStore`, `arkParseRecord`, `Signer.arkLeafKey`), staking and any-asset-fee bindings. |
 | `lwk_bindings` | UniFFI bindings (Python, Kotlin, Swift, C#, Go, C++). Upstream API surface (no Sequentia network exposed yet); only the `Contract::from_parts` call changed. |
 | `lwk_cli` / `lwk_app` / `lwk_rpc_model` / `lwk_tiny_jrpc` | JSON-RPC wallet server and CLI client. Upstream apart from `lwk_app`'s `Contract::from_parts` call: no `sequentia` network selector yet (networks: liquid, liquid-testnet, regtest). |
 | `lwk_jade`, `lwk_ledger`, `lwk_hwi` | Hardware-signer support (upstream; not wired to Sequentia flows). |
-| `lwk_contracts` | The contract engine (a crate of this fork): reads a `sequentia-contracts` descriptor with that repository's reader and pinned compiler, recomputes an instance's address and leaves, lists its paths and what each needs, builds the spend of a path, runs its program against the final transaction, and signs with a contract key. See `lwk_contracts/README.md`. |
+| `lwk_contracts` | The contract engine (a crate of this fork): reads a `sequentia-contracts` descriptor with that repository's reader and pinned compiler, recomputes an instance's address and leaves, lists its paths and what each needs, builds the spend of a path, runs its program against the final transaction, and signs with a contract key only what the wallet showed (the five-point rule). See `lwk_contracts/README.md`. |
 | `lwk_simplicity` | Upstream Simplicity utilities plus one Sequentia example, `examples/live_covenant.rs`, which derives and spends a Simplicity leaf on the live testnet. |
 | `lwk_boltz`, `lwk_payment_instructions`, `amp2_mock`, `lwk_containers`, `lwk_test_util` | Upstream LWK crates (Boltz swaps, payment-URI parsing, test infrastructure). Unmodified on this branch. |
 | `rust-elements` (vendored, not a workspace member) | Fork of the `elements` crate wired in via `[patch.crates-io]`, with a `sequentia` cargo feature for anchored headers, issuance denomination, and `tb`/`tsqb` address parsing. |
@@ -183,7 +183,8 @@ lwk_wollet = { features = ["btc-async"] }      # wasm / async apps
 `buildDelegationCreateTx()` / `buildDelegationSpendTx()`, `buildUnbondTx()` /
 `buildUnbondClaimTx()`, `coinjoinSignInputs()`, the `Openamp` client, the
 `adaptor*` functions, and the contract engine (`ContractTemplate`,
-`ContractInstance`, `ContractSpend`).
+`ContractInstance`, `ContractSpend`, `ContractApproval`,
+`Signer.signContractSpend`).
 
 ```sh
 lwk_wasm/build-web.sh    # wasm-pack build --target web --release; needs clang

SEQUENTIA.md

@@ -485,8 +485,11 @@ The fork is not published to npm; consumers build `pkg/` with `wasm-pack`.
   `ContractTemplate` (a descriptor and its resolved sources, checked; the
   carried templates by hash, `knownList`), `ContractInstance` (the output,
   address, derivation and paths of an instance; `planDrip` for the faucet
-  drip covenant) and `ContractSpend` (the spend of a path, its outputs'
-  roles, its locks). Values cross as JSON text.
+  drip covenant), `ContractSpend` (the spend of a path, its outputs'
+  roles, its locks) and `ContractApproval` (the spend checked under the
+  five-point signing rule, with the summary a wallet shows and its digest).
+  `Signer.signContractSpend(approval, shownDigest)` signs only that digest's
+  spend. Values cross as JSON text.
 - `build-web.sh`: the browser build (`wasm-pack build --target web
   --release`) with every build-machine path remapped, failing if one remains.
 - `src/seqdex_swap.rs`: `SwapRequest` (same-chain SeqDEX swap proposal).

lwk_contracts/README.md

@@ -22,12 +22,37 @@ values on one chain. The engine:
   missing or second fee, and outputs that do not balance the coin;
 - refuses a spend whose relative lock (BIP68) or lock time the chain would
   refuse now, from the chain facts it is given;
-- signs with a contract key (under `m/8383h/{coin}h/0h`, `0/0` by default),
-  only the one the path names; runs the program against the final
+- signs, through the five-point gate below, with a contract key (under
+  `m/8383h/{coin}h/0h`, `0/0` by default), only the one the path names; runs
+  the program against the final
   transaction, naming the source check that fails when it refuses; and pads
   the witness with an annex when the program costs more than it earns under
   the budget rule (`min(4 × witness bytes + 50, 4000050)` weight units).
 
+## Signing under the five-point rule
+
+A wallet signs a contract spend only through `approval::Approval`, which holds
+the five points of the signing rule in the contracts' specification:
+
+1. the template hash is on the wallet's list of known templates;
+2. the engine recomputed the output from the template and the instance, and
+   the coin pays it;
+3. the engine ran the program against the final transaction;
+4. the approval shows the template (by the registry's name where the wallet
+   has one, else its commitment root), the path, every parameter by its role
+   (assets by ticker, amounts in the asset's precision, keys marked when they
+   are the wallet's, relative locks as a delay), and the wallet's own balance
+   change in every asset, beside the contract's, the payments and the fee;
+5. the key is a contract key, the one the path names.
+
+`Approval::prepare` checks 1, 2, 3 and 5 and the chain's locks, and writes the
+summary of 4 with a digest over it. `Approval::sign` signs only when handed that
+digest back: it prepares the spend again from the same inputs, refuses if the
+digest differs, and runs the program once more against the transaction it
+returns. To run a program before the approval, the engine signs inside itself
+(the program checks the signature) and drops that signature; the only one that
+leaves the engine is made by `sign`.
+
 The faucet drip covenant (`sequentia/faucet-drip`) has a planner, `drip::plan`,
 which computes a drip's sequence, successor and tier as its program checks
 them.
@@ -46,13 +71,14 @@ run the tests.
 ## Tests
 
 ```sh
-cargo test -p lwk_contracts                       # vectors, refusals, budget
+cargo test -p lwk_contracts                       # vectors, refusals, budget, the gate
 SEQUENTIA_BIN=/path/to/Sequentia/src cargo test -p lwk_contracts --test drip_regtest -- --nocapture
 ```
 
 `tests/vectors.rs` reproduces every golden vector and makes every refusal of
-the corpus for its reason. `tests/drip_regtest.rs` starts a local
+the corpus for its reason. `tests/approval.rs` holds the gate to its rule with
+no chain. `tests/drip_regtest.rs` starts a local
 `elementsregtest` chain with Simplicity active and `-par=1`, drips from a
-covenant, and forces three bad drips into blocks (before the interval, above
+covenant through the gate, and forces three bad drips into blocks (before the interval, above
 the tier, a successor that is not the covenant), asserting each refusal's
 reason in the mempool and in the block.