On this page
- §0 The area in one paragraph
- §1 Bridge coins
- §1a Custody accounts and open withdrawals
- §2 Attesters and the quorum
- §3 A bridge attestation
- §4 Deposit resolution and the mint
- §5 The withdrawal trigger: its checks and the request row
- §5a A custody account receives nothing else
- §6 Withdrawal resolution and the burn
- §7 The idle window and the one-shot guards
- §8 The API views (local)
- §9 The keeper and its supervisor (local)
- §10 Foreign-signed carriers: the chain bindings and the once-only rule
- §11 Consensus and local; summary of defects
34 — The multichain bridge, on-chain side: bridge coins, deposit attestations and mints, withdrawal requests, attestations and burns, foreign-signed carriers
Out of scope the execution of AttestEvent and the generic oracle tally it feeds (17); TransferToken's own execution (14) and the token tables (14, 07); survival mode itself (36 §12); the parsing and signature verification of a foreign-signed carrier (02 §9) and its admission (04); everything on the foreign chains (watchers, the custody multisig, EIP-712 and Bitcoin signing): programs of the keeper, not of the node
§0 The area in one paragraph
The bridge lets a foreign asset (bitcoin, ether, an ERC-20) appear on ZooBC as a wrapper token and leave again, and the node's part of it is small and built from pieces other documents specify: four genesis tokens carry a foreign custody address in the bridge_coin table (never written after genesis), and each of them has a ZooBC custody account the chain derives from its token id and no key signs for; registry nodes vote with ordinary AttestEvent transactions (fee-free duties from their node keys) whose event id begins with one of two reserved prefixes; at the end of every block two steps tally those votes over the counted registered nodes of the registry with a two-thirds supermajority (every counted registered node for a deposit above the day's mint cap) and, once, mint the agreed amount of the agreed token to the agreed recipient (a deposit) or burn the agreed amount from the custody account a user's own executed transfer paid (a withdrawal), each leaving a result row that makes the event final. A withdrawal starts only from a withdrawal request row that the executed transfer writes when it credits custody: a transfer that was mined but became a paid no-op writes none, so the keepers attest executed credits and never transaction rows. The transfer itself must be a well-formed withdrawal: of a coin whose release exists (in this release only the Ethereum native coin, ZETH), without an escrow, sent to that coin's custody account and naming a destination the coin's chain can be paid at; every other transaction that would name a custody account is refused, so a custody account receives withdrawals of its own coin and nothing else. While the chain is in survival mode no attestation can be mined and neither resolution step runs (pending events resolve at the first block after it ends, their idle window counting only the heights outside it). The node does not watch any foreign chain, computes no foreign signature and charges no bridge fee; it consults the bridge_coin table to judge withdrawals and custody accounts, to refuse a mint to a custody account and for the API views. A supermajority of the registry can mint any existing token to any account that can hold tokens (a custody account excepted), and a withdrawal can only burn what a credited request row says. What the keepers emit (event ids, value strings, the custody account they watch, the foreign release id they sign only once the burn's result exists) is a convention of the reference keeper that an implementation's keeper must share to reach quorum with the others; what the node does with it is the consensus specified here. A second, unrelated way across is the foreign-signed carrier: a transaction whose message carries a native Ethereum, Bitcoin or Solana transaction signed by the foreign key (02 §9); §10 states the bindings that tie such a carrier to this chain and the once-only rule.
§1 Bridge coins
Purpose. The wrapper tokens and the foreign custody address each one is backed at.
Inputs. The genesis_tokens of the genesis file (06): a token with a non-empty chain and a non-empty deposit_address is a bridge coin; asset empty means native; decimals is the token's (default 8).
Output and effect. One row per bridge coin in the table bridge_coin: token_id (64-bit integer, the key), symbol (text), chain (text), asset (text), deposit_address (text), decimals (integer); not versioned, written by the builder at height 0 through the same writer the node uses, never written afterwards (07; it travels whole in a snapshot, 26). The custody binding is part of the chain identity: chain, asset and deposit_address of every genesis token are committed to the config hash (06), so a node built with another custody address has another genesis hash and is refused at handshake. The rows are read by the withdrawal and custody checks of every transaction (§5, §5a), by the deposit step's custody refusal (§4) and by GET /api/v1/bridge/coins (§8); no burn consults them.
How to compute it. Copy the rows below; a new chain derives them from its genesis file by the rule above.
Rule activation. None.
Rejections and errors. None.
Vector. computed (the TestNet and DevNet genesis files, whose 14 genesis tokens are the same, 32 §15; ids are positional, 1–14):
| token_id | symbol | chain | asset | deposit_address | decimals |
|---|---|---|---|---|---|
| 4 | ZBTC | bitcoin | native | bc1q02eahpuu87g85zka8eapmwzc0rv56yw2s226c4 |
8 |
| 5 | ZETH | ethereum | native | 0x9A080FFFE4105361b023220bD21Be0B9418E908e |
8 |
| 13 | ZUSDC | ethereum | 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 |
0x9A080FFFE4105361b023220bD21Be0B9418E908e |
8 |
| 14 | ZUSDT | ethereum | 0xdAC17F958D2ee523a2206206994597C13D831ec7 |
0x9A080FFFE4105361b023220bD21Be0B9418E908e |
8 |
The other ten genesis tokens name a chain but no deposit address and have no row. Supplies at height 0 (computed from the stipends of 32 §15: the treasury and the market maker each 10,000,000,000 ZBTC units, 100,000,000,000 ZETH, 10,000,000,000,000 ZUSDC and ZUSDT; 25 other accounts one tenth of each): ZBTC 45,000,000,000, ZETH 450,000,000,000, ZUSDC 45,000,000,000,000, ZUSDT 45,000,000,000,000 (each persist_height 0, unbacked 1) until a mint or burn changes them.
Test cases · §1
2 cases · 2 valid · 2 reference
The four bridge coins of the TestNet and DevNet genesis files
token_id, symbol, chain, asset, deposit_address, decimals; the other ten genesis tokens name no deposit address and have no row.
A stated value: there is nothing to compute. A compatible node shows the same value.
- 4
ZBTC bitcoin native bc1q02eahpuu87g85zka8eapmwzc0rv56yw2s226c4 8- 5
ZETH ethereum native 0x9A080FFFE4105361b023220bD21Be0B9418E908e 8- 13
ZUSDC ethereum 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 0x9A080FFFE4105361b023220bD21Be0B9418E908e 8- 14
ZUSDT ethereum 0xdAC17F958D2ee523a2206206994597C13D831ec7 0x9A080FFFE4105361b023220bD21Be0B9418E908e 8
The four bridge coins' supplies at height 0
The treasury and the market maker each hold 10,000,000,000 ZBTC units, 100,000,000,000 ZETH and 10,000,000,000,000 ZUSDC and ZUSDT; 25 other accounts one tenth of each.
A stated value: there is nothing to compute. A compatible node shows the same value.
- ZBTC
45000000000- ZETH
450000000000- ZUSDC
45000000000000- ZUSDT
45000000000000
Defects to match. A mint never checks that its token is a bridge coin (§4).
§1a Custody accounts and open withdrawals
Purpose. The ZooBC account each bridge coin's withdrawals are sent to, and whether withdrawals of the coin are open in this release.
Inputs. The bridge_coin rows (§1): token_id, symbol, chain, asset.
Output and effect. Rule bridge_withdrawal_credit. The custody account of the coin with token id T is the 36-byte typed account 00000000 ‖ SHA3-256("ZBC-BRIDGE-CUSTODY" ‖ T as 8 bytes little-endian) (the 18 ASCII bytes of the domain, then the id in two's complement: a 26-byte preimage). Its 32 bytes after the type are a hash output, so no private key is known for them and no transaction can ever be signed from it: what it holds leaves only through the burn of §6. It is written as text like any type-0 account (01, prefix ZBC). The name of a coin is its symbol, or token <id> when the symbol is empty. A coin's withdrawals are open when its chain in lower case is ethereum and its asset in lower case is native (the one foreign release the keepers make: native ether, §9); otherwise they are closed, with the reason withdrawals of <name> are not open: no release of an ethereum token contract exists in this release for any other asset on ethereum, and withdrawals of <name> are not open: no release to <chain in lower case> exists in this release for every other chain (its chain in place of an empty chain).
How to compute it. As stated.
Rule activation. bridge_withdrawal_credit, active from height 0 on every chain.
Vector. computed (the four bridge coins of the shipped genesis files):
| token_id | symbol | preimage (hex, 26 bytes) | custody account | text form | open |
|---|---|---|---|---|---|
| 4 | ZBTC | 5a42432d4252494447452d435553544f44590400000000000000 |
000000009c12546254570a0b0cf128e9b70f20c7a61a625dbce7a6dec7b873f6e458bff1 |
ZBC_TQJFIYSU_K4FAWDHR_FDU3ODZA_Y6TBUYS5_XTT2NXWH_XBZ7NZCY_X7YUFPFA |
no: withdrawals of ZBTC are not open: no release to bitcoin exists in this release |
| 5 | ZETH | 5a42432d4252494447452d435553544f44590500000000000000 |
00000000b070ddf68c3270c38319c7c4c76166a2c76d8e9a75c368c6769d0fe5cf4f4df2 |
ZBC_WBYN35UM_GJYMHAYZ_Y7CMOYLG_ULDW3DU2_OXBWRRTW_TUH6LT2P_JXZAEBCI |
yes |
| 13 | ZUSDC | 5a42432d4252494447452d435553544f44590d00000000000000 |
000000006326c1035c60736d62fcd27ae9e9807c9a60bf1e4be16c784b2757799067778f |
ZBC_MMTMCA24_MBZW2YX4_2J5OT2MA_PSNGBPY6_JPQWY6CL_E5LXTEDH_O6H75IJY |
no: withdrawals of ZUSDC are not open: no release of an ethereum token contract exists in this release |
| 14 | ZUSDT | 5a42432d4252494447452d435553544f44590e00000000000000 |
00000000a3de97bbe2310df7e069a32c109cc1e726fc0eff8073e10d21a00777458bae5e |
ZBC_UPPJPO7C_GEG7PYDJ_UMWBBHGB_44TPYDX7_QBZ6CDJB_UADXORML_VZPD4DXZ |
no: withdrawals of ZUSDT are not open: no release of an ethereum token contract exists in this release |
INVALID INPUT: a withdrawal of ZBTC (§5) → TransferToken: withdrawals of ZBTC are not open: no release to bitcoin exists in this release; a transfer of anything else to ZBC_WBYN35UM_GJYMHAYZ_Y7CMOYLG_ULDW3DU2_OXBWRRTW_TUH6LT2P_JXZAEBCI → refused (§5a).
Test cases · §1a
5 cases · 5 valid
The custody account of ZBTC (token 4)
Loading the test widget…
The custody account of ZETH (token 5), whose withdrawals are open
Loading the test widget…
The custody account of ZUSDC (token 13)
Loading the test widget…
The custody account of ZUSDT (token 14)
Loading the test widget…
A coin with no symbol on another chain is named by its id and closed
Loading the test widget…
Defects to match. None.
§2 Attesters and the quorum
Purpose. Who may vote on a bridge event and how many votes it takes, the same for deposits and withdrawals.
Inputs. The counted registered nodes at height H − 1 (every Registered row at or below H − 1 that is not suspended, 36 §4); the rows bridge_quorum_num / bridge_quorum_den (2 / 3 on both chains, 32 §12; compiled 2 / 3 when a row is missing); min_registry_size (7 on the TestNet, 3 on the DevNet).
Output and effect. In order, both steps:
- Registry floor (rule
quorum_floor): the counted registered nodes must be at leastmax(3, min_registry_size)nodes and that many distinct owners (ABSOLUTE_MIN_REGISTRY3). If not, the step returns without resolving any event. authorized= for each counted registered node, the attester account00000000 ‖ node_public_key(36 bytes; a row whose key is not 32 bytes is skipped). An empty set ends the step.quorum = ⌈size × num / den⌉computed as(size × num + den − 1) div denin u32, withden = 0 → size, and a result of 0 → 1, over the same counted set (a suspended registered node neither attests nor sits in the denominator). The bridge steps always use the counted registered nodes: unlike the generic oracle (17), they do not consultoracle_full_registry_quorum.- Mint cap (rule
governance_window): for a deposit, the leading value is read first (the value the most live attestations byauthorizedcarry, the smaller string on a tie); when it parses as<token_id>:<amount>:…with a non-zero token id and the token's mints of the last 5,760 blocks (the amounts of the deposit result rows naming that token withresolved_height>H − 5,760, or > 0 whileH≤ 5,760) plusamountexceed the cap — the larger of 100,000,000 units and 10 % of the token's supply before the mint,⌊supply / 10,000⌋ × 1,000 + ⌊(supply mod 10,000) × 1,000 / 10,000⌋— the quorum is every counted registered node (size).
An attester outside the set is ignored, not refused. Because every attester has at most one live row per event (§3) and the quorum exceeds half the set, two different values can never both reach it. A failed read (the previous block, the counted registered nodes, the unresolved events, the day's mints, a token, a resolver's storage) refuses the block; a refusal the rules define is logged and the step goes on.
How to compute it. As stated.
| counted registered nodes | quorum (2 / 3) |
|---|---|
| 1 | 1 |
| 2 | 2 |
| 3 | 2 |
| 4 | 3 |
| 5 | 4 |
| 6 | 4 |
| 7 | 5 |
| 8 | 6 |
| 9 | 6 |
| 10 | 7 |
| 11 | 8 |
| 12 | 8 |
| 13 | 9 |
| 20 | 14 |
| 100 | 67 |
Rule activation. quorum_floor, governance_window, active from height 0 on every chain.
Rejections and errors. None (an empty set or a floor not met makes the step do nothing).
Vector. computed: the table; with the 11 genesis registered nodes of either chain registry_size 11 and quorum 8 (GET /api/v1/bridge/withdrawals/<trigger> of a recorded request answers "registry_size":11,"quorum":8,"quorum_num":2,"quorum_den":3); with min_registry_size 7, a TestNet with 6 counted registered nodes resolves no bridge event.
Test cases · §2
17 cases · 17 valid · 1 reference
1 counted registered node needs 1
Loading the test widget…
2 counted registered nodes need 2
Loading the test widget…
3 counted registered nodes need 2
Loading the test widget…
4 counted registered nodes need 3
Loading the test widget…
5 counted registered nodes need 4
Loading the test widget…
6 counted registered nodes need 4
Loading the test widget…
7 counted registered nodes need 5
Loading the test widget…
8 counted registered nodes need 6
Loading the test widget…
9 counted registered nodes need 6
Loading the test widget…
10 counted registered nodes need 7
Loading the test widget…
11 counted registered nodes need 8
Loading the test widget…
12 counted registered nodes need 8
Loading the test widget…
13 counted registered nodes need 9
Loading the test widget…
20 counted registered nodes need 14
Loading the test widget…
100 counted registered nodes need 67
Loading the test widget…
Six counted registered nodes on TestNet resolve no bridge event
Loading the test widget…
The quorum a recorded request's withdrawal view shows with the 11 genesis registered nodes
A stated value: there is nothing to compute. A compatible node shows the same value.
- registry_size
11- quorum
8- quorum_num
2- quorum_den
3
Defects to match. None.
§3 A bridge attestation
Purpose. The transaction a keeper sends to vote, and what makes it a bridge attestation to the admission gate.
Inputs. An AttestEvent (type 17) whose body is id_len (uint32 LE) ‖ event_id ‖ val_len (uint32 LE) ‖ value (17; each length ≤ 4,096, event_id non-empty); the sender; the survival flag of the block it lands in (36 §12).
Output and effect. The transaction is a bridge attestation when: the body has ≥ 4 bytes; len = uint32 LE of bytes 0–3 satisfies 1 ≤ len ≤ 200 (BRIDGE_DEPOSIT_EVENT_ID_MAX); 4 + len ≤ the body length; and the len bytes from offset 4 begin with the ASCII ZBRDEP1: (deposit) or ZBWDR1: (withdrawal). Such a transaction is admitted only when its sender is a typed node-key account 00000000 ‖ key (36 bytes) of a node the registry knows (its latest version at the tip, whatever its status), else "Bridge attestation must be signed by a registered node" (04). An AttestEvent is a fee-free duty (rule duty_fee_free): its minimum fee is 0, it must declare fee == 0 (else "Transaction fee must be exactly 0: a node duty declares a fee of exactly zero (this one declares <fee>)") and be sent by a registry attester account (the node's own key), else "a fee-free duty transaction must be sent by a registry attester account (the node's own key)". While the survival flag of the block it would land in is true, an AttestEvent (the whole bridge category) is refused at admission and makes a block that carries it invalid (36 §12); a blocksmith holds admitted ones in its pool for the first block after survival mode ends. Execution is 17's: one versioned row oracle_attestation(event_id, attester = the sender as presented, value, block_height, latest) keyed on (event_id, attester, block_height), a later attestation by the same account becoming the live row (latest) and retiring the earlier one, so every tally and every read sees one row per attester; under oracle_registered_only a sender that is not an attester account of the counted registry is a paid no-op.
The event id beyond the prefix is free text to the chain. The conventions of the reference keeper, which an implementation's keeper must reproduce byte for byte to count towards the same event: deposit event_id = ZBRDEP1:<chain>:<ext_txid>:<log_index>, value = <token_id>:<amount>:<recipient_hex> (the recipient's 36-byte account in lower-case hex, the amount in the token's base units: for an Ethereum deposit the whole units of its wei, §9); withdrawal event_id = ZBWDR1:<trigger_tx_hash_hex>, value = <token_id>:<amount>:<dest>| followed, once the burn has resolved, by R<result height>|<foreign_signature_hex> (§9): the keeper's first attestation carries nothing after the |.
How to compute it. Body = uint32 LE(len(id)) ‖ id ‖ uint32 LE(len(value)) ‖ value; the envelope of 03.
Rule activation. duty_fee_free, oracle_registered_only, survival_mode (the freeze), active from height 0 on every chain.
Rejections and errors. The admission strings above, 17's three stateless ones, and in survival mode 36 §12's SurvivalMode: … strings.
Vector. computed.
- INPUT: a deposit attestation for the Ethereum transaction
0x‖ab× 32, log index 0, minting 1 ZETH (100,000,000 base units of token 5) to the account00000000‖30ceb2c6× 8 (36 bytes). - EXPECTED OUTPUT:
event_id=ZBRDEP1:ethereum:0xabababababababababababababababababababababababababababababababab:0(85 bytes);value=5:100000000:0000000030ceb2c630ceb2c630ceb2c630ceb2c630ceb2c630ceb2c630ceb2c630ceb2c6(84 bytes); body (177 bytes) =550000005a4252444550313a657468657265756d3a3078616261626162616261626162616261626162616261626162616261626162616261626162616261626162616261626162616261626162616261626162616261623a3054000000353a3130303030303030303a303030303030303033306365623263363330636562326336333063656232633633306365623263363330636562326336333063656232633633306365623263363330636562326336; it is a bridge attestation (85 ≤ 200, prefix present). - INVALID INPUT: the same transaction sent with fee 1 →
Transaction fee must be exactly 0: a node duty declares a fee of exactly zero (this one declares 1)(04); sent by an account that is not a registered node's typed key account →Bridge attestation must be signed by a registered node; sent while the next block's survival flag is true →SurvivalMode: transaction type 17 is not accepted while fewer than survival_min_producers distinct producers made the last 120 blocks (survival mode: governance and bridge are frozen until N produce again).
Test cases · §3
4 cases · 1 valid · 3 invalid
A deposit attestation minting 1 ZETH
Loading the test widget…
The same attestation with a fee of 1
Loading the test widget…
The same attestation from an account that is no registered node
Loading the test widget…
The same attestation while the next block's survival flag is true
Loading the test widget…
Defects to match. None.
§4 Deposit resolution and the mint
Purpose. Turn a supermajority of deposit attestations into wrapper units, once per event.
Inputs. Block H (H ≥ 1); the live attestation rows; the result rows; authorized and quorum of §2 at H − 1; the candidates of §7.
Output and effect. While the survival flag of block H is true (36 §12) this step does not run at all: no candidate is tallied, nothing is minted, and the attestations already on chain stay pending; they are tallied at the first block whose flag is false. Candidates: every event id that has at least one live attestation, no result row, a newest attestation within the idle window (§7), and the prefix ZBRDEP1:. For each candidate, in whatever order the database lists them (the effects commute):
- Evaluate: the event's live attestation rows are read in
(block_height, attester)order; rows by an attester outsideauthorizedare skipped; the count of each exactvaluestring is kept; the first value whose count reachesquorum(two thirds of the counted registered nodes, or every counted registered node above the mint cap, §2) is the resolved value; no value at quorum → nothing changes. - Parse the resolved value as
<token_id>:<amount>:<recipient_hex>at the first two colons (both must exist);token_idandamountas signed 64-bit decimal integers (leading blanks and one sign are accepted, trailing text after the digits is ignored, no digits → malformed); the recipient hex must be non-empty, of even length and strict hex (0-9,a-f,A-Fonly), and the decoded recipient must be a valid account that can hold tokens (an account of a signing type,01) and not a full-key account form (rulecanonical_account_forms,01: an Ethereum or Tron type followed by a 64-byte key, a Bitcoin legacy, P2PKH or P2WPKH type followed by a 33- or 65-byte key, a form no transaction can ever be sent from), and not the custody account (§1a) of any bridge coin (rulebridge_withdrawal_credit: a custody account receives only withdrawals);amount> 0; the token's latest version must exist (any token,14: a genesis coin or a user token;bridge_coinis not consulted);total_supply + amountand the recipient's balance +amountmust fit in i64. - Mint: a new token version at
Hwith the new supply (14); a new token-balance version of the recipient (of its group when the recipient is a group member,18) atHwithbalanceandspendable_balance+=amount(07), written directly — neither the recipient's split policy nor its transact policy (08) is applied. No ledger row is written. - Only then the result row
oracle_result(event_id, value, resolved_height = H): the event is final. A refusal in step 2 or 3 (rulebridge_withdrawal_credit) writes no result row: the event stays pending, the refusal is logged ("Bridge deposit <id> refused: …"), and a later attestation that reaches quorum on a correct value resolves it.
How to compute it. 0. If the survival flag of H is true: stop. 1. The candidates (§7). 2. Per event: evaluate; parse; mint; write the result row. 3. On a rule refusal: stop for this event (nothing written); on a storage fault: the block is refused.
Rule activation. bridge_withdrawal_credit (the result row after the mint), survival_mode (the pause), canonical_account_forms (no mint to a full-key form: the deposit waits), bridge_withdrawal_credit also for the custody refusal (no mint to a custody account: the deposit waits); §2's rules; all active from height 0 on every chain.
Rejections and errors. Nothing the attesters send refuses the block (a storage fault does). Logged only: "Bridge deposit: malformed resolved value", "… bad token/amount", "… bad recipient hex", "Bridge deposit: recipient address cannot hold tokens", "Bridge deposit: recipient: a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms)", "Bridge deposit: the recipient is the custody account of <name>, which receives only withdrawals", "Bridge mint amount must be > 0", "Bridge mint: unknown token", "Bridge mint: supply overflow", "Bridge mint: recipient balance overflow".
Vector. computed (the attestation of §3, 11 counted registered nodes, the mint within the day's cap): the eighth distinct registry attester carrying exactly that value resolves the event in the block that mines its attestation; token 5's supply becomes 450,000,000,000 + 100,000,000 = 450,100,000,000 in a new version; the recipient's ZETH balance rises by 100,000,000; the result row holds the value. The day's cap for ZETH is max(100,000,000, 10 % of 450,000,000,000) = 45,000,000,000 units: a first mint of 50 ZETH (5,000,000,000 units) within 5,760 blocks needs two thirds (8 of 11); a mint of 500 ZETH (50,000,000,000 units) needs all 11. INVALID INPUT: eight attesters agreeing on 99:100000000:0000000030ceb2c6… (token 99 does not exist) → Bridge mint: unknown token logged, no result row, the event pending; eight later attestations on the §3 value resolve it. INVALID INPUT: eight attesters agreeing on 5:100000000:040000002c67e6ec6aa795e8ae01447ac9f3a57616dc2cf17ddbe367d8dfc564e923c1e268487e15e10d153c32c41a2820a383628098d155fc6eefb44ba37e93e99f05f1 (type 4 followed by the 64-byte key of the Ethereum private key of 33 §3, 68 bytes: the full-key form of the account 040000003bc64c92d9bb1c5826643b081108b892e2e7f590) → Bridge deposit: recipient: a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms) logged, nothing minted, no result row; the event waits for a quorum on a value that names 040000003bc64c92d9bb1c5826643b081108b892e2e7f590. INVALID INPUT: eight attesters agreeing on 5:100000000:00000000b070ddf68c3270c38319c7c4c76166a2c76d8e9a75c368c6769d0fe5cf4f4df2 (ZETH's custody account, §1a) → Bridge deposit: the recipient is the custody account of ZETH, which receives only withdrawals logged, nothing minted, no result row.
Test cases · §4
9 cases · 6 valid · 3 invalid
The eighth of eleven attesters resolves the deposit and mints
Loading the test widget…
Seven attesters are not enough
Loading the test widget…
A first mint of 50 ZETH in 5,760 blocks needs two thirds
Loading the test widget…
A mint of 500 ZETH needs every counted registered node
Loading the test widget…
Eight attesters agreeing on token 99, which does not exist
Loading the test widget…
Eight later attestations on the correct value resolve the same event
Loading the test widget…
Eight attesters agreeing on the 68-byte full-key form of an Ethereum account
Loading the test widget…
Eight attesters agreeing on ZETH's custody account as the recipient
Loading the test widget…
The same deposit naming the 20-byte address of that key resolves
Loading the test widget…
Defects to match. (1) Any existing token can be minted by a registry supermajority (to any account that can hold tokens but a custody account): the chain trusts the registry entirely. (2) The mint bypasses the split and transact policies, unlike every transaction credit (08). (3) GET /api/v1/bridge/deposits/:event_id (§8) shows the refusal a pending event is stuck on.
§5 The withdrawal trigger: its checks and the request row
Purpose. The user's own on-chain request to leave: what makes a transfer a withdrawal, when one is valid, and the executed transfer a withdrawal attestation must match.
Inputs. A TransferToken (type 11, 14) of a bridge coin from the user to that coin's custody account (§1a), with the message field (03) set to the ASCII ZBW1| followed by the foreign destination address exactly as the user wants it paid, and nothing else (no chain name, no space; BRIDGE_WITHDRAWAL_MEMO = ZBW1|); the bridge_coin rows.
Output and effect. A transaction is a withdrawal when it is a TransferToken whose body has at least 8 bytes and whose message begins with ZBW1| (ZBW1| alone included). Under rule bridge_withdrawal_credit a withdrawal is valid only when it passes the checks below, which are part of the stateless validation (03 §3, 19 §2): a refused one is refused at admission, and a block that carries one is invalid. They run after the envelope's account-form checks and before the version and body checks of 03 and 14. A valid withdrawal then executes exactly as 14: the units move to the recipient, the fee is paid, the message is stored with the transaction. In addition (rule bridge_withdrawal_credit), when the transfer credited the recipient — never when it ended as a paid no-op — and its message is longer than ZBW1| and begins with it, the executor writes one versioned row to bridge_withdrawal_request: trigger_hash = the transaction's hash (32 bytes), custody_address = the recipient's balance holder (the recipient itself, or its group when the recipient is a group member, 18), token_id, amount (the body's), destination = the message after ZBW1| (text), block_height = the block, latest = 1; the key is (trigger_hash, block_height), an older row of the same trigger loses latest, a pop-off deletes the rows above the target and restores latest on the newest remaining row; nothing prunes the table. Because only a valid withdrawal reaches a block, a request row exists only for an open coin's custody account. (A MultiSignature cannot carry a TransferToken as its inner transaction, 12, and an escrowed TransferToken cannot be a withdrawal, so no other path writes one.) A row is refused (the block fails on this node) only when its fields are incomplete (an empty destination or a non-positive amount cannot occur past 14's checks). The table is a snapshot state table (26): the newest row per trigger at or below the snapshot height travels. The row records the body's amount (a custody account can hold no split policy: nothing may name it, §5a). The reference keeper reads the executed rows through GET /api/v1/bridge/withdrawal-requests?custody= (§8), acts only on rows at or below the chain's finalized height (finalized: true; rule checkpoint_finality), so a request a reorganisation could still remove is not voted on; this is keeper policy (local). It takes each coin's custody account from GET /api/v1/bridge/coins (custody_account, §8) and ignores rows of any other custody; it derives a multisignature account of its configured participants and threshold (node-local configuration) only for a token the chain names no custody for.
How to compute it. 14 for the body (token_id LE i64 ‖ amount LE i64 ‖ optional fields); 03 for the message (the plain-message cap applies, so the destination is at most the cap minus 5 bytes). The checks of a withdrawal, in order (a chain whose bridge_coin table is empty refuses every withdrawal at step 1):
- The token id = body bytes 0–7 as i64 LE; it must be a bridge coin (§1), else
TransferToken: a message starting ZBW1| is a withdrawal, and token <id> is not a bridge coin, so it has none. - Its withdrawals must be open (§1a), else
TransferToken:‖ the coin's closed reason. - No escrow part, else
TransferToken: a withdrawal cannot carry an escrow (its approval would put the tokens in custody with no withdrawal request). - The envelope recipient must equal the coin's custody account, else
TransferToken: a withdrawal of <name> is sent to its custody account <its ZBC_ text form>, and this one is not. - The destination
D(the message bytes afterZBW1|) is judged against the coin'schain(compared in lower case), the first failing line giving the reason: (a)Dempty →the withdrawal names no destination; (b) a byte outside 0x21–0x7E, or a|→a destination is printable ASCII with no space and no '|'(the attestation value splits at the first|, §6); (c) chainethereum(also spelledethorevm) orbsc: whenDis longer than 2 bytes and begins0xor0Xthat prefix is dropped, and the rest must be exactly 40 hex digits, elsean Ethereum destination is 0x and 40 hex digits (a 20-byte address); when those 40 digits hold both a lower-case letter (a–f) and an upper-case one (A–F) they carry an EIP-55 checksum: withk= Keccak-256 of the 40 digits in lower case (40 ASCII bytes), the letter at positioni(0-based) must be upper case exactly when nibbleiofk(the high nibble of bytei div 2for eveni, the low nibble for oddi) is 8 or more, elsethe Ethereum destination is in mixed case, so it carries an EIP-55 checksum, and the checksum does not match: a character is wrong(all lower or all upper case is plain hex and carries none); (d) chainbitcoin(orbtc):Dmust read as a Bitcoin address, a Base58Check value of 21 bytes with version00or6F(P2PKH) or05orC4(P2SH), or a bech32/bech32m address with prefixbc1,tb1orbcrt1and witness version 0 with a 20- or 32-byte program or version 1 with a 32-byte one, elsea Bitcoin destination is a Bitcoin address with a valid checksum (1..., 3..., bc1...); (e) chainsolana(orsol):Dmust be base58 of exactly 32 bytes, elsea Solana destination is the base58 form of a 32-byte key; (f) any other chain: (a) and (b) only. A reason refuses withTransferToken: the withdrawal destination cannot be paid on <chain as stored>: <reason>. Step 2 closes every coin but one whose chain isethereumand assetnativebefore step 5 is reached, so in this release only (a)–(c) can answer, for the chainethereum; lines (d)–(f) are the format a release to those chains will be held to. - The custody check of §5a (a withdrawal's own recipient is not judged by it).
Then the execution and the request row as stated.
Rule activation. bridge_withdrawal_credit (the checks and the request row), active from height 0 on every chain.
Rejections and errors. The texts of steps 1–5 (stateless: refused at admission, a block invalid), then 14's.
Vector. computed. INPUT: a withdrawal of 1 ZETH to 0x9A080FFFE4105361b023220bD21Be0B9418E908e, sent to ZETH's custody account 00000000b070ddf68c3270c38319c7c4c76166a2c76d8e9a75c368c6769d0fe5cf4f4df2 (ZBC_WBYN35UM_GJYMHAYZ_Y7CMOYLG_ULDW3DU2_OXBWRRTW_TUH6LT2P_JXZAEBCI, §1a). EXPECTED OUTPUT: TransferToken body 050000000000000000e1f50500000000 (token 5, amount 100,000,000, each int64 LE); message (47 bytes) 5a4257317c307839413038304646464534313035333631623032333232306244323142653042393431384539303865 (ZBW1|0x9A08…908e); the destination is in mixed case and its EIP-55 checksum holds (Keccak-256 of 9a080fffe4105361b023220bd21be0b9418e908e = ad485bcbd57f47714bbe77a187ae1092d598ef94011e66039e16679fb012776e), so the withdrawal passes; the same destination all in lower case, all in upper case or without 0x passes too; mined at 10,000 and credited, the row (trigger_hash = its hash, custody_address = 00000000b070ddf68c3270c38319c7c4c76166a2c76d8e9a75c368c6769d0fe5cf4f4df2, 5, 100000000, "0x9A080FFFE4105361b023220bD21Be0B9418E908e", 10000, 1). INVALID INPUT, each the same transfer changed in one point: the destination 0x9a080FFFE4105361b023220bD21Be0B9418E908e (its first letter lower case) → TransferToken: the withdrawal destination cannot be paid on ethereum: the Ethereum destination is in mixed case, so it carries an EIP-55 checksum, and the checksum does not match: a character is wrong; 0x9A080FFFE4105361b023220bD21Be0B9418E90 (19 bytes) → TransferToken: the withdrawal destination cannot be paid on ethereum: an Ethereum destination is 0x and 40 hex digits (a 20-byte address); the message ZBW1|ethereum|0x9A080FFFE4105361b023220bD21Be0B9418E908e → TransferToken: the withdrawal destination cannot be paid on ethereum: a destination is printable ASCII with no space and no '|'; the message ZBW1| → TransferToken: the withdrawal destination cannot be paid on ethereum: the withdrawal names no destination; the recipient 00000000 ‖ c5 × 32 → TransferToken: a withdrawal of ZETH is sent to its custody account ZBC_WBYN35UM_GJYMHAYZ_Y7CMOYLG_ULDW3DU2_OXBWRRTW_TUH6LT2P_JXZAEBCI, and this one is not; an escrow part → TransferToken: a withdrawal cannot carry an escrow (its approval would put the tokens in custody with no withdrawal request); token 13 → TransferToken: withdrawals of ZUSDC are not open: no release of an ethereum token contract exists in this release; token 4 with the destination bc1q02eahpuu87g85zka8eapmwzc0rv56yw2s226c4 → TransferToken: withdrawals of ZBTC are not open: no release to bitcoin exists in this release; token 1 (a genesis token that is no bridge coin) → TransferToken: a message starting ZBW1| is a withdrawal, and token 1 is not a bridge coin, so it has none. The valid transfer from a sender that no longer holds the units (a paid no-op, 14) → no row; no withdrawal can ever name it.
Test cases · §5
15 cases · 4 valid · 11 invalid
A withdrawal of 1 ZETH to an Ethereum address, sent to ZETH's custody account, mined at 10,000 and credited
Loading the test widget…
The same destination all in lower case passes
Loading the test widget…
The same destination all in upper case passes
Loading the test widget…
The same destination without 0x passes
Loading the test widget…
The same transfer from a sender that no longer holds the units writes no request row
Loading the test widget…
The destination with its first letter in lower case (a wrong EIP-55 checksum)
Loading the test widget…
A 19-byte destination
Loading the test widget…
The chain named in the message
Loading the test widget…
A destination with a space
Loading the test widget…
The message ZBW1| alone
Loading the test widget…
Sent to another account
Loading the test widget…
With an escrow part
Loading the test widget…
A withdrawal of ZUSDC (token 13)
Loading the test widget…
A withdrawal of ZBTC (token 4) to a Bitcoin address
Loading the test widget…
A ZBW1| transfer of token 1, which is no bridge coin
Loading the test widget…
Defects to match. None of its own.
§5a A custody account receives nothing else
Purpose. Keep every transaction but a withdrawal away from a custody account, whose holdings could never leave it.
Inputs. Any transaction; the bridge_coin rows and their custody accounts (§1a).
Output and effect. Rule bridge_withdrawal_credit, part of the same stateless validation as §5 and run right after it (a refusal is refused at admission and makes a block invalid). For each bridge coin in ascending token id, with C its custody account, the first of these refuses: the sender is C; the transaction is not a withdrawal (§5) and the envelope recipient is C; an escrow part names C as approver; the 32 bytes of C after its type occur anywhere in the transaction's body bytes. The text is the site (the sender, the recipient, the escrow approver, an account in the transaction's body) followed by is the custody account of <name>, which receives only withdrawals of <name> (a TransferToken with a ZBW1| message): nothing else sent to it could ever leave it for a coin whose withdrawals are open, and with , not open in this release before the ) for a closed one. The body search catches every way a body names an account (a batch payment, a split recipient, an offer's counterparty, an app's opponent, a group member or controller, a consent participant, a multisig participant or a MultiSignature's inner transaction bytes); the 32 bytes are a SHA3-256 output, so nothing else in a body matches them. A chain without bridge coins runs no such check. A deposit whose recipient is a custody account waits (§4).
How to compute it. As stated.
Rule activation. bridge_withdrawal_credit, active from height 0 on every chain.
Rejections and errors. The texts above.
Vector. computed. The withdrawal of §5 passes (its recipient is its own coin's custody, its body names none). INVALID INPUT: a SendZBC of 1 ZBC to 00000000b070ddf68c3270c38319c7c4c76166a2c76d8e9a75c368c6769d0fe5cf4f4df2 → the recipient is the custody account of ZETH, which receives only withdrawals of ZETH (a TransferToken with a ZBW1| message): nothing else sent to it could ever leave it; a TransferToken of 1 ZUSDC without a message to 000000006326c1035c60736d62fcd27ae9e9807c9a60bf1e4be16c784b2757799067778f → the recipient is the custody account of ZUSDC, which receives only withdrawals of ZUSDC (a TransferToken with a ZBW1| message, not open in this release): nothing else sent to it could ever leave it; a SendZBCBatch whose second payment is to 00000000b070ddf68c3270c38319c7c4c76166a2c76d8e9a75c368c6769d0fe5cf4f4df2 → an account in the transaction's body is the custody account of ZETH, which receives only withdrawals of ZETH (a TransferToken with a ZBW1| message): nothing else sent to it could ever leave it (body 0200 ‖ 24 ‖ 00000000 ‖ d2 × 32 ‖ 00e1f50500000000 ‖ 24 ‖ that account ‖ 00e1f50500000000: two payments of 1 ZBC); an escrowed SendZBC whose approver is ZBTC's custody account 000000009c12…bff1 → the escrow approver is the custody account of ZBTC, which receives only withdrawals of ZBTC (a TransferToken with a ZBW1| message, not open in this release): nothing else sent to it could ever leave it.
Test cases · §5a
4 cases · 4 invalid
A SendZBC of 1 ZBC to ZETH's custody account
Loading the test widget…
A TransferToken of 1 ZUSDC without a message to ZUSDC's custody account
Loading the test widget…
A SendZBCBatch whose second payment is to ZETH's custody account
Loading the test widget…
An escrowed SendZBC whose approver is ZBTC's custody account
Loading the test widget…
Defects to match. None.
§6 Withdrawal resolution and the burn
Purpose. Burn the wrapper units a user's executed transfer put in custody once a supermajority has ratified the request, and publish the keepers' foreign signatures.
Inputs. Block H ≥ 1; the live attestation rows; the result rows; authorized and quorum of §2; the bridge_withdrawal_request rows; BRIDGE_WITHDRAWAL_PREFIX ZBWDR1:.
Output and effect. Like §4, the step does not run while the survival flag of H is true. Candidates as §4 with the prefix ZBWDR1: (this step runs after the deposit step and before governance, 22). For each: an existing result row → nothing (one-shot). Otherwise the event's live attestation rows in (block_height, attester) order; for each row by an authorized attester: agreed = the value up to the first | (the whole value when there is none; the part after it is that node's reference and foreign signature and is ignored by the tally); an empty agreed is skipped; the first agreed whose count reaches quorum wins and the scan stops; none → nothing changes (no row is written).
The winner is parsed as <token_id>:<amount>:<dest> at its first two colons (the numbers read as in §4; the destination is everything after the second colon, may contain further colons, cannot contain |); amount ≤ 0 or an empty destination → malformed. The event id after the prefix must be non-empty and strict hex (even length, digits 0-9a-fA-F, no 0x) and is decoded to the trigger's hash bytes; the live request row for that hash must exist, and its token_id, amount and destination must equal the winner's. Then the burn from the row's custody_address (rule bridge_burn_supply_first): amount > 0 and an existing token (any token) → total_supply < amount → "Bridge burn: supply underflow" and nothing written; else the custody balance version is written (balance and spendable −= amount; a balance below amount refuses with "Insufficient token balance" and writes nothing); then a new token version with total_supply −= amount. Only after a successful burn: oracle_result(event_id, agreed, H) (a failed write refuses the block). No ledger row is written. Every refusal is logged ("Bridge withdrawal <id> refused: …") and leaves the event open: it is retried at every block while it is within the idle window (§7), and the registry may attest a corrected payload (a new attestation retires the attester's earlier row). A refusal is never a block fault: a storage fault is.
How to compute it. 0. If the survival flag of H is true: stop. 1. The candidates (§7). 2. Per event: the one-shot check; the tally on agreed. 3. Parse the winner and the event id. 4. Read the request row; compare token, amount and destination. 5. Check the supply; debit custody; lower the supply. 6. Write the result row.
Rule activation. bridge_withdrawal_credit (the request row as the only proof; the result after the burn), bridge_burn_supply_first (the supply check before the debit), survival_mode (the pause); §2's rules; all active from height 0 on every chain.
Rejections and errors. Logged only, in this order: "Bridge withdrawal: malformed agreed value", "… malformed event id", "… trigger hash is not hex", "… no executed custody credit for this trigger", "… token/amount do not match the executed credit", "… destination does not match the executed credit", "Bridge burn amount must be > 0", "Bridge burn: unknown token", "Bridge burn: supply underflow", "Insufficient token balance".
Vector. computed (the request row of §5, trigger hash d75df025be21ac74af3327c20186b415927367402a5b5028447e95c224f74d21 for the example): event_id = ZBWDR1:d75df025be21ac74af3327c20186b415927367402a5b5028447e95c224f74d21 (71 bytes; the upper-case spelling of the hex names the same event only if every keeper spells it the same way, because the tally groups by the exact string — the reference keeper uses the hash as the API returned it); agreed value 5:100000000:0x9A080FFFE4105361b023220bD21Be0B9418E908e, each keeper's first attestation ending in |; at the eighth agreeing attester of the 11 the custody account loses 100,000,000 units of token 5 and the supply falls by the same, the result row holds the agreed value at the resolving height. INVALID INPUT: eight attesters agreeing on 5:200000000:0x9A08…908e against that row → Bridge withdrawal: token/amount do not match the executed credit logged, nothing burned, the event open; an event id ZBWDR1:00ff naming no row → Bridge withdrawal: no executed custody credit for this trigger.
Test cases · §6
6 cases · 3 valid · 3 invalid
The eighth agreeing attester burns the custody's units
Loading the test widget…
Seven agreeing attesters burn nothing
Loading the test widget…
Eight attesters agreeing on twice the request row's amount
Loading the test widget…
Eight attesters agreeing on another destination
Loading the test widget…
An event id ZBWDR1:00ff naming no request row
Loading the test widget…
A request row credited at 10,000 still burns at block 1,000,000
Loading the test widget…
Defects to match. A request row has no window of its own: a withdrawal attested years later still burns, as long as a keeper attests it (§7).
§7 The idle window and the one-shot guards
Purpose. Which events the two steps look at, and why a resolved event is final.
Inputs. H; the live attestation heights; BRIDGE_EVENT_IDLE_WINDOW 720; the stored survival flags (36 §12).
Output and effect. An event is a candidate while the survival-adjusted idleness of its newest live attestation (height h) is at most 720: (H − h) − (the number of stored survival rows with height in (h, H] and active = 1) ≤ 720; with no survival heights in between that is every block H ≤ h + 720, and from h + 721 it is ignored by both bridge steps until a new attestation (which retires its attester's earlier row and raises h). The generic oracle resolution never considers the two bridge prefixes (17), so an idle bridge event is resolved by nothing. A result row makes an event final: the deposit step writes it only after a successful mint, the withdrawal step only after a successful burn; neither step ever revisits an event with a result row. In survival mode no new attestation can be mined (§3) and neither bridge step runs (§4, §6): the events wait, their idleness does not grow over the survival heights, and at the first block whose flag is false each one whose adjusted idleness is still within 720 is a candidate again. The attestation rows of a pending event inside the window outlive the receipt horizon of the prune, and the survival rows its idleness counts are kept with it (36 §12, 22).
How to compute it. Take every distinct event_id of the live attestation rows that has no row in the result table and whose newest live attestation h satisfies the inequality above; keep those that begin with the step's prefix.
Rule activation. survival_mode (the adjusted count), active from height 0 on every chain.
Rejections and errors. None.
Vector. computed: an event whose newest attestation is at 135,000 is considered at every block up to 135,720 and dropped from 135,721; with the survival flag stored true at 135,100 … 135,199 (100 heights) it is considered up to 135,820 and dropped from 135,821.
Test cases · §7
4 cases · 4 valid
An event attested at 135,000 is a candidate at 135,720
Loading the test widget…
It is dropped from 135,721
Loading the test widget…
With the survival flag stored true at 135,100 … 135,199 it is a candidate at 135,820
Loading the test widget…
… and dropped from 135,821
Loading the test widget…
Defects to match. A deposit or withdrawal whose attestations are all older than 720 counted blocks is unresolvable until someone attests again; a withdrawal refused for a correctable reason (an under-funded custody) that nobody re-attests within the window is abandoned (22).
§8 The API views (local)
Purpose. What the HTTP API shows of the bridge (31 §7).
Inputs. The tables above; the keeper's state files.
Output and effect. Where a view below names the registry, it is every node whose latest registry row is Registered at the time of the call, suspended ones included (unlike the counted set of §2), each as its attester account, with the compiled quorum 2 / 3: quorum = max(1, ⌈size × 2 / 3⌉).
GET /api/v1/bridge/coins→{"bridge_withdrawal_credit":<the rule's state for tip + 1>,"coins":[…]}, one entry per bridge coin in token order with, in this order,token_id(a string),symbol,chain,asset,deposit_address, and while the rule is active for tip + 1custody_account(§1a, lower-case hex),zbc_withdraw_address(itsZBC_text form),withdrawals_open(a boolean) andwithdrawals_closed_reason(§1a,""when open), thendecimals(a number); 503unavailablewithout state.GET /api/v1/bridge/deposits/:event_id(the id must beginZBRDEP1:, else 404not a bridge deposit event; the path accepts letters, digits,:,.,_and-) → keys in alphabetical order:bridge_withdrawal_credit(the rule's state for tip + 1),event_id,pending(no result row),reason(the refusal text of §4 step 2 the event is stuck on, else""),resolved,value(the result value, or while pending the value the registry's attesters agree on at its quorum,""when none); 503bridge state unavailablewithout state, registry or chain.GET /api/v1/bridge/withdrawal-requests?custody=&from_height=&to_height=&scan_blocks=→custody(hex account; the rows whosecustody_addressends with those bytes) is required, else 400custody (hex account address) is required(503bridge state unavailablewithout state or chain, checked first); the answer, keys alphabetical:bridge_withdrawal_credit,finalized_height,requests:[…], and withfrom_heightalsofrom_height(floored at 1) andscanned_to=min(to_height, finalized_height, from_height + scan_blocks − 1), orfrom_height − 1whenscan_blocksis 0 orfrom_heightexceeds thatto_height(scan_blocksdefault 2,000, held to at most 500;to_heightdefault and capfinalized_height; an unparsable height → 400invalid height range); withoutfrom_heightthe list is empty. A row, keys alphabetical:amount,block_height,destination,finalized(block_height ≤ finalized_height),message(ZBW1|‖ destination),recipient_account_address(the custody, hex),token_id(number),transaction_hash(the trigger, hex); the live rows withfrom_height ≤ block_height ≤ scanned_to, ordered by height then trigger hash; rows are read only while the rule is active for tip + 1.GET /api/v1/bridge/withdrawals/:hex([0-9a-fA-F]+) → in order:event_id=ZBWDR1:‖ the hex as given,trigger_transaction_hashas given,request_recorded(true when the rule is active for tip + 1; then a trigger with no live request row answers 404no executed custody credit for this triggerinstead),oracle_result_height(the result row's height, 0 while pending),withdrawal_id(0x‖ Keccak-256(trigger hash bytes ‖oracle_result_heightas uint32 LE) once resolved, else""),resolved,token_id(a number),amount,release_amount_wei(while the rule is active for tip + 1 and the event is resolved, the wei the keepers sign for,amount × 10¹⁰, as0xand 64 hex digits, big-endian; else""),destination(from the result value when resolved, else from the first authorized attestation's agreed part, else 0 / 0 / empty),registry_size,quorum,quorum_num2,quorum_den3 (the registry of this section),signature_countandsignatures:[{attester (hex), signature}]= the foreign signatures of the registry's attesters: none while pending; once resolved, only those agreeing with the winner whose value names the result height (R<oracle_result_height>|after the first|, the height in decimal digits, the signature being what follows); a value without that reference lists no signature. An attestation of a resolved event is pruned once it falls below the receipt horizon (13§8;receipt_lifecycle518,400 blocks on the TestNet, 1,440 on the DevNet), so the view lists a signature only until the attestation that carries it is that old. 503bridge state unavailablewithout state.GET /api/v1/bridge/deposits?recipient=andGET /api/v1/bridge/withdrawals?account=→{"deposits":[…]}/{"withdrawals":[…]}read from the keeper's JSON files ($ZOOBC_BRIDGE_DEPOSITS/$ZOOBC_BRIDGE_WITHDRAWALS, else~/.zoobc/bridge-deposits.json/bridge-withdrawals.json), filtered by address substring, unvalidated (31); empty lists when the files are absent.
How to compute it. As stated.
Rule activation. bridge_withdrawal_credit shapes the four chain-backed views (active from height 0 on every chain).
Rejections and errors. The 400, 404 and 503 strings above.
Vector. computed: /bridge/coins on either shipped chain → {"bridge_withdrawal_credit":true,"coins":[{"token_id":"4","symbol":"ZBTC","chain":"bitcoin","asset":"native","deposit_address":"bc1q02eahpuu87g85zka8eapmwzc0rv56yw2s226c4","custody_account":"000000009c12546254570a0b0cf128e9b70f20c7a61a625dbce7a6dec7b873f6e458bff1","zbc_withdraw_address":"ZBC_TQJFIYSU_K4FAWDHR_FDU3ODZA_Y6TBUYS5_XTT2NXWH_XBZ7NZCY_X7YUFPFA","withdrawals_open":false,"withdrawals_closed_reason":"withdrawals of ZBTC are not open: no release to bitcoin exists in this release","decimals":8},{"token_id":"5","symbol":"ZETH","chain":"ethereum","asset":"native","deposit_address":"0x9A080FFFE4105361b023220bD21Be0B9418E908e","custody_account":"00000000b070ddf68c3270c38319c7c4c76166a2c76d8e9a75c368c6769d0fe5cf4f4df2","zbc_withdraw_address":"ZBC_WBYN35UM_GJYMHAYZ_Y7CMOYLG_ULDW3DU2_OXBWRRTW_TUH6LT2P_JXZAEBCI","withdrawals_open":true,"withdrawals_closed_reason":"","decimals":8},…]} (ZUSDC and ZUSDT as §1a); /bridge/deposits?recipient=00 with no keeper file → {"deposits":[]}; /bridge/withdrawals/00ff with no request row → 404 {"success":false,"error":"no executed custody credit for this trigger","code":404}; /bridge/withdrawal-requests without custody → 400 custody (hex account address) is required; the §6 example resolved at height 1,200 → "oracle_result_height":1200,"withdrawal_id":"0x3b4a638b4f6e7f3f3bc034171f0c22d4473966d1227b86260a049f6a15419a8e" (Keccak-256 of d75df025…4d21 ‖ b0040000), "amount":100000000,"release_amount_wei":"0x0000000000000000000000000000000000000000000000000de0b6b3a7640000" (10¹⁸ wei, one ether); the same request while pending → "release_amount_wei":"".
Test cases · §8
6 cases · 4 valid · 2 invalid · 3 reference
/bridge/coins
The rows of §1 with the custody keys of §1a (computed by 34-custody), token_id a string.
A stated value: there is nothing to compute. A compatible node shows the same value.
- body
{"bridge_withdrawal_credit":true,"coins":[{"token_id":"4","symbol":"ZBTC","chain":"bitcoin","asset":"native","deposit_address":"bc1q02eahpuu87g85zka8eapmwzc0rv56yw2s226c4","custody_account":"000000009c12546254570a0b0cf128e9b70f20c7a61a625dbce7a6dec7b873f6e458bff1","zbc_withdraw_address":"ZBC_TQJFIYSU_K4FAWDHR_FDU3ODZA_Y6TBUYS5_XTT2NXWH_XBZ7NZCY_X7YUFPFA","withdrawals_open":false,"withdrawals_closed_reason":"withdrawals of ZBTC are not open: no release to bitcoin exists in this release","decimals":8},{"token_id":"5","symbol":"ZETH","chain":"ethereum","asset":"native","deposit_address":"0x9A080FFFE4105361b023220bD21Be0B9418E908e","custody_account":"00000000b070ddf68c3270c38319c7c4c76166a2c76d8e9a75c368c6769d0fe5cf4f4df2","zbc_withdraw_address":"ZBC_WBYN35UM_GJYMHAYZ_Y7CMOYLG_ULDW3DU2_OXBWRRTW_TUH6LT2P_JXZAEBCI","withdrawals_open":true,"withdrawals_closed_reason":"","decimals":8},…]}
/bridge/deposits?recipient=00 with no keeper file
A stated value: there is nothing to compute. A compatible node shows the same value.
- status
200- body
{"deposits":[]}
/bridge/withdrawals/00ff with no request row
Loading the test widget…
/bridge/withdrawal-requests without custody
A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.
- status
400- refusal
custody (hex account address) is required
The §6 example resolved at height 1,200
Loading the test widget…
The same request before any attestation
Loading the test widget…
Defects to match. None.
§9 The keeper and its supervisor (local)
Purpose. What the node runs beside itself to watch the foreign chains and to vote; none of it is consensus, but an implementation's keeper must produce the same event ids and values as the reference keeper to count towards the same quorum.
Inputs. bridge.json (node_key hex, api, threshold, participants[], coins{symbol → token_id}, confirmations, poll_sec, inner_fee, scan_from_height, an ethereum{custody, node_key, chain_id, coin} block (coin default ZETH), a bitcoin{rpc, user, pass, custody, coin, required, wallet, birth_height, scan_window} block for the Bitcoin watcher); the [bridge] section of node.conf (30).
Output and effect. The supervisor (30: started after the API, gated on free disk, available RAM and the presence of bridge.json, restarted with a backoff from 2 s) runs the keeper in watch mode with its output in the bridge log. For each coin of its configuration the keeper takes the custody account the chain names in GET /api/v1/bridge/coins (§1a; the multisignature of its participants only for a token the chain names none for). It keeps a cursor per coin, the last finalized height it processed (a fresh keeper starts at scan_from_height; 1 = the whole chain), reads GET /api/v1/bridge/withdrawal-requests?custody=<custody hex> for the chain's finalized_height and the rule's state, and pages through (cursor, finalized] oldest first with from_height, to_height and scan_blocks (§8), moving the cursor after each page; an action that fails stops the pass before its block; an answer without the finalized height scans nothing that pass. (A chain where the rule is off is scanned from the transaction rows of /accounts/<custody>/transactions instead, a row whose body hex has a non-hex digit reading as no amount and being skipped; no live chain is such.) Per executed request not seen yet, of its token, whose finalized is not false, whose message begins with ZBW1| and whose amount, destination and height are non-empty: for the coin its ethereum block maps (with a custody and a key set), a request it can never release — a destination that fails §5's Ethereum rule (steps 5 a–c), or an amount whose wei value does not fit 128 bits — is logged once ([<coin>] withdrawal <trigger> (block <height>) cannot be released and is skipped: <reason>), marked seen with the value refused: <reason>, never attested, and the scan moves on (on a 0.6.1 chain no such request exists, §5). Otherwise first it attests the request (§3; value <token_id>:<amount>:<dest>|, no foreign signature, fee 0, from the node key); for a coin other than the one its ethereum block maps (with a custody and a key set) that is the keeper's whole part. For the mapped coin it reads GET /api/v1/bridge/withdrawals/<trigger> before the first attestation (no answer stops the pass; a request already resolved is not attested first but signed at once) and then, at every later pass, again, and, once resolved with a matching token, amount and destination and a non-zero oracle_result_height, computes the foreign release for Ethereum — the withdrawal id = Keccak-256(trigger hash bytes ‖ oracle_result_height as uint32 LE), an EIP-712 signature under the configured chain id and custody contract over that id, the token field (the zero address: native ether), the 20-byte destination and the amount in wei as a 32-byte big-endian number — and attests again with the value <token_id>:<amount>:<dest>|R<oracle_result_height>|<signature hex>, which retires its first row and publishes the signature on the bus (§8). A release the keeper recorded as waiting whose request it can never release is dropped once at the next pass, marked seen the same way (… waiting for its release cannot be released and is dropped: <reason>). Its release record names the destination as 0x and 40 lower-case hex digits and the wei amount.
Amounts. A ZooBC token amount counts atomic units of 10⁻⁸ of a whole coin whatever the coin's declared decimals (decimals below 8 only make an amount a multiple of 10^(8 − decimals) units, 14); ether counts wei, 10⁻¹⁸. So one ZETH unit is 10^(18 − 8) = 10¹⁰ wei, and the declared decimals never scale an amount (the mainnet template's 9 for ZETH changes nothing). A withdrawal of N units pays exactly N × 10¹⁰ wei, computed in 128 bits; a product that would not fit is refused, never signed (no 64-bit amount reaches it). A deposit of W wei is attested as floor(W / g) × g / 10¹⁰ units, with the grain g = 10¹⁰ wei, times 10^(8 − decimals) when the decimals /bridge/coins states are below 8; the remainder, under one grain, stays in the foreign custody and is never minted, so a mint is never more than the deposit; a deposit that gives 0 units is not attested (not attested: the deposit is under one unit of the coin; it stays in the foreign custody), one above 128 bits or whose units exceed a signed 64-bit integer neither. The chain never sees the wei: it mints the attested units, so the quorum counts one number every keeper computes alike. For deposits, its foreign-chain watchers confirm a transfer to the deposit address and send the deposit attestation of §3 with the ZooBC recipient the watcher derived and the units so computed. Neither mint nor burn takes a bridge fee.
Submitting the release (the operator's step). Nothing submits it automatically: once /bridge/withdrawals/<trigger> shows resolved with at least the custody contract's threshold of signatures, any one operator builds the Ethereum transaction to the custody contract from the published withdrawal_id, the token address 0 (native ether), the destination, the release_amount_wei and the signatures of the contract's registered signers, and broadcasts it; the contract re-checks the quorum and pays a withdrawal id once, so a second submission is refused.
Rule activation. None.
Rejections and errors. The keeper's own log lines. In survival mode its attestations are refused at admission (§3) and it retries them at its next pass.
Vector. computed: for the §6 example resolved at height 1,200 the keepers sign the withdrawal id 0x3b4a638b4f6e7f3f3bc034171f0c22d4473966d1227b86260a049f6a15419a8e for the amount 0x0000000000000000000000000000000000000000000000000de0b6b3a7640000 (100,000,000 units × 10¹⁰ = 10¹⁸ wei) and publish 5:100000000:0x9A080FFFE4105361b023220bD21Be0B9418E908e|R1200|<signature hex>; before the burn their attestation value is 5:100000000:0x9A080FFFE4105361b023220bD21Be0B9418E908e|. A ZETH deposit of 1,234,567,890,123,456,789 wei is attested as 123,456,789 units (1.23456789 ZETH; 123,456,789 wei stay in the foreign custody), with the mainnet template's 9 decimals the same; one of 10,000,000,000 wei as 1 unit; one of 9,999,999,999 wei is not attested. A withdrawal of 1 unit pays 0x00000000000000000000000000000000000000000000000000000002540be400 (10¹⁰ wei). INVALID INPUT: a recorded request of the Ethereum-mapped coin whose destination is 0x9A080FFFE4105361b023220bD21Be0B9418E90 (19 bytes; recorded on a chain without the rule, §5 refuses it) → logged once, marked seen refused: an Ethereum destination is 0x and 40 hex digits (a 20-byte address), never attested or signed, and the scan goes on with the next request.
Test cases · §9
11 cases · 9 valid · 2 invalid
The keeper's values for the §6 example resolved at height 1,200
Loading the test widget…
The keepers' signatures published once the burn resolved at 1,200
Loading the test widget…
A withdrawal of 1 unit pays 10^10 wei
Loading the test widget…
A recorded request of the Ethereum-mapped coin with a 19-byte destination is skipped, never signed
Loading the test widget…
A deposit of 10^18 wei
Loading the test widget…
A deposit of 1,234,567,890,123,456,789 wei
Loading the test widget…
The same with the mainnet template's 9 decimals
Loading the test widget…
A deposit of 10^10 wei
Loading the test widget…
A deposit given as 0x-hex
Loading the test widget…
A deposit of a coin with 6 decimals rounds to its grain
Loading the test widget…
A deposit of 9,999,999,999 wei
Loading the test widget…
Defects to match. None.
§10 Foreign-signed carriers: the chain bindings and the once-only rule
Purpose. A transaction may carry, in its message field, a native transaction signed by the sender's foreign key — an Ethereum transaction (an EIP-155 legacy or an EIP-1559 one), a Bitcoin transaction or a Solana transaction — in place of a ZooBC signature (02 §9). The foreign signature covers nothing of ZooBC (no timestamp, no fee, no chain), so the chain binds every such carrier to itself and lets it execute once.
Inputs. The carrier's message bytes; the sender's account type (04000000 Ethereum; 05000000 Bitcoin P2PKH, 07000000 Bitcoin P2WPKH; the Solana account type of 01); the chain's block-0 hash; the main chain's recent blocks; the sender's account nonce; the pool and the staging area; the spent_foreign_message table (msg_hash, blob, the key: a carrier id; block_height, integer; not versioned, rolled back by deleting the rows above the target, travels whole up to the snapshot height, 26).
Output and effect. Rule foreign_carrier_bound (active from height 0 on every chain). A carrier is a SendZBC (any kind) or, for Solana only, a TransferToken; it carries no escrow, no expiry and no survival amount; it pays at least the minimum fee (04) and, an Ethereum carrier, exactly the fee its signed gas fields name: gas_price × gas_limit wei, divided by 10¹⁰ (a product that overflows 64 bits reads as 100,000,000). Its carrier id is: Ethereum — Keccak-256 of the canonical signed transaction bytes; Bitcoin — the transaction id of the message; Solana — the message's single 64-byte signature (bytes 1 … 64). Bindings:
- Ethereum: the message re-encodes exactly (one minimally encoded RLP value, no trailing bytes, no leading zeros,
yParity0 or 1, no access list); EIP-155 with this chain's EVM chain id, which is derived from the block-0 hash (30); the nonce rule below; the recipient a type-4 (Ethereum) account. - Bitcoin: the message re-serializes exactly (minimal CompactSize everywhere; the segwit marker only when a witness is present); exactly one input whose outpoint is the chain's block-0 hash as the 32 txid bytes, in the order the node stores and the API shows them (a library that takes a display txid reverses it on serialization: hand it the block-0 hash hex reversed), at index
0xFFFFFFFF(bytesff ff ff ff); a P2WPKH input carries no scriptSig; a P2PKH spend carries no witness; the recipient's type follows the first output's script (0014 ‖ 20 bytes→ type 7,76a914 ‖ 20 bytes ‖ 88ac→ type 5). - Solana: exactly one signature (byte 0 =
01, and the header's signature count, byte 65, =01); the signedrecent_blockhash(the 32 raw bytes of the message field, compared as they stand: they equal the block hash bytes in the order the node stores and the API shows them in hex, and a Solana library that takes a base58 blockhash is handed the base58 of those 32 bytes, nothing reversed) is the hash of a main-chain block whose height lies in[including − 720, including](SNAPSHOT_BLOCK_REFERENCE_REACH, the blocks every node holds: the carrier expires with that window and is re-judged at block assembly); a TransferToken carrier moves ZSOL (the token whose symbol isZSOL) only, never with a fee in the token. - Nonce (Ethereum): in a block, the carrier's nonce must equal the sender's account nonce as the executor sees it. A carrier whose nonce differs makes the block that carries it invalid (
ForeignCarrierNonce: carrier nonce N, account nonce M (a block carrying it is invalid)): nothing is charged, the nonce does not move and the carrier id is not marked spent. A block holds at most one transaction per account (19), so nothing earlier in the block moves the sender's nonce; the mempool and block assembly refuse such a carrier first, so only a blocksmith that skips them builds such a block, and it loses the block and its turn (a miss,36§3), exactly as for a replayed id. The nonce is judged where the block's transactions are applied, after block validation passed, so a relaying peer of such a block is not struck (36§3), unlike one of a block carrying a replayed id. A matching carrier increments the nonce, as every executed transaction of the sender does, whatever its outcome after that. At admission the expected nonce is the first free nonce at or above the account nonce over the carriers of that signer already pooled or staged on this node (the judged carrier's own excluded), so a carrier queued behind one that expired or was dropped waits until a carrier with the missing nonce arrives or it expires itself; the refusal readscarrier nonce N, account nonce M. At block assembly only the account nonce is expected, so of queued M and M + 1 only M enters this block.GET /api/v1/accounts/<eth>/eth-tx-countanswerscount(the account nonce) andpending(the admission's expected nonce); the RPC adapter answerseth_getTransactionCountwithpendingfor thependingtag andcountfor every other (31§6). - Once only: every check looks up both the carrier id and the SHA3-256 of the message bytes (a key no row holds on a chain where the rule is active from height 0). At submission the staging area refuses, before the stateless checks, a carrier whose key is spent in
spent_foreign_message, held by a pooled carrier or held by a staged one (ForeignCarrierReplayedeach); the pool refuses a copy of a pooled key (ForeignCarrierReplayed, a duplicate) and the validator a spent one (Foreign carrier transaction already used). Block assembly skips a spent carrier and takes, of several pooled copies of one id, the oldest (by arrival, then transaction id). A block carrying a spent key, or the same id twice, is invalid (ForeignCarrierReplayed). An executed carrier writes its id to the table (rolled back with the block).
How to compute it. 02 §9 for the parse and the signature; the checks above at admission (04) and in block validation (19), the Solana and Bitcoin bindings also at selection.
Rule activation. foreign_carrier_bound, eth_signature_canonical_v (every ZooBC-signed signature by an Ethereum- or Tron-typed key uses recovery id 27 or 28 exactly, 02; a carrier keeps its own chain's form), active from height 0 on every chain.
Rejections and errors. A foreign-signed carrier transaction cannot carry survival (the foreign signature does not cover it); fund it with FundLongevity instead, A foreign-signed carrier cannot carry an expiry, … cannot carry an escrow, A foreign-signed carrier has the wrong transaction type, Ethereum carrier is not canonical: …, Ethereum carrier chain id does not match this chain, Ethereum carrier fee must equal the signed gas fields, Ethereum carrier recipient must be an Ethereum-typed account, Bitcoin carrier is not canonically serialized, Bitcoin carrier P2WPKH input carries a scriptSig, Bitcoin carrier P2PKH spend carries a witness, Bitcoin carrier recipient type does not match the paid output's script, Bitcoin carrier needs exactly one genesis outpoint, Bitcoin carrier input must spend the ZooBC genesis hash at index 0xFFFFFFFF, Solana carrier must carry exactly one signature, Solana carrier: malformed token body, Solana carrier cannot pay its fee in the token, Solana carrier moves ZSOL or ZBC only, Solana carrier recent_blockhash is not a main chain ancestor within 720 blocks, Foreign carrier transaction already used, carrier nonce N, account nonce M (admission), ForeignCarrierNonce: carrier nonce N, account nonce M (a block carrying it is invalid) (in a block), ForeignCarrierReplayed, Ethereum signature recovery id must be 27 or 28.
Vector. computed: a Bitcoin carrier on a chain whose block-0 hash bytes are b0 b1 … b31 carries one input whose 36 outpoint bytes are b0 b1 … b31 ff ff ff ff; for the shipped TestNet genesis file (block-0 hash 3a2897e7c5ad6143429bab33a92d14d11ffd6fc281f2b62a6fd6b49c183b863d, 06 §3; the launch restamps the timestamp, so a live chain substitutes the hash it announces) the serialized outpoint is 3a2897e7c5ad6143429bab33a92d14d11ffd6fc281f2b62a6fd6b49c183b863dffffffff, and a library that takes a display txid is handed 3d863b189cb4d66f2ab6f281c26ffd1fd1142da933ab9b424361adc5e797283a. INVALID INPUT: the outpoint 3d863b18…283a ffffffff (the hash reversed in the serialized bytes) → Bitcoin carrier input must spend the ZooBC genesis hash at index 0xFFFFFFFF; two inputs → Bitcoin carrier needs exactly one genesis outpoint. A Solana carrier on that chain included at height 2,000 may cite the hash of main-chain blocks 1,280 … 2,000; one citing block 1,279 → Solana carrier recent_blockhash is not a main chain ancestor within 720 blocks. An Ethereum carrier with gas_price 47,619,047,620 wei and gas_limit 21,000 names a fee of 1,000,000,000,020,000 wei → 100,000 atomic units (ZBC 10⁻³); declared with any other fee → Ethereum carrier fee must equal the signed gas fields. A sender with account nonce 4 and a pooled carrier at nonce 4: a second carrier at nonce 4 → carrier nonce 4, account nonce 5; one at nonce 5 is admitted and eth-tx-count answers "count":4,"pending":6, so the adapter answers eth_getTransactionCount(<address>, "pending") with "0x6" and eth_getTransactionCount(<address>, "latest") with "0x4"; at block assembly only the nonce-4 carrier is eligible. INVALID INPUT: a block in which that sender's account nonce is 4 carrying its carrier at nonce 5 → the block is invalid, ForeignCarrierNonce: carrier nonce 5, account nonce 4 (a block carrying it is invalid); nothing is charged and the nonce stays 4. The raw transactions and signatures of 33 §3 are the signature vectors.
Test cases · §10
14 cases · 7 valid · 7 invalid
The Bitcoin carrier outpoint on the shipped TestNet genesis
Loading the test widget…
The outpoint with the hash reversed in the serialized bytes
Loading the test widget…
A Bitcoin carrier with two inputs
Loading the test widget…
A Solana carrier included at 2,000 citing block 1,280
Loading the test widget…
A Solana carrier included at 2,000 citing block 2,000
Loading the test widget…
The same carrier citing block 1,279
Loading the test widget…
An Ethereum carrier at 47,619,047,620 wei gas price and 21,000 gas
Loading the test widget…
The same carrier declaring another fee
Loading the test widget…
A second carrier at nonce 4 while one at nonce 4 is pooled
Loading the test widget…
A carrier at nonce 5 while one at nonce 4 is pooled is admitted
Loading the test widget…
eth-tx-count with carriers at nonces 4 and 5 pooled
Loading the test widget…
At block assembly the nonce-4 carrier is eligible
Loading the test widget…
At block assembly the nonce-5 carrier waits
Loading the test widget…
A block carrying the carrier at nonce 5 while the account nonce is 4
Loading the test widget…
Defects to match. None.
§11 Consensus and local; summary of defects
Consensus: §1 (the rows and their place in the genesis hash), §1a, §2, the classification and the admission gate of §3 and its survival-mode freeze, §4, §5 (the withdrawal checks and the request row), §5a, §6 (including the exact error order, since a refused withdrawal is retried), §7 (and the absence of ledger rows for mints and burns: event types 27 and 36 are written by nothing, 32 §11), §10. Local: the keeper's conventions, its amounts and its refusals (§3, §9), the API of §8, the supervisor.
Defects an implementation must reproduce or know about: (1) any existing token can be minted by a registry supermajority, a mint consulting bridge_coin only to refuse a custody recipient (§4); (2) a mint bypasses the recipient's split and transact policies (§4); (3) the idle window abandons un-re-attested events (§7); (4) a request row never lapses by itself (§6).
A question about this chapter, or a statement that does not match the network? Discuss on zoobc.pro.