A shielded pool is one TSL1 token, spent once a round.

The pool as a TSL1 token

Every link is a spend, and the chain of spends ends at an outpoint that could only be spent once.

TSL1 is a token layout for BSV built from three locking scripts and a witness transaction. PP1 carries the token's header and checks each transfer's structure. PP2 bridges the token transaction to its witness. PP3 holds the value. The witness proves the transfer that created it, and the next transfer can only spend PP3 once that witness exists.

Shieldpool's pool is one such token. Its tokenId is the funding txid of the genesis round. Its mutable header is the pool's state. Each round is one token transfer carrying up to 256 users' transfers at once. Because PP1 walks the parent chain down to the funding outpoint, a copy of the pool's scripts written into some other transaction can be mined but can never be advanced. That matters here: the set of spent notes belongs to one chain, so a cloned chain would be a double spend.

That is the whole design principle. Keep every round small, and put every large thing either in a witness or in a slot transaction whose bytes are pushed once.

Four parties, one path

Wallets and the coordinator exchange a small set of binary messages over ricochet. Each begins with a version byte and a kind byte, and every length is bounded before a byte of the field is read.

Nothing a coordinator says is trusted. A wallet opens its ledger from the descriptor's txids and applies announced rounds itself. An announcement whose header or round number does not match what that round's own PP1 carries is refused, naming the disagreement.

Notes, nullifiers, and the pool header

Inside the pool, money is held as notes. A note records an amount and the key that may spend it. The chain stores only a commitment to each note, a leaf in a depth-32 Poseidon2 tree. When a note is spent its nullifier is published, nf = H(nk, rho), where nk is derived from the spending key. Nobody can link a nullifier to its commitment, and publishing the same one twice is refused.

The pool's whole public state is one 236-byte header, carried as a single push in PP1:

A wallet follows the commitment tree for 32 bytes a round. Because every round owns one aligned block of leaves, a note's lower siblings are fixed when its round is mined, and everything above follows from one block root per round. The wallet folds each block root and checks the result against the cmRoot in a header it proved from the chain, so a block root is safe to take from anyone.

A payment, end to end

Here is what each cloak command does in protocol terms. The files it writes, such as invoices, proofs and acknowledgements, travel between people over whatever channel they already share. None of them goes through the pool.

cloak address --transparent
cloak deposit --amount 5000
cloak sync   # submits once D is mined
cloak sync   # reads the round; note is spendable

# payee
cloak invoice new --amount 1200 --out oranges.invoice
# payer
cloak pay oranges.invoice
cloak sync
cloak proof --invoice 3f9a… --out oranges.proof
# payee
cloak check oranges.proof
cloak ack oranges.proof --out oranges.ack

cloak withdraw --amount 1000 --to mzJ9…
cloak sync

A round's life, as the coordinator runs it

The stages below are the ones the live widget on the front page reports. Timings are for a production round of 256 transfers on one machine with a GPU.

1. assembling

   Intake

   Each submission is checked in cost order and refused at the first failure: it decodes, the transfer agrees with itself, its anchor is in the ring, its nullifiers are unspent and unclaimed, a deposit names the live PP3, withdrawals stay within the balance. The proof is verified last.

   ~18 ms a transfer

2. Close

   Transfers whose anchor left the ring are dropped with an expired reply. The round is padded to its plan size with padding transfers.

   at the deadline
3. proving

   Aggregate

   A recursive prover folds every spend proof into one root proof and computes the next header.

   ~245 s GPU
   ~332 s CPU
4. funding

   Build Y, the round and the witness

   The coordinator funds three transactions, builds each once to size it, then again with exact fees and real outpoints.

   ~9 s

5. Apply to its own ledger

   The coordinator applies the round with a reader's checks before anyone sees it. A transfer that would strand every reader is caught here, while it can still be stopped.

   ~0.7 s
6. broadcast

   Publish

   Y, then the round, then the witness. They chain at zero confirmations and may all land in one block.

   ~4 s

7. Announce and notify

   The announcement goes on the feed. Each submitter is sent its round when it is mined.

   on mining

Close to mined, production: 258 to 261 s measured, of which about 245 s is aggregation. The node validated each round, which runs the verifier, in 914 to 963 ms.

Rounds and witnesses alternate; slot transactions drop in from above

A script is named for the output it locks, and it executes only when a later transaction spends that output. PP3_Nlocks round N's output 3 and runs when round N+1 spends it at input 3. The map keeps those two positions apart: a box's outputs are what it creates, an arrow arriving at a box is what consumes them.

Three relationships appear, and telling them apart is the design. A solid arrow is a spend. A dotted line is a claim: PP3 pins an outpoint the next round must spend, and PP1 certifies what the script at that outpoint actually is. The grey anchor makes a pin impossible until the slot it names is mined.

Six kinds of script, colour-coded throughout

Round 1 and its witness, input by input

After genesis every round has the same five inputs and five outputs. What varies is the tail: a deposit covenant for each deposit from input 5, and from output 5 its receipt and then each withdrawal.

Round 0, the issuance, spends the funding outpoint that becomes the tokenId, and Y_0's anchor. Round 2 has the same five inputs one round on, and pays a 300-satoshi withdrawal at output 5 as PP3 steps from 501 to 201.

Three scripts, none sufficient alone

PP1 on round N+1's output 1 does not run when that round is mined. It runs later, when witness N+1 spends it, by which time the round's withdrawals are already spendable. So PP1 can never gate its own round's money, and the gate is V, in the same transaction as the payout.

PP3 supplies the timing and PP1 supplies the sight. The ordering holds because round N+2 spends witness N+1's output 0, so the certificate always exists before the pin it describes is tested.

Wallets prove their spends; the coordinator folds them

What a coordinator can and cannot do

A round can only be mined if V accepted it. The design's failure mode for a dishonest coordinator is that the pool stops, not that funds move. Withdrawals a round already paid stay paid even if the pool is never advanced again.

The slot transaction Y is the one piece built outside a round, so it was attacked on its own:

What is real today

• The verifier is real at both scales. Removing any one of its checks lets that check's attack through. A regtest node accepted production rounds running V in 914 to 963 ms, against its 1,000 ms limit for a non-standard transaction. That is the thinnest margin in the system.
• Rounds need relaxed node policy. Every witness's PP1 unlock is larger than the default 500,000-byte maxscriptsizepolicy, and production witnesses go in over node RPC because ARC cannot yet parse scriptSigs that large.
• Deposits, payments and withdrawals are built end to end, through the coordinator, over protocol version 3, on a regtest chain at both scales.
• Wallet restore from seed alone is not built. Back up the wallet directory.
• Nothing here has been audited. Use amounts you can afford to lose.

The full design record, with every measurement and the reasoning behind each choice, is docs/ZK_SHIELDED_POOL_TSL1_DESIGN.md in tstokenlib.