feat(covenantsigner): wallet-signed EIP-712 approvals + cooperative REDEEM/RENEW

[piotr-roslaniec]

Summary

Enables wallet-signed (eth_signTypedData_v4) covenant artifact approvals and adds
the cooperative REDEEM / RENEW action paths to the keep-core covenant signer.

This is the keep-core prerequisite (section A of the VBA EIP-712 change-list) that must land
before this covenant work goes live: today the signer verifies a bare EIP-712 struct
hash (no 0x1901, no domain separator) against the depositor's secp256k1 key, which
no connected ETH wallet can produce. This PR domain-wraps the digest, binds the depositor
approval to a pinned ETH identity via ecrecover, and builds out the redeem/renew
transaction path.

Stacked on top of #3882 (feat/psbt-covenant-final-project-pr) — the only branch carrying
pkg/covenantsigner/. Tracked by tlabs-xyz/vba-dashboard#172:
https://github.com/tlabs-xyz/vba-dashboard/issues/172

What changed

A1 - Domain-wrap the digest (EIP-712 v2, off-chain / salt-based).
The approval digest is now keccak256(0x1901 ‖ domainSeparator ‖ structHash) with domain
EIP712Domain(string name,string version,uint256 chainId,bytes32 salt) (no
verifyingContract, since verification is off-chain). name = "tBTC Covenant Artifact Approval", version = "2", chainId + salt from signer config (default salt =
keccak256("tBTC Covenant Artifact Approval Domain v2")). Domain params are threaded from
config → validation options → digest, including the exported ComputeArtifactApprovalDigest
used by pkg/tbtc.

A2 - ETH identity binding. Optional EthAddress on DepositorTrustRoot (keyed by
route/reserve/network). When pinned, the depositor approval is verified via
ecrecover-and-compare (65-byte r‖s‖v, v in {27,28} or {0,1}, low-S enforced);
otherwise it falls back to the secp256k1 script key. Custodian role stays secp256k1.

A3 - Hard cut to approvalVersion = 2 (v1 rejected). Nothing is deployed yet, so no
transition window is needed.

A4 - Vectors. Regenerated the v2 approval vectors and added a real-wallet vector
whose digest is cross-verified byte-identical against the independent eth_account
(0.13.7) EIP-712 encoder — genuine eth_signTypedData_v4 compatibility, not a
self-referential check. A startup guard rejects a config that pins depositor ETH addresses
while eip712ChainId == 0.

A5 - Cooperative REDEEM / RENEW path. New CovenantAction discriminator
(MIGRATION / REDEEM / RENEW; empty defaults to MIGRATION), RedeemDestinationReservation /
RenewDestinationReservation, redeem/renew commitment schemas (SHA-256 over canonical JSON,
mirroring migration), action-dispatched validation, and an action branch in
buildCovenantTransactionBuilder. The built transaction is proven to pay exactly the
committed output — the transaction plan's destinationValueSats is bound to the committed
output value.

Commitment schemas (normative contract for the client repos to mirror):

• redeem: {reserve, epoch, route, revealer, vault, network, outputScriptHash, outputValueSats}
• renew: {reserve, epoch, route, revealer, vault, network, nextCovenantScriptHash, nextMaturityHeight, outputValueSats}

Client-side contract (must be mirrored byte-for-byte)

• digest = keccak256(0x1901 ‖ domainSeparator ‖ structHash).
• Struct: ArtifactApproval(uint8 approvalVersion,bytes32 route,bytes32 scriptTemplateId,bytes32 destinationCommitmentHash,bytes32 planCommitmentHash), approvalVersion = 2.
• route / scriptTemplateId are bytes32 = keccak256(identifier string) — the dApp must
  pre-hash them; a wallet encoder given the raw bytes32 reproduces the digest.

Verification

• go test ./pkg/covenantsigner/... — 156 passed
• go test ./pkg/tbtc/... — 275 passed (full suite)
• go build ./... — green; gofmt clean
• Headline flow proven end-to-end: a wallet-signed (ETH-identity) cooperative REDEEM is
  accepted through Service.Submit, and the signed transaction pays exactly the committed
  redeem/renew output (scriptPubKey + value).

Out of scope

The section-B/C client sync (covenant-manager, dashboard engine.ts, verification kit,
co-sign service, dual-connection wallet UX) lives in other repos. The pre-existing migration
depositScript-as-output gap is flagged, not fixed here — the redeem/renew paths sidestep it
by carrying an explicit output scriptPubKey.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 57a8a581-b592-4196-a696-fc0a20ed2425

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/covenant-eip712-eth-leg

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[piotr-roslaniec]

Security-review follow-ups (deferred from this PR)

The hardening findings addressed in d3afaa7f7 are self-contained. Three further findings were intentionally not included here because each reaches beyond the signer or conflicts with a recent decision. Documenting them so they aren't lost:

1. REDEEM/RENEW carry no freshness/authority bound — deferred (needs decision)

MIGRATION is gated by an ed25519 migrationPlanQuote with an expiresAt check (validation_quote.go), which is skipped for REDEEM/RENEW (validation.go:353). ArtifactApprovalPayload has no expiry field, so a REDEEM/RENEW depositor signature is long-lived and replayable within the epoch. Mitigation present: activeOutpointTxid/Vout is bound inside planCommitmentHash, pinning the input UTXO.

Why deferred: the "cryptographically bind and enforce signer-approval expiry" feature was reverted twice recently (af236a25a, 2faf6e764). Re-introducing a freshness field reverses that deliberate decision and is a protocol change requiring coordinated client + orchestrator updates. Needs a design call before implementation.

Options: add an expiry field to the approval payload; require a parallel REDEEM/RENEW plan-quote; or explicitly document that epoch-scoped UTXO binding satisfies the threat model and why.

2. MigrationTransactionPlan name leaks into REDEEM/RENEW — deferred (cross-repo)

REDEEM payout and RENEW re-lock values bind to MigrationTransactionPlan.DestinationValueSats; the struct, fields, and JSON key migrationTransactionPlan all say "migration" while serving three actions. Every mirroring client (covenant-manager / dashboard / verification-kit) must send a field literally named "migration" to redeem/renew.

Why deferred: a back-compat input alias alone doesn't fix the response side (the server still emits migrationTransactionPlan), so client-facing confusion persists until the three client repos are updated together. Belongs in a coordinated cross-repo rename (e.g. to covenantTransactionPlan) rather than a signer hardening commit.

3. Empty depositorTrustRoots falls back to request-supplied key — already addressed

When depositorTrustRoots is empty and structured signing is enabled, the depositor key is caller-supplied and only a warning is logged (server.go:110-118).

Status: this is already enforceable via the existing requireApprovalTrustRoots config flag — validateRequiredApprovalTrustRoots (server.go:190) hard-errors on missing trust roots when the flag is set. The warn-only default is the intentional opt-in posture. Recommend documenting the flag rather than changing the default to a hard error (which would break trustless dev/test deployments).

---

Suggested next steps: track (1) and (2) as separate issues; treat (3) as resolved via config documentation.