Skip to content

fix(TBC777): credit only the deposit recorded for the listed revision - #523

Merged
ClemensLey merged 5 commits into
bitcoin-computer:stagingfrom
codenlighten:fix/tbc777-escrow-flag
Sep 29, 2026
Merged

ClemensLey merged 5 commits into
bitcoin-computer:stagingfrom
codenlighten:fix/tbc777-escrow-flag

Conversation

@codenlighten

@codenlighten codenlighten commented Sep 28, 2026 •

Copy link
Copy Markdown

Summary

EscrowAuditor counts a deposit as the drop in amount from a listed revision R to its next revision, provided the
next revision has escrow === <this escrow>. deposit() sets escrow, and only a regular withdraw clears it.
The inherited transfer() and burn() lower amount and leave escrow set, and so do Commodity's overrides. An
escrow can therefore list a revision after the deposit, and a later transfer or burn is credited as a deposit.

Demonstrated on LTC regtest against unmodified staging (4d89340):

  • TBC777: 10n minted. 1n is deposited into an escrow that also lists the post-deposit revision, and the other
    9n is transferred to another key. A claim for 10n is accepted, and the total supply becomes 19n.
  • Commodity: a mined subsidy with 1 unit deposited and the rest transferred. A claim for the full subsidy is
    accepted, so the supply roughly doubles.
  • The same happens with burn() in place of the transfer, which undoes the burn.

Repeating the steps creates arbitrary amounts. tbc777.test.ts:747 asserts that the sender keeps escrow after a
transfer, which is the state these steps rely on.

Why not just clear escrow in transfer()/burn()

We tried that first. It isn't enough: in one transaction a holder can call transfer and then deposit. The next
revision then has escrow === E, and the balance drop includes the transfer. It also ran into a lib issue: in the
module-deployed TBC777, assigning this.escrow = undefined while it is already undefined fails deterministically
with mandatory-script-verify-flag-failed (Operation not valid with the current stack size). That broke the
existing test "fast path returns true for same-lineage tokens".

Changes (packages/TBC777/src/tbc777.ts)

The fix binds each deposit to the transition that made it:

  • deposit() records depositFrom = this._rev (the revision being spent) and depositAmount. Repeated deposits
    into the same escrow from the same revision add up.
  • computeDepositAmount credits a listed R only if next(R).depositFrom === R, and at most
    min(R.amount − next(R).amount, depositAmount), floored at 0.
  • The constructor drops escrow, depositFrom and depositAmount from its arguments, and transfer children omit
    them, so only deposit() sets these fields.

Commodity inherits deposit() and the auditor, so it needs no change. transfer and burn are unchanged.

Tests

New tests, the same scenario in both packages ("does not count a transfer / burn after a deposit as a deposit"):

test on staging with this PR
TBC777: transfer after a deposit fails: the claim is accepted ✔
TBC777: burn after a deposit fails: the claim is accepted ✔
Commodity: transfer after a deposit fails: the claim is accepted ✔
Commodity: burn after a deposit fails: the claim is accepted ✔

Existing suites on LTC regtest, with this change:

  • TBC777: 46 passing, 3 failing, 1 pending in the full run. The 3 failures were txn-mempool-conflict,
    bad-txns-inputs-missingorspent and not found by prev, from the node's indexing lag. All 3 passed in two
    reruns, and "fast path returns true for same-lineage tokens" passes.
  • Commodity: 49 passing, 1 failing. The failing test timed out in the suite's mint helper, before any escrow
    code ran, and passed in two reruns.
  • chess-contracts: 21 passing, 1 failing, the same as without the change (too-long-mempool-chain).

Commodity and chess-contracts import TBC777 through its build/, so run npm run build in packages/TBC777
before their tests
. Without that, the two new Commodity tests run against the old auditor and fail. The runs above
used a build/ regenerated from this change, and it isn't part of this PR (see Notes).

Not covered here (for your review)

  • Regression tests for the same-transaction cases (for example, a transfer and then a deposit in one
    transaction). By design the auditor credits at most depositAmount, which doesn't include the transfer, but
    no test in this PR checks it.

  • Under-credits in some unusual honest combinations within one transaction. I found no remaining way to
    over-credit in the cases I worked through, but these cases credit less than was deposited:

    • a deposit followed by a regular withdraw, since the withdraw clears escrow;
    • deposits into two different escrows, since only the last keeps its record;
    • a withdraw or final withdraw alongside a deposit, since the credit is capped by the net drop.

    Recording deposits per escrow would cover these, or the contract could disallow those combinations.
    Which to do is your call.

Notes

  • Tokens already minted keep their code. A token's class code is fixed at mint, so existing TBC777 and
    Commodity tokens keep the old behaviour.
  • build/ is not rebuilt here, so chess-contracts, chess-app and commodity pick up the fix only after a rebuild.
    I can add it to this PR if you'd like.
  • fix(lib): replay reconciliation, author cache, and _root from the running method #521 (fix/security-review) doesn't touch the auditor. This patch applies cleanly to it for tbc777.ts and
    tbc777.test.ts. The Commodity test file conflicts with fix(lib): replay reconciliation, author cache, and _root from the running method #521's changes, and I'll rebase whichever lands second.
    Its re-enabled merge() refuses bags with escrow set. A clean bag could still merge and then deposit in one
    transaction, but the merge raises amount, so the credit is capped by the net drop and by depositAmount. That
    can under-credit but not over-credit. This is reasoning only; no test covers it.
  • fix(TBC777): reject negative escrow claim amounts #524 (negative claim amounts) adds tests at the same place in tbc777.test.ts. The two will
    conflict there, and I'll rebase whichever lands second.

computeDepositAmount credited a listed revision's whole balance drop
whenever the next revision still had escrow set. deposit() sets escrow
and only a regular withdraw clears it, so a later transfer or burn could
be counted as a deposit, and so could a transfer made in the same
transaction as the deposit. That lets an escrow pay out more than it
received, on both TBC777 and Commodity.

deposit() now records the revision it spends (depositFrom) and the
amount (depositAmount). The auditor credits a listed revision only if
the next revision's depositFrom is that revision, and at most the
recorded amount. The constructor and transfer children drop these
fields.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

The new Commodity tests will likely run against stale @bitcoin-computer/TBC777 build output unless packages/TBC777/build/** is regenerated/committed or CI explicitly rebuilds that package first.

Review effort: Lite
Findings: 1 Medium severity · 1 Low severity

Open (2)
What changed in this PR

Fixes an inflation vulnerability in TBC777/Commodity escrow auditing where a later transfer/burn could be miscounted as a deposit if an escrow listed a post-deposit revision, by binding each credited deposit to the specific revision transition that performed deposit().

Changes:

  • Track deposit provenance on-token via depositFrom and depositAmount, and cap credited deposits accordingly.
  • Update escrow deposit auditing (computeDepositAmount) to only credit deposits recorded for that exact transition and never more than the recorded deposited amount.
  • Add regression tests in both TBC777 and Commodity for “transfer/burn after deposit must not be credited as deposit”.
File Description
packages/​TBC777/​src/​tbc777.ts Adds depositFrom/depositAmount, omits them from transfer children, and tightens computeDepositAmount to prevent over-crediting.
packages/​TBC777/​test/​tbc777.test.ts Adds regression tests ensuring transfer/burn after deposit can’t be miscredited as a deposit.
packages/​commodity/​test/​commodity.test.ts Adds analogous regression tests for Commodity’s escrow-deposit behavior.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment on lines +542 to +546
describe('escrow deposits', () => {
// An escrow that records any deposit revision it is given.
class ListEscrow extends Contract {
deposits!: [string, string][]
withdraws!: [string, string, bigint][]
Comment on lines 438 to +441
protected _createTransferToken(to: string, amount: bigint): this {
const ctor = this.constructor as Constructor<this>

// eslint-disable-next-line @typescript-eslint/no-unused-vars
const { _id, _root, _rev, _owners, withdrawn, finalWithdrawn, escrow, ...preserved } = this
/* eslint-disable @typescript-eslint/no-unused-vars */

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 5dde2e5. The build strips comments, so build/ is unchanged.

ClemensLey and others added 4 commits September 28, 2026 16:56
…eposit

Transfer then deposit leaves escrow set and includes the transferred
balance in the drop. The credit stays at the deposited amount for both
TBC777 and Commodity.

@ClemensLey ClemensLey left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for tracking this down and for the fix. Recording the spent revision and the deposited amount, and crediting a listed revision only when it is that transition, is the right way to stop a transfer or burn from being counted as a deposit. That holds when the transfer happens in a later transaction and when it happens in the same transaction as the deposit.

I regenerated packages/TBC777/build, added a same-transaction transfer-then-deposit test for TBC777 and Commodity, and pushed both to this branch. I re-ran the Commodity and TBC777 suites. They pass, including the new test.

The same-transaction cases you described, where a deposit is combined with claim() or withdraw(), or where one transaction deposits into two escrows, can credit less than was deposited. That can lock funds. It does not create supply. I am fine leaving those out of this pull request. A deposit in one transaction and a withdraw in a later one still credits the deposit in full.

@ClemensLey
ClemensLey merged commit 32fce0d into bitcoin-computer:staging Sep 29, 2026
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.

3 participants