Skip to main content

Bridging with subfrost-cli fractal

subfrost-cli fractal builds the same routed actions the SUBFROST apps do, through the same wallet core and with the signers' own encoder. Every route is quoted live, every minimum is margined, and the gateway address is recomputed locally and compared with the gateway service's before anything is signed.

Fractal mainnet is paired with Bitcoin mainnet only, so every fractal command refuses any other --network. The wallet's Fractal address is its Bitcoin taproot address. Wallet flags are the CLI's global ones (--keystore FILE --password-file FILE, or a mnemonic), and only the commands that sign use them.

Look before you deposit​

subfrost-cli fractal info                          # fb-vault, the gateway service's /v1/vault (K, minimum, routes), heights
subfrost-cli fractal routes                        # supported pairs and route legs
subfrost-cli fractal routes --from FB --to frBTC --amount 5000000000   # a live route quote
subfrost-cli fractal quote --amount 5000000000     # what a plain deposit mints
subfrost-cli fractal balance                       # FB on Fractal, frFB on Bitcoin

fractal info shows the gateway service's routes object: the route fee, the gas fee, the BTC unwrap floor, the contract ids, and max_action_version. FIRE, frUSD and the gas split use action version 2, which the service reports as 2. The CLI refuses version-2 routes whenever it does not, rather than build an address the signers would treat as plain frFB.

Deposit with a route​

subfrost-cli fractal deposit --recipient <btc address> --amount <FB sats> --fee-rate <sat/vB> \
  --route plain|btc|diesel|lp|fire|frusd|stable \
  [--gas diesel|btc --gas-bps N] \
  [--route-margin-bps 300..500] \
  [--dry-run] [--out PLAN] [--state FILE] [--no-track] [-y]
  • --amount is in FB sats (1 FB = 100,000,000).
  • --route-margin-bps is the slippage margin taken off every quoted minimum: 300 to 500, default 500. A value outside that range is refused, never clamped.
  • --gas diesel|btc --gas-bps N splits N basis points (1 to 5,000) of the routed frFB off as gas. Allowed gas per route: plain, LP, FIRE, frUSD and STABLE take diesel or btc; DIESEL takes btc; BTC takes none. With --route plain the rest stays frFB. See the gas split.
  • --dry-run quotes, derives and prints the plan (legs, minimums, action bytes, the address) and stops. --out PLAN keeps it; fractal sign-send PLAN signs and sends it later, after re-checking the wallet's UTXOs and the vault script.
  • Routed deposits must be at least 7 FB (30 FB for STABLE). The CLI then checks that the route fee and the routed minimums leave every leg above zero and, for a BTC route or BTC gas, above the unwrap floor.
  • Coin selection never spends a Fractal UTXO carrying an inscription, rune, atomical or protofractal alkane.

Examples:

# 50 FB -> FIRE, 10% of it as DIESEL gas
subfrost-cli fractal deposit --recipient bc1p… --amount 5000000000 --fee-rate 2 \
  --route fire --gas diesel --gas-bps 1000 --dry-run

# 20 FB -> frFB, 20% of it unwrapped to BTC for fees
subfrost-cli fractal deposit --recipient bc1p… --amount 2000000000 --fee-rate 2 \
  --route plain --gas btc --gas-bps 2000

# 30 FB -> frUSD kept on Bitcoin, 20% as BTC gas
subfrost-cli fractal deposit --recipient bc1p… --amount 3000000000 --fee-rate 2 \
  --route frusd --gas btc --gas-bps 2000

STABLE (USDC / USDT on an EVM chain)​

subfrost-cli fractal stable-check --to-chain 56 --to-token USDT      # is this payout path served today?

subfrost-cli fractal deposit --recipient bc1p… --amount 5000000000 --fee-rate 2 \
  --route stable --to-chain 56 --to-token USDT --evm-recipient 0x… [--gas-drop-bps 500]
  • --to-chain is the destination chain id (Base 8453, Polygon 137, BNB Chain 56; default 56); --to-token is USDC or USDT (default USDT). --evm-recipient is EIP-55 checked.
  • --gas-drop-bps N (1–1,000) pays N bps of the payout in the destination's native token. Its registration is posted automatically and unsigned right before the FB deposit is signed; a refused registration aborts with nothing signed. The EVM recipient signs nothing and may be any address.
  • subfrost-cli fractal gas-drop-status <handler> --chain 56 shows pending until the peg-out to the handler is seen on chain, then admitted. fractal gas-drop-register --from PLAN retries a registration by hand.
  • --recipient is still a Bitcoin address you control: any refund lands there.

Just the address​

subfrost-cli fractal deposit-address --recipient <btc> [--sweep-fee K] [--amount N] \
  [--route … | --action-hex H] [--local-only]

prints the gateway address for a recipient and route. It derives the address locally against the live vault script, has the gateway service derive and register the same intent (unless --local-only), and refuses unless the two agree field for field. --action-hex takes a raw action, validated with the signers' decoder.

Tracking​

subfrost-cli fractal track STATE
subfrost-cli fractal track --recipient <btc> | --address <gateway> [--txid T]   [--once] [--interval S] [--wake]

fractal deposit writes a tracking record (under ~/.subfrost-cli/fractal/ unless --state) before signing, and follows it unless --no-track. Tracking runs through the seven stages (seen, confirmed, swept, credited, mint in the mempool, mint confirmed, frFB indexed), then reports the route's delivery: the mint and each child transaction, what landed at the recipient, the gas leg's state, and BTC from the frBTC signer for a BTC route or BTC gas. A STABLE payout continues with subfrost-cli pegout track. Ctrl-C is safe: run the same command on the same file to resume.

If the gateway service has not swept a deposit, fractal self-sweep STATE --outpoint TXID:VOUT broadcasts the covenant sweep yourself. It is paid out of K and needs no other funds.

frFB on Bitcoin: swap and redeem​

# frFB <-> frBTC on SUBFROSTAMM 2:102725 (pair with wrap / unwrap for BTC)
subfrost-cli fractal swap --from frFB --to frBTC --amount N [--min-out M | --slippage-bps B] --dry-run

# frFB -> FB: burn on Bitcoin (4:88888 opcode 88), FB paid to --to on Fractal
subfrost-cli fractal redeem --amount N [--to <fractal address>] --simulate-call
subfrost-cli fractal redeem --amount N [--to <fractal address>] --fee-rate 2 [--dry-run]
subfrost-cli fractal redeem-track STATE

Both are built as reviewable tx plans, checked and simulated before you are asked to sign. A redeem first simulates the Burn call on live state, so a destination frFB would refuse fails before anything is built. See Redemption.