NETConnecting

Docs Build

Move tokens across

Deposit ACRUX from Solana mainnet to Acrux and withdraw it back through acrux_bridge, one program at one address on both chains, and follow each transfer to its end.

ACRUX crosses between Solana mainnet and Acrux through acrux_bridge, one program at one address on both chains. A deposit locks ACRUX in the program's vault on Solana and is credited on Acrux. A withdrawal burns it on Acrux and is paid from the vault once Solana's light client of Acrux certifies the cblock that carries it.

Program, on both chainsEDm6HxGArNEgGfWRZwvj42f4euc9oPQWVUwUbkK3PEe5
On SolanaACRUX, the one mint the bridge takes (ACRUX)
On Acruxnative ACRUX from slot 4,752,000, 1,000 lamports per base unit; before it, an SPL token at CoN68LBvgfADtuKXXZMq3PwJsTkAfb2yGmVUyfrn8yPE, the program's PDA ["mint", ACRUX mint], with the same 6 decimals
Least withdrawal1 ACRUX
FromAcrux slot 2,711,660
Follow it/bridge, GET /v1/bridge, GET /v1/bridge/transfers

/bridge deposits with a Solana wallet and withdraws with the key in your browser or a wallet, and draws each transfer's trail. This page does the same from code. From slot 4,752,000 bridged ACRUX is the native balance that pays Acrux's fees (Native ACRUX); before it, it sits in a token account beside that balance.

Install

Terminal
npm install https://acrux.computer/downloads/acrux-contract-0.1.21.tgz @coral-xyz/anchor@0.31.1 @solana/web3.js @solana/spl-token

ACRUX_BRIDGE_IDL in @acrux/contract is the program's IDL, and Anchor builds every instruction below from it. Every account and instruction is on Bridge program.

Deposit from Solana

  1. Hold ACRUX and SOL on Solana

    The depositing wallet holds ACRUX in its associated token account, and SOL for the fee and the deposit record's rent, 0.00178872 SOL, which stays with the record.

  2. Send deposit

    deposit takes the amount in base units and the Acrux address to credit. The record's address comes from the bridge's deposit count, so read it first:

    bridge.mjs
    import anchor from '@coral-xyz/anchor'
    import { Connection, Keypair, PublicKey } from '@solana/web3.js'
    import { TOKEN_PROGRAM_ID, getAssociatedTokenAddressSync } from '@solana/spl-token'
    import { ACRUX_BRIDGE_IDL } from '@acrux/contract'
    const { AnchorProvider, BN, Program, Wallet } = anchor
    
    const ACRUX = new PublicKey('<ACRUX mint>') // on /docs/token
    const solana = new Connection('<a Solana mainnet RPC>', 'confirmed')
    const wallet = new Wallet(Keypair.fromSecretKey(/* your Solana key */))
    const bridge = new Program(ACRUX_BRIDGE_IDL, new AnchorProvider(solana, wallet))
    const pda = (...seeds) => PublicKey.findProgramAddressSync(seeds, bridge.programId)[0]
    const u64 = (n) => new BN(n.toString()).toArrayLike(Buffer, 'le', 8)
    
    const { deposits } = await bridge.account.bridge.fetch(pda(Buffer.from('bridge')))
    const signature = await bridge.methods
      .deposit(new BN(5_000_000), new PublicKey('<your Acrux address>')) // 5 ACRUX
      .accountsPartial({
        depositor: wallet.publicKey,
        mint: ACRUX,
        source: getAssociatedTokenAddressSync(ACRUX, wallet.publicKey),
        record: pda(Buffer.from('deposit'), u64(deposits)),
        tokenProgram: TOKEN_PROGRAM_ID,
      })
      .rpc()

    Anchor fills in the bridge, the mint's admission, the vault and the event accounts from their seeds. If another deposit lands between the read and the send, the record's address has moved on and the transaction fails on its seeds: read the count again and send again.

  3. Credited on Acrux

    Once two independent Solana RPCs show the deposit finalized, the next Acrux block carries its credit, and every validator checks it against the same finalized record before the slot executes. From slot 4,752,000 the credit adds the amount to the recipient's native balance, 1,000 lamports per base unit, and wallets show it as the address's ACRUX:

    bridge.mjs, continued
    const acrux = new Connection('https://rpc.acrux.computer', 'confirmed')
    console.log((await acrux.getBalance(new PublicKey('<your Acrux address>'))) / 1e9, 'ACRUX')

    Before that slot the credit mints the amount into the recipient's associated token account for the bridged mint, opened by the credit when the recipient has none, and wallets list it with the account's other tokens:

    bridge.mjs, continued
    const held = getAssociatedTokenAddressSync(pda(Buffer.from('mint'), ACRUX.toBuffer()), new PublicKey('<your Acrux address>'))
    console.log((await acrux.getTokenAccountBalance(held)).value.uiAmountString)

Withdraw from Acrux

  1. Open the recipient's token account on Solana

    The vault pays only into the Solana recipient's associated token account for ACRUX. Open it before or after the withdrawal; until it exists, the withdrawal waits with releaseError set and is tried again every minute:

    bridge.mjs, continued
    import { createAssociatedTokenAccountIdempotent } from '@solana/spl-token'
    
    await createAssociatedTokenAccountIdempotent(solana, wallet.payer, ACRUX, new PublicKey('<Solana recipient>'))
  2. Send withdraw_native on Acrux

    From slot 4,752,000 the same program on Acrux takes the amount from the key's native balance, which also pays the fee and the withdrawal record's rent. amount is in ACRUX base units, 6 decimals. The record's address comes from the withdrawal count in ["outbound"]:

    bridge.mjs, continued
    const key = Keypair.fromSecretKey(/* your Acrux key */)
    const onAcrux = new Program(ACRUX_BRIDGE_IDL, new AnchorProvider(acrux, new Wallet(key)))
    
    const outbound = await acrux.getAccountInfo(pda(Buffer.from('outbound')))
    const withdrawals = outbound ? outbound.data.readBigUInt64LE(8) : 0n
    await onAcrux.methods
      .withdrawNative(new BN(2_000_000), new PublicKey('<Solana recipient>')) // 2 ACRUX
      .accountsPartial({
        owner: key.publicKey,
        minimum: pda(Buffer.from('minimum'), ACRUX.toBuffer()),
        record: pda(Buffer.from('withdrawal'), u64(withdrawals)),
      })
      .rpc()

    A withdrawal under 1 ACRUX is refused with BelowMinimumWithdrawal.

    Before slot 4,752,000 withdraw burns the bridged token instead, and the key holds native ACRUX for the fee and the rent, which the faucet gives until that slot:

    bridge.mjs, continued
    await onAcrux.methods
      .withdraw(ACRUX, new BN(2_000_000), new PublicKey('<Solana recipient>')) // 2 ACRUX
      .accountsPartial({
        owner: key.publicKey,
        source: getAssociatedTokenAddressSync(pda(Buffer.from('mint'), ACRUX.toBuffer()), key.publicKey),
        record: pda(Buffer.from('withdrawal'), u64(withdrawals)),
        tokenProgram: TOKEN_PROGRAM_ID,
      })
      .rpc()
  3. Released on Solana

    The withdrawal is written into the outbox of the cblock its slot belongs to, and the outbox's Merkle root is part of the hash the validators vote on. Once that cblock is final, its votes are posted to the program on Solana, which checks them against the epoch's validator set and certifies the cblock. release then proves the withdrawal against the cblock's outbox root and pays the recipient from the vault, once per withdrawal. Acrux's relayer sends these every 15 seconds, and anyone can send release with the proof from getCblockProof.

The trail

GET /v1/bridge/transfers lists every transfer, newest first; ?address= keeps those from or to one address, on either chain. Each has one of five states:

statusKindMeans
lockeddepositin the vault on Solana, not yet credited on Acrux
crediteddepositthe credit executed on Acrux
burnedwithdrawalburned on Acrux and written into its cblock's outbox
certifiedwithdrawalthat cblock certified by the light client on Solana
releasedwithdrawalpaid from the vault; releaseAccount holds its paid bit

A withdrawal not yet released carries the reason of its last payout attempt in releaseError, such as "The recipient has no token account for this token on Solana. Create it, and the withdrawal is paid." GET /v1/bridge gives the vaults, the bridged supply on Acrux, the native counters from the cut-over, the light client's epoch and newest certified cblock, and the totals.