Skip to content

feat!: PUTXO-aware bridging - #1136

Draft
erhant wants to merge 28 commits into
devfrom
erhant/private-utxo-offiste
Draft

erhant wants to merge 28 commits into
devfrom
erhant/private-utxo-offiste

Conversation

@erhant

@erhant erhant commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Why

Bedrock is moving to a private UTXO ledger (logos-lips #480 and #481, node PR logos-blockchain#3865). Three things LEZ's bridge relied on are gone:

  • A deposited note stays under the depositor's own key, so the channel's keys can no longer move it. A deposit alone gives LEZ nothing to back L2 tokens with.
  • CHANNEL_TRANSFER and transfer_threshold are removed, so deposits can't be pinned and the committee can't release notes.
  • A withdrawal is posted by the note's holder and waits WITHDRAW_DELAY (86,400 slots).

LEZ will instead hold bridged funds in a vault program: program notes that only a registered Groth16 proof can move. Each LEZ inscription carries a ProgramStep that takes in that block's deposits and pays out that block's withdrawals.

This PR is the tracking branch for that work. It is a draft: the L1 side and the L2 program are built, the wiring between them is not.

How the bridge will work

Deposit, L1 to L2

  1. The holder moves funds into the channel with the node's /channel/deposit. The note stays under the holder's key.
  2. The holder asks the node (/channel/step) for a ProgramDeposit step paying the vault program, with its transfer proof. The step's inscription field carries the L2 recipient, and its intent commits to the vault's committee and that recipient.
  3. The holder hands the step and proof to a sequencer (submitProgramDeposit).
  4. The sequencer checks it and places it in its next inscription, followed by the vault's ProgramStep, which takes the value into a vault note.
  5. The L2 block of that inscription mints the same amount to the recipient, once per deposit. The replay key is the deposit's first input nullifier, which Bedrock lets be spent once.

Withdrawal, L2 to L1

  1. The user sends a bridge Withdraw naming an L1 key. The tokens return to bridge custody on L2 and the program emits a Withdraw event.
  2. The vault's ProgramStep in that block's inscription pays the amount out of vault notes to that key, as a channel note.
  3. The payee releases it to the L1 ledger with /channel/withdraw, after Bedrock's withdraw delay.

Who builds what in a step. zone-sdk builds the program step from a description (the vault notes to consume, the note to keep, the payouts): it derives the nonces, nullifiers, root and Merkle paths, and proves Bedrock's ZkProgramSpend, which covers nullifiers, commitments and value conservation. LEZ adds the vault's own Groth16 proof and the committee's signatures.

The vault's rule, enforced by the registered circuit (lez/vault_circuit) over Bedrock's three public inputs program_step_id, program_deposits_hash and op_id:

  • A threshold of the committee signs the three inputs, so a step is valid for one inscription only.
  • Every vault note consumed names that committee.
  • Vault notes created do not stake and go to the successor committee: the same one, or a new one that also signs (the hand-over).
  • A payout stakes under its payee's key, so vault value is never staked under another's.
  • Every deposit consumed was made out to this committee.

The vault is a set of notes, not one. zone-sdk lets a step consume a program note only once it is four L1 blocks deep, so the note a step creates can't feed the next block's step. Each step consumes whichever spendable notes cover its payouts (at most 4), and a withdrawal can be included only when spendable notes cover it.

State of the branch

The bridge is off: nothing mints from L1 and every withdrawal is refused.

Piece State
zone-sdk on PR 18 (1f95999, node 767cf96); old bridge removed from the sequencer and its store Done
Bedrock test harness on the node's new genesis format (just regenerate-bedrock-settings), test keys and fixture updated Done
Bridge Deposit accepted only in genesis. A later block that debits bridge custody is invalid for every node, which closes the forged-deposit half of #809 Done
Vault circuit, with a demo key from a public seed Done
Vault program registered in the transaction that creates the channel. Its id is the same for every zone, so no config carries it Done
Vault step (VaultStep): describes the step for zone-sdk and proves it Done. Tests run Bedrock's own inscription verification on a deposit and on a payout. Not yet published by the sequencer
Deposit admission (VaultDeposit::admit): decoding, intent, proof Done, not wired to the RPC or the builder
Bridge Withdraw on L2 Done. The block builder refuses every withdrawal for now
Publishing a block with its vault step; minting from admitted deposits; paying withdrawals out of spendable vault notes Next
Checking, when a block is applied, that each mint matches a ProgramDeposit in the block's inscription Not started
Indexer: deposits and payouts from inscription steps Not started
Wallet and FFI: deposit, withdraw to a one-time L1 key, exit status Not started
End-to-end test, with the depositor built from the node's /channel/* calls Not started

Before this can merge

  • Rebase onto dev.
  • CI green.
  • submitProgramDeposit is a todo!() stub; it must call the admission instead.
  • The builder's withdrawal guard is unconditional and marked FIXME; it becomes a check against the spendable vault notes.
  • The withdrawal guard lives in the block builder only. A block from a misbehaving sequencer that includes a withdrawal is still accepted by the others.
  • Bridge Deposit with a zero amount, or paying custody itself, still writes its replay receipt. Two asserts in the program fix it (found in self-review, already possible on dev).
  • The vault program is registered only on the channel-creation path.
  • zone-sdk PR 18 merged, so the pin stops pointing at a branch.

How to review

Commit by commit, in four groups. Hashes are the ones after the rebase.

  1. Removal and migration: 8456106, 367eebd, a8ba3a8, bdc09e9, 3e4b050. Mostly deletions; the sequencer core and its store lose the deposit queue, pinning and withdrawal reconciliation.
  2. Vault, first version: 8a810ef and 29d448a (circuit), 7e49f61 (registration), e68b8e4 (step builder), f7425e4 (deposit admission).
  3. L2 bridge and fixes: ab2a4fb (withdrawals in the bridge program), a52ae71 (interim builder guard), c7cbf7b and 83c8787 (channel view freeze, described under "Test status"), ad94b6c and 0f944fe (self-review fixes), 9de54a3 (CI).
  4. zone-sdk PR 18: f43d54b (pin and harness), ab5c276 (fixture), a6c0f4d (vault step rebuilt on zone-sdk's program inscriptions). a6c0f4d supersedes most of e68b8e4 and reverts the intent salt of ad94b6c: the node's /channel/step chooses the notes a deposit spends, so the depositor can't know a nullifier when it writes the intent.

Open questions

  • Committee for the demo. The plan is 1-of-N: the sequencer publishing a block signs its vault step alone. A real threshold needs the other sequencers to co-sign each inscription before it is published.
  • Genesis supply is not backed on L1. Genesis hands out L2 balances (founding stakes, initial accounts) through Deposits with synthetic ids that no L1 deposit backs, while the vault starts empty. These tokens are indistinguishable from bridged ones, so a genesis holder can withdraw against other people's collateral and the last withdrawers find the vault short by the genesis supply. Refusing a withdrawal the vault can't pay keeps the chain live but is a fractional reserve. Before real funds, the founders must deposit the genesis supply on L1 and the genesis allocations must reference those deposits.
  • Withdraw delay in tests. The harness keeps Bedrock's default channel_withdraw_delay of 86,400 slots, a day at one slot per second. An end-to-end test can't wait for the final release unless the template lowers it.
  • Migration. A program's id is derived from its verification key, so any circuit change is a new program. The first circuit needs a way to move funds to a successor.
  • Sizes. The circuit fits 4 signers, 4 deposits, 4 inputs and 8 outputs per step, so at most 7 payouts per block while the vault keeps a note. The real sequencer set size decides the first.
  • Trusted setup. The circuit needs a phase-2 ceremony before it holds real funds.
  • Liveness. Program notes can't be withdrawn, so sequencers can freeze the vault by refusing steps (logos-lips feat(wallet-ffi)!: mnemonic-based updates #518).

zone-sdk todos

Requests for the zone-sdk team, in order of need.

  • Roots and Merkle paths for a channel's program notes. Done in PR 18: zone-sdk tracks the program notes and builds and proves the program step itself.
  • Export ProgramNote and ProgramNotesView. SequencerHandle::program_notes() returns them, but PR 18 doesn't re-export them, so a caller can't name the type in its own signatures. We copy the fields into a type of our own for now.
  • One transaction carrying a channel config change and an inscription. The vault's committee is named in the vault notes and changes by a hand-over step inside an inscription. If the config change and that inscription share a transaction, the accredited keys approving the new sequencer set approve the hand-over in the same signature: both happen or neither. Today prepare_channel_config and the inscription preparation build separate transactions.
  • Drive the sequencer without the caller polling. next_event does all of zone-sdk's work inside the caller's poll, so a caller that awaits anything slow freezes its channel view (see "Test status"). A background task handing events over a channel would remove the problem for every consumer.
  • Gas estimate for a stepped inscription, to keep a batch under the block gas limit and to price users.
  • Merge PR 18. We pin its head, so a force-push there breaks our build.

Depends on

  • logos-zone-sdk PR 18 (program steps built and proven by the sequencer), on top of the private UTXO integration and program registration branches. None is merged; the pinned revision will move.
  • The node's wallet endpoints for the user side: /channel/deposit, /channel/step and /channel/withdraw.

Test status

Locally: workspace clippy is clean. Unit tests pass for the vault circuit (21), the bedrock actor (36), the sequencer core (177), the executor (59), test_fixtures and devnet_configs. The bridge integration test passes on the new node (3 of 3). The rest of the integration suite and the cucumber suites were not run locally after the bump to PR 18.

CI: it did not run between b521db7 and the rebase, because the branch conflicted with dev. It runs again now. On the first push after the rebase 27 jobs had passed, none had failed, when a newer push superseded the run.

Channel view freeze when publishing is slow

The PUTXO node generates a proof for every fund_tx, so funding a publish can take longer than the 2 s block interval on a slow machine. Before the fix, the sequencer then stopped following the channel and did not recover until restart:

  1. Block production sends a PublishBlock every 2 s. If each takes longer than that, the BedrockActor's mailbox always holds the next one.
  2. zone-sdk only follows the L1 while next_event is polled. The actor did not poll it during funding, and between publishes the waiting PublishBlock won.
  3. No channel update or turn notification reached the sequencer core.

Reproduced locally with sequencer_stake_demo and the Bedrock container limited to 2 CPUs: publishes took 3 s after the second sequencer joined, no channel or turn event arrived for 12 minutes, both sequencers kept publishing on a stale view (539 blocks published, 45 indexed), the config change accrediting the joining key was resubmitted 255 times and never landed, and 187 L1 blocks were empty. It does not happen on dev, where funding needs no proof, nor on a fast machine.

Fix, in two commits:

  • c7cbf7b: the publisher keeps polling zone-sdk while it waits on funding and queues the events.
  • 83c8787: if a queued event moved the channel, the publish is refused as "channel moved" and the turn is skipped. Without this the queued events reached the core after the publish, with checkpoints taken before it, and the store kept the older checkpoint (found in self-review).

With both, at 1.2 CPUs (publishes around 3.8 s) the channel keeps moving, at a cost: 22 blocks published in 195 s with 61 skipped turns, against 33 in 156 s with 34 skips before the second commit. sequencer_stake_demo still fails at that speed on its own 30 s wait for the config change, so some test deadlines may need widening.

Self-review

Four reviewers read the branch against the pinned node and zone-sdk sources. What they found and where it went:

  • An older zone-sdk checkpoint could overwrite a newer one after the freeze fix: fixed in 83c8787.
  • A deposit into an empty vault could create the same note twice, the second unspendable: no longer possible, since zone-sdk now derives those nonces from the publish parent.
  • prove could return a proof Bedrock rejects when given too few, too many or wrong signatures: fixed in ad94b6c.
  • A deposit spending a note twice passed admission: fixed in ad94b6c.
  • The remaining items are listed under "Before this can merge".
  • Found sound: the circuit's hashing against Bedrock's, its signature checks, Withdraw debiting only the signer, and the removal of the old bridge.

🤖 Generated with Claude Code

@erhant erhant self-assigned this Nov 18, 2026
@erhant
erhant force-pushed the erhant/private-utxo-offiste branch from 0fa3d93 to ab5c276 Compare November 20, 2026 12:43
erhant and others added 9 commits November 20, 2026 13:17
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
…s signatures

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
… their vault deposits

Co-Authored-By: Claude <noreply@anthropic.com>
…he vault's intake

Co-Authored-By: Claude <noreply@anthropic.com>
…riber

Co-Authored-By: Claude <noreply@anthropic.com>
…channel

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
event = self.sequencer.next_event() => self.backlog.push_back(event),
}
}
}

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

(Optional). A background driver requirement

What happens today

ZoneSequencer only makes progress inside next_event. Our sequencer owns it inside one actor. That actor's loop alternates between polling next_event and handling messages such as "publish this block":

Publishing means awaiting the node. Since the private UTXO ledger, fund_tx returns only after the node has proven a transfer, and a block with a program step also waits for the spend proof and our program proof. On CI runners we had a median of 5–8 s per publish against a 2 s block interval; a publish with a program step takes 7–13 s locally. While the actor awaits that, it is not in next_event, so the SDK processes no L1 blocks.

Publishing back to back, it never got a turn: the channel view stopped advancing and the zone froze.

What we did about it

  1. Every slow await runs through a helper that keeps polling next_event meanwhile and queues what it returns:

/// Awaits `task` with zone-sdk still followed: the events it raises meanwhile are queued
/// for [`Self::next_event`].
#[expect(
clippy::integer_division_remainder_used,
reason = "Generated by select! macro, can't be easily rewritten to avoid this lint"
)]
async fn following<T>(&mut self, task: impl Future<Output = T>) -> T {
tokio::pin!(task);
loop {
tokio::select! {
biased;
done = &mut task => break done,
event = self.sequencer.next_event() => self.backlog.push_back(event),
}
}
}

It wraps the funding call and the proving task:

// The node proves the fee transfer, which can take longer than a block interval. zone-sdk
// keeps following the channel meanwhile: publishing back to back would otherwise leave it
// no time to, and the channel view would freeze.
let node = self.node.clone();
self.following(async move { node.fund_tx(request).await })

  1. Our own next_event drains that queue before asking the SDK again:

    pub async fn next_event(&mut self) -> Event {
    if let Some(event) = self.backlog.pop_front() {
    return event;
    }
    self.sequencer.next_event().await
    }

  2. Queueing reorders things: an event that arrived during the wait reaches our consumer after the publish it preceded, carrying a checkpoint taken before that publish. Storing it would put an older checkpoint over a newer one. So after funding we look at the queue, and if anything in it moved the channel we abandon the publish and rebuild the block:

/// Refuses a publish when the channel moved while the node funded it. The queued events
/// reach the consumer after the publish would, with checkpoints taken before it, so the
/// block has to be rebuilt on the view they leave.
fn check_backlog(&self, expected_seq: Option<ChannelSeq>) -> Result<()> {
let current = self
.backlog
.iter()
.filter(|event| self.moves_channel(event))
.fold(self.seq, |seq, _| seq.next());
if current == self.seq {
return Ok(());
}
Err(Error::ChannelMoved {
provided: expected_seq.unwrap_or(self.seq),
current,
})
}
/// Whether [`Self::on_blocks_processed`] will hand `event` on under a new channel sequence.
fn moves_channel(&self, event: &Event) -> bool {
let Event::BlocksProcessed {
channel_update,
finalized,
..
} = event
else {
return false;
};
!matches!(channel_update, SdkChannelUpdate::Extension { adopted } if adopted.is_empty())
|| finalized
.iter()
.any(|tx| self.replayed_up_to.is_none_or(|up_to| tx.l1_slot > up_to))
}

What it costs us

Piece 3 throws away finished proofs. Any L1 block that finalizes one of our earlier inscriptions counts as "the channel moved", and with a proof that takes longer than an L1 slot that is most of the time. In our end-to-end deposit test the first vault proof (13 s) was discarded this way and only the second went out.

What would help

If the SDK drove itself in its own task and handed events to us over a channel, pieces 1 and 2 would go away: the SDK would keep up with L1 no matter what the caller is awaiting. Piece 3 is about ordering, and one of these would remove it too:

  • events and publish results delivered on one ordered stream, so a checkpoint is never older than the one before it; or
  • a way to ask for the current checkpoint at any time, so we store the latest one and ignore the ones attached to queued events.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

@erhan btw check out #1137 it changes a bit how we use loop and next_event()

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.

2 participants