NETConnecting

Docs Reference

Bridge program

The acrux_bridge program on Solana mainnet and on Acrux. The vault and deposit records, the light client of Acrux, withdrawals and their release, native ACRUX from slot 4,752,000, every account, instruction and error.

acrux_bridge moves SPL tokens between Solana and Acrux. On Solana it locks deposits in a vault per mint and keeps a light client of Acrux: the validator set of each Acrux epoch and the cblocks certified by it. On Acrux the same program burns withdrawals, and a cblock that Solana's light client certifies proves them to the vault. How to send a deposit or a withdrawal is on Move tokens across.

Programacrux_bridge
Program idEDm6HxGArNEgGfWRZwvj42f4euc9oPQWVUwUbkK3PEe5
Version0.1.0

The same program, at the same id, runs on both chains:

ChainWhat runs there
Solana mainnetinitialize and allow_mint, once, by the program's upgrade authority; deposit; the light client: init_validator_set, post_cblock, attest_cblock, hand_off; release; the closes
Acruxwithdraw, and from slot 4,752,000 withdraw_native. The program is placed at its address from slot 2,711,660, the bridge rule's first slot, and replaced at slot 4,752,000 by the build that adds withdraw_native (Programs on Acrux)

ACRUX is the one mint allowed on Solana mainnet (ACRUX). The IDL is ACRUX_BRIDGE_IDL in @acrux/contract 0.1.21, built with Anchor 0.31.1. The API reads both chains.

Deposits and credits

deposit moves tokens from the depositor's token account into the mint's vault, a token account at ["vault", mint] that is its own authority, and writes a DepositRecord at ["deposit", sequence]. The record holds what the vault received, after any Token-2022 transfer fee. Sequences count up from 0, one per deposit.

Each Acrux validator reads the records through two independent Solana RPCs at finalized commitment, every two seconds, and keeps a record only when both return the same bytes. From the bridge rule's first slot a proposer block carries up to 16 credits in sequence beside its transactions, and every validator checks each one against the record it read itself: a block whose credit matches no finalized record is invalid (Validator). Before a slot's transactions execute, its credits are applied in sequence:

Account on AcruxAddress under the programHolds
Bridged mintPDA ["mint", solana_mint]an SPL Token mint with the Solana mint's decimals; mint authority PDA ["authority"], no freeze authority. For ACRUX, CoN68LBvgfADtuKXXZMq3PwJsTkAfb2yGmVUyfrn8yPE
Recipient's token accountthe associated token account of the recipient for the bridged mintthe credited amount; created by the credit when the address holds nothing
Credit counterPDA ["credited"]the next sequence to credit, 8 bytes
Skipped creditPDA ["skipped_credit", sequence]a credit whose bridged mint or recipient account is not the plain token account the credit writes, kept with its reason; the counter moves on past it

Withdrawals

withdraw on Acrux burns the bridged token from the owner's token account and writes a Withdrawal at ["withdrawal", sequence], counted in Outbound. The amount must reach the mint's least withdrawal, an 8-byte amount after an 8-byte discriminator at ["minimum", solana_mint], which the bridge rule writes at its first slot and no instruction changes. For ACRUX it is 1,000,000 base units, 1 ACRUX. A mint without one has no minimum.

Each cblock's outbox lists, as OutboxEntry values, the next epoch's validator set and every withdrawal burned in its four slots. Its Merkle root is part of the cblock hash the validators vote on. release on Solana takes a withdrawal entry and its Merkle proof against a certified Cblock, and pays from the vault into the recipient's token account for the Solana mint. The bit sequence mod 8192 in Released at ["released", sequence / 8192] is set after the payout, so each sequence is paid once. Any payer can send release; the proofs come from getCblockProof.

Native ACRUX

From Acrux slot 4,752,000, the bridge rule's nativeFromSlot, ACRUX bridged from Solana is Acrux's native balance, the one that pays every fee (Fees and the reserve rule). In that slot, before its transactions, every validator and follower:

  • credits each bridged ACRUX balance to its holder's wallet as native lamports, 1,000 per base unit, and sets the bridged mint's supply to 0;
  • retires the lamports every wallet held before, a wallet being a system account with no data: the faucet's grants, the genesis faucet, the validators' identities and the built-in traffic's senders;
  • keeps the lamports of every data, token and program account, and records their total, with the rent of the two accounts below, once as the fixed reserve; at slot 5,184,000 the rent of the genesis vote accounts and the stake schedule's account joins it (Stake on Acrux), and from slot 5,616,000 the rent of each outside identity's vote account (Admission);
  • places the build of acrux_bridge that adds withdraw_native, and writes the native gate.

From then on a deposit's credit adds its amount times 1,000 in lamports to the recipient's wallet; a recipient that is not a wallet is recorded as a skipped credit. withdraw_native takes lamports from the owner's wallet, at most what has been credited from Solana and not yet withdrawn, and writes the same Withdrawal record as withdraw, so the outbox, the light client and release on Solana are unchanged. The built-in traffic stops.

Account on AcruxAddress under the programHolds
Native gatePDA ["native"]NativeGate, written by the executor at the cut-over; no instruction creates it, and withdraw_native changes only withdrawn
Native burnPDA ["native_burn"]an empty account at its rent; withdraw_native moves the lamports here, and the executor removes them at the end of the slot

getSupply answers nonCirculating, the reserve, and circulating, every lamport above it: what was credited from Solana, less what was withdrawn and the base fees burned. getNativeSupply and native on GET /v1/bridge give the gate's counters.

The light client

The light client knows Acrux's validators and their stakes for each bridge epoch of 432,000 Acrux slots, 108,000 cblocks. Its first set, epoch 6 with Acrux Net's twelve validators, was seeded once by init_validator_set. Every later set comes from Acrux: each cblock's outbox carries the next epoch's set, and hand_off proves it against a certified cblock of the epoch before. From epoch 14 that is the set frozen at the cut-off of the epoch before, outside validators included (Admission).

A cblock is posted once by post_cblock with its hash preimage and outbox root. The program hashes them together and requires the cblock's hash, so the root is the one the validators signed. attest_cblock then counts the votes that Solana's Ed25519 program verified in the same transaction. Each must be a validator of the cblock's epoch voting Notar or Finalize on its consensus slot and hash, over the message:

text
SHA-256(chainId) ‖ bincode Vote { validator, slot, Some(hash), kind }

chainId is "acrux" on Acrux Net. The votes fill more than one transaction's 1,232 bytes, so a cblock is attested over several. It is certified once Finalize votes hold 60% of the epoch's stake, or Notar votes 80%, the thresholds of Consensus on cblocks.

Accounts

AccountAddressChain
BridgePDA ["bridge"]Solana
AllowedMintPDA ["allowed", mint]Solana
VaultPDA ["vault", mint], a token accountSolana
DepositRecordPDA ["deposit", sequence]Solana
ValidatorSetPDA ["set", epoch]Solana
CblockPDA ["cblock", hash]Solana
ReleasedPDA ["released", sequence / 8192]Solana
OutboundPDA ["outbound"]Acrux
WithdrawalPDA ["withdrawal", sequence]Acrux
Least withdrawalPDA ["minimum", solana_mint]Acrux
NativeGatePDA ["native"]Acrux, from slot 4,752,000
Native burnPDA ["native_burn"]Acrux, from slot 4,752,000

Sequences and epochs in seeds are u64 little-endian.

Bridge

The deposit count and the light client's fixed values.

Discriminator: e7 e8 1f 62 6e 03 17 3b, then the fields in order, Borsh-encoded.

FieldTypeMeaning
depositsu64deposits made so far; the next deposit's sequence number
bumpu8the PDA bump
authoritypubkeythe upgrade authority that initialized it; admits mints and seeds the first set
epoch_slotsu64a bridge epoch's length in Acrux slots
first_epochu64the only epoch the authority can seed directly
seededboolwhether init_validator_set has run
chain_id[u8; 32]prefix of every validator's signed vote, unique to this Acrux chain

AllowedMint

Discriminator: ad e5 b3 2e 79 a4 f7 06, then the fields in order, Borsh-encoded.

FieldTypeMeaning
mintpubkeythe admitted mint

DepositRecord

Discriminator: 53 e8 0a 1f fb 31 bd a7, then the fields in order, Borsh-encoded.

FieldTypeMeaning
sequenceu64the deposit's sequence, from 0
depositorpubkeythe Solana wallet that signed the deposit
recipientpubkeythe Acrux address the deposit is credited to
mintpubkeythe Solana mint
amountu64what the vault received, in the mint's base units
slotu64the Solana slot the deposit landed in
bumpu8the PDA bump

ValidatorSet

Discriminator: 23 ce 61 ca 2b 0b 0b 7f, then the fields in order, Borsh-encoded.

FieldTypeMeaning
epochu64the bridge epoch, slot / 432,000 in Acrux slots
totalu64the sum of the validators' stakes
validatorsValidator[]Acrux's validators in their validator order, each with its stake
payerpubkeyreceives the rent when this account is closed

Validator

FieldTypeMeaning
keypubkeythe validator's identity
stakeu64its stake in lamports

Cblock

Discriminator: 6f b6 c8 21 91 60 1a 1e, then the fields in order, Borsh-encoded.

FieldTypeMeaning
slotu64the cblock's consensus slot
epochu64its bridge epoch, slot × 4 / epoch_slots
hash[u8; 32]the cblock hash the validators vote on
outbox_root[u8; 32]the Merkle root of its outbox
notaru32the validators whose Notar vote was verified, one bit each by index in the set
finalizeu32the validators whose Finalize vote was verified, one bit each by index in the set
certifiedboolFinalize votes hold 60% of the stake, or Notar votes 80%
payerpubkeyreceives the rent when this account is closed

Released

Discriminator: c8 77 7a 05 4b 77 8d f1, then the fields in order, Borsh-encoded.

FieldTypeMeaning
bucketu64sequence / 8192 of the withdrawals it guards
bits[u8; 1024]low bit first within each byte; a bit is set only after the payout succeeds

Outbound

Discriminator: 25 f2 0b 6b f2 9c 46 81, then the fields in order, Borsh-encoded.

FieldTypeMeaning
withdrawalsu64withdrawals made so far; the next withdrawal's sequence
bumpu8the PDA bump

Withdrawal

Discriminator: 0a 2d d3 b6 81 eb 5a 52, then the fields in order, Borsh-encoded.

FieldTypeMeaning
sequenceu64the withdrawal's sequence, from 0
ownerpubkeythe Acrux address that burned it
recipientpubkeythe Solana address paid out of the vault
solana_mintpubkeythe Solana mint the vault pays
amountu64base units burned and paid
slotu64the Acrux slot of the burn; its cblock's outbox carries the withdrawal
bumpu8the PDA bump

NativeGate

Discriminator: 63 cc b2 cb 54 6b 26 41, then the fields in order, Borsh-encoded.

FieldTypeMeaning
solana_mintpubkeythe Solana mint whose deposits are credited as lamports
lamports_per_base_unitu64lamports per base unit, 1,000 for ACRUX
creditedu64lamports credited from Solana, the balances converted at the cut-over included
withdrawnu64lamports withdrawn; never more than credited
reserveu64the fixed reserve, lamports
slotu64the cut-over slot

ProofNode

One step of a Merkle proof: the running hash starts as SHA-256 of the entry's bincode bytes, and each step hashes it with hash on the side left names.

FieldTypeMeaning
leftboolwhether the sibling sits left of the running hash
hash[u8; 32]the sibling hash

Instructions

deposit emits its event by self CPI, so its accounts end with event_authority and program.

InstructionChainSignersDoes
initializeSolanathe program's upgrade authoritycreates the Bridge with the epoch length, the first epoch and the chain tag
allow_mintSolanathe bridge authorityadmits a mint
depositSolanadepositorlocks tokens in the vault and records the deposit
init_validator_setSolanathe bridge authorityseeds the first epoch's validator set, once
post_cblockSolanapayerposts a cblock to certify
attest_cblockSolananonecounts the votes verified in the same transaction
hand_offSolanapayercreates the next epoch's validator set from a certified cblock
releaseSolanapayerpays a proven withdrawal from the vault
close_cblockSolanathe cblock's payerreturns a posted cblock's rent
close_validator_setSolanathe set's payerreturns an old set's rent, keeping the newest two
withdrawAcruxownerburns a bridged token and records the withdrawal
withdraw_nativeAcrux, from slot 4,752,000ownertakes native ACRUX and records the withdrawal

initialize

Only the upgrade authority recorded in the program's ProgramData can call it. epoch_slots is a positive multiple of 4; chain_id is the 32-byte chain tag, SHA-256 of the chain's name, and not all zeros.

Discriminator: af af 6d 1f 0d 98 9b ed.

ArgTypeMeaning
epoch_slotsu64a bridge epoch's length in Acrux slots, 432,000
first_epochu64the epoch init_validator_set seeds
chain_id[u8; 32]SHA-256 of the chain's name, the prefix of every signed vote
#AccountWritableSignerAddressMeaning
0payeryesyesthe program's upgrade authority; becomes the bridge authority and pays the rent
1bridgeyesPDA ["bridge"]created
2programEDm6HxGArNEgGfWRZwvj42f4euc9oPQWVUwUbkK3PEe5this program
3program_datathis program's ProgramData, whose upgrade authority must be payer
4system_programSystem program

allow_mint

Discriminator: f0 1c f0 46 7c f0 f5 e1.

Args: none.

#AccountWritableSignerAddressMeaning
0authorityyesyesthe bridge authority; pays the rent
1bridgePDA ["bridge"]
2mintthe mint to admit, SPL Token or Token-2022
3allowedyesPDA ["allowed", mint]created
4system_programSystem program

deposit

amount is in the mint's base units and more than 0, and the vault must receive more than 0. The vault is created by the mint's first deposit. The depositor pays the record's rent.

Discriminator: f2 23 c6 89 52 e1 f2 b6.

ArgTypeMeaning
amountu64base units to move from source
recipientpubkeythe Acrux address credited
#AccountWritableSignerAddressMeaning
0depositoryesyesowns source; pays the rent
1bridgeyesPDA ["bridge"]its deposits count names the record
2mintan admitted mint
3allowedPDA ["allowed", mint]the mint's admission
4sourceyesthe depositor's token account for the mint
5vaultyesPDA ["vault", mint]the mint's vault: a token account at ["vault", mint] that is its own authority, created by the mint's first deposit
6recordyesPDA ["deposit", bridge.deposits]created at the next sequence
7token_programSPL Token or Token-2022, the mint's owner
8system_programSystem program
9event_authorityPDA ["__event_authority"]self-CPI event signer
10programthis program

init_validator_set

Accepted once, for the Bridge's first_epoch, with 1 to 32 validators in Acrux's validator order.

Discriminator: 77 b4 99 36 0d d5 44 69.

ArgTypeMeaning
epochu64the Bridge's first_epoch
validatorsValidator[]1 to 32 validators with their stakes
#AccountWritableSignerAddressMeaning
0authorityyesyesthe bridge authority; pays the rent
1bridgeyesPDA ["bridge"]
2setyesPDA ["set", epoch]created
3system_programSystem program

post_cblock

The cblock's consensus slot is read from the first 8 bytes of the preimage, and its epoch is slot × 4 / epoch_slots.

Discriminator: 40 44 38 a4 0d a0 1a fe.

ArgTypeMeaning
hash[u8; 32]the cblock hash
outbox_root[u8; 32]its outbox's Merkle root
preimagebytesthe bytes that, followed by the root, hash to hash; its first 8 are the consensus slot
#AccountWritableSignerAddressMeaning
0payeryesyespays the rent and alone can close it
1bridgePDA ["bridge"]
2cblockyesPDA ["cblock", hash]created
3system_programSystem program

attest_cblock

Every Ed25519 program instruction before this one in the transaction is read. Its signatures, public keys and messages must sit in its own data. Each verified signature sets the voter's bit in notar or finalize, by its index in the set.

Discriminator: f9 1f 29 a2 9e 77 49 af.

Args: none.

#AccountWritableSignerAddressMeaning
0bridgePDA ["bridge"]its chain_id prefixes the votes
1cblockyesPDA ["cblock", cblock.hash]the posted cblock
2setPDA ["set", cblock.epoch]the validator set of the cblock's epoch
3instructionsSysvar1nstructions1111111111111111111111111the instructions sysvar

hand_off

The cblock is certified and in epoch epoch − 1. The entry proven is OutboxEntry::ValidatorSet for epoch with the validators in order.

Discriminator: 11 e4 d2 9c 1a dc 9e 65.

ArgTypeMeaning
epochu64the epoch handed on to, one after the cblock's
validatorsValidator[]its validators with their stakes, as the outbox entry lists them
proofProofNode[]the entry's Merkle proof against the cblock's outbox root
#AccountWritableSignerAddressMeaning
0payeryesyespays the rent
1cblockPDA ["cblock", cblock.hash]a certified cblock of the epoch before
2nextyesPDA ["set", epoch]created
3system_programSystem program

release

The entry proven is OutboxEntry::Withdrawal with sequence, the mint, recipient and amount. destination is a token account of the mint owned by recipient.

Discriminator: fd f9 0f ce 1c 7f c1 f1.

ArgTypeMeaning
sequenceu64the withdrawal's sequence
recipientpubkeythe Solana address paid
amountu64base units paid
proofProofNode[]the withdrawal entry's Merkle proof against the cblock's outbox root
#AccountWritableSignerAddressMeaning
0payeryesyessends the release; pays the bucket's rent the first time
1cblockPDA ["cblock", cblock.hash]the certified cblock whose outbox holds the withdrawal
2mintthe Solana mint
3vaultyesPDA ["vault", mint]the mint's vault, which pays
4destinationyesrecipient's token account for the mint
5releasedyescreated by the bucket's first release
6token_programSPL Token or Token-2022, the mint's owner
7system_programSystem program

close_cblock

Discriminator: b8 46 93 a2 30 f7 f9 4f.

Args: none.

#AccountWritableSignerAddressMeaning
0payeryesyesthe cblock's payer; receives the rent
1cblockyesPDA ["cblock", cblock.hash]closed

close_validator_set

newest is at least two epochs after set.

Discriminator: 31 bd da 9d 06 4a fb cf.

Args: none.

#AccountWritableSignerAddressMeaning
0payeryesyesthe set's payer; receives the rent
1setyesPDA ["set", set.epoch]closed
2newestPDA ["set", newest.epoch]a set at least two epochs later

withdraw

amount is more than 0 and at least the mint's least withdrawal. The owner pays the record's rent, and the first withdrawal's for Outbound.

Discriminator: b7 12 46 9c 94 6d a1 22.

ArgTypeMeaning
solana_mintpubkeythe Solana mint the bridged token stands for
amountu64base units to burn, at least the mint's least withdrawal
recipientpubkeythe Solana address paid
#AccountWritableSignerAddressMeaning
0owneryesyesowns source; pays the rent
1mintyesPDA ["mint", solana_mint]the bridged mint
2minimumPDA ["minimum", solana_mint]the mint's least withdrawal; an empty address for none
3sourceyesthe owner's token account for the bridged mint
4outboundyesPDA ["outbound"]created by the first withdrawal
5recordyesPDA ["withdrawal", outbound.withdrawals]created at the next sequence
6token_programSPL Token
7system_programSystem program

withdraw_native

amount is in the Solana mint's base units, more than 0 and at least its least withdrawal; the owner's wallet pays it times the gate's scale in lamports, beside the fee and the rent. A withdrawal past what has been credited from Solana and not yet withdrawn is refused with UnbackedNativeWithdrawal. The owner pays the record's rent, and the first withdrawal's for Outbound.

Discriminator: 71 e3 1a 20 35 42 5a fa.

ArgTypeMeaning
amountu64base units of the Solana mint, at least its least withdrawal
recipientpubkeythe Solana address paid
#AccountWritableSignerAddressMeaning
0owneryesyespays amount times the gate's scale in lamports, and the rent
1nativeyesPDA ["native"]the native gate
2minimumPDA ["minimum", native.solana_mint]the mint's least withdrawal
3burnyesPDA ["native_burn"]takes the lamports; the executor removes them at the end of the slot
4outboundyesPDA ["outbound"]created by the first withdrawal
5recordyesPDA ["withdrawal", outbound.withdrawals]created at the next sequence
6system_programSystem program

Events

EventFieldsEmitted by
Depositedsequence: u64; depositor: pubkey; recipient: pubkey; mint: pubkey; amount: u64; slot: u64deposit

Errors

Anchor custom errors, returned as custom program error: 0x… with the code below.

CodeNameMessage
6000ZeroAmountA deposit moves more than nothing.
6001BadEpochAn epoch is a positive number of cblocks.
6002BadSetA validator set holds 1 to 32 validators.
6003BadPreimageThe preimage and outbox root do not hash to the cblock's hash.
6004BadVoteA signature is not a validator's Notar or Finalize vote on this cblock.
6005NotCertifiedThe cblock is not certified in the epoch before the set it hands on.
6006BadProofThe validator set is not in the cblock's outbox.
6007RecentValidatorSetThe newest two validator sets stay open.
6008NotUpgradeAuthorityOnly the program's upgrade authority can initialize the bridge.
6009AlreadySeededThe first validator epoch can be seeded only once.
6010BadChainIdThe chain tag must be set.
6011AlreadyReleasedThis withdrawal has already been released.
6012InvalidMinimumThe withdrawal minimum account is invalid.
6013BelowMinimumWithdrawalThe withdrawal amount is below this mint's configured minimum.
6014InvalidNativeGateThe native bridge gate or burn account is invalid.
6015NativeAmountOverflowThe native withdrawal amount overflows its configured scale or counter.
6016UnbackedNativeWithdrawalThe native withdrawal exceeds the tokens credited from Solana.
6017AlreadyBurnedThis fee-burn epoch has already been burned.
6018BadFeeBurnEpochA fee burn belongs to the last cblock of its epoch.
6019WrongFeeBurnMintFee burns use the immutable configured native mint.