Skip to content
ConcatenaLabsPublic

About

Ambra: non-custodial dual-chain (Bitcoin testnet4 + Sequentia) mobile wallet. Flutter UI over a Rust core (ambra_core) built on SWK: balances, send/receive, any-asset fees, RBF/CPFP, staking, asset issuance, and SeqDEX swaps.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

538 Commits

Folders and files

Repository files navigation

Ambra

Ambra is a non-custodial dual-chain mobile wallet for Bitcoin (testnet4) and Sequentia: a Flutter UI over a shared Rust core (ambra_core) built on SWK, the Sequentia Wallet Kit. One 12-word recovery phrase controls both chains, and the same tb1... address receives Bitcoin and Sequentia assets alike: Sequentia is transparent by default and its default addresses use Bitcoin's own bech32 format, so BTC is a first-class asset in the wallet, not an add-on.

Everything here is testnet software (Bitcoin testnet4 + the public Sequentia testnet). There is no mainnet. Coins and assets have no value.

Sequentia itself is a Bitcoin sidechain for asset tokenization and disintermediated exchanges. Protocol documentation lives in the node repo: Sequentia doc/sequentia/.

Get the app

  • Download the Android APK from https://sequentiatestnet.com/download/. That page always names the current release; this file deliberately does not, because a version pinned in prose goes stale the next time the publisher runs. Allow "install unknown apps", then open the .apk.
  • Ambra also ships as a Chromium browser extension, the same dual-chain wallet built from sequentia-extension, offered on the same download page.
  • iOS is not released. The app/ios/ scaffold exists but iOS bring-up has not happened (it needs a macOS + Xcode machine).
  • Free testnet funds: the in-app faucet (More tab) dispenses BTC (testnet4: on the Bitcoin ark in seconds, at a receive code carrying the ark address, faucetBtcTo, said to have arrived once the ark wallet has synced; else on chain to the wallet's address), tSEQ and the demo assets. In user mode the faucet pays the wallet's receive code, and the wallet reads its mailbox for the coin at once, so it shows as received in seconds (the address if the faucet refuses the code, though never only because the faucet is busy); in developer mode, a wallet that joined an operator can ask to be paid as a leaf instead. The faucet pays each asset once per wallet: every request names the wallet by its id (app/lib/src/data/faucet_wallet.dart, the same for one phrase in every Sequentia wallet), a button whose asset the wallet has received reads " received" and is off, and more of that asset comes from trading for it.

What the wallet does

Each item below is implemented in this repo; the file pointers name the screen or module that implements it.

Wallet and custody

  • Create a wallet (12-word BIP39 phrase, word grid + verification quiz) or import an existing phrase (app/lib/src/screens/onboarding.dart). The phrase is stored only in platform secure storage (Android Keystore-backed encrypted preferences / iOS Keychain) and is read out transiently for signing, never cached (app/lib/src/data/wallet_repository.dart).
  • Opt-in app lock (biometrics or device PIN) that engages on cold start and whenever the app is backgrounded; revealing the recovery phrase always requires authentication.
  • Reveal recovery phrase and remove wallet (deletes the phrase from the device), both from the More tab.
  • Keylogger-immune phrase import: the import path uses an on-screen keyboard with BIP39 autocomplete, so no system IME ever sees the words; free-text paste remains as a fallback (app/lib/src/screens/recover_screen.dart).
  • OpenAMP tagged signing: sign a wallet-link/login challenge or a document hash for an OpenAMP-integrated site, opened from an oamp-sign deep link (app/lib/src/screens/sign_screen.dart).
  • Classic message signing on the same screen: sign with the key behind one of the wallet's own addresses, in the format verifymessage accepts, so anyone with a node can check that an address is yours. Neither signature can move funds. Verification is offered against the legacy form of the address, the only form that RPC takes.
  • CoinJoin: mix a Sequentia asset in a seqcj round, from the More tab. The amounts are confidential, so the chain sees a transaction and not what moved in it, and the change is blinded like the mixed coins; what the blind signatures buy is that the coordinator cannot link the coins going in to the mixed coins coming out. The screen says the rest plainly — the coordinator sees your amounts, the phone connects from one address, and the anonymity set is the round (app/lib/src/screens/mix_screen.dart).

Balance (dual-chain, no privileged asset)

  • The headline is one total balance across all held assets and everything held of each, valued in a user-chosen reference currency (USD default; picker in the top bar, fed by the public price server), in both modes, hidden assets included. Below it, every held asset is one equal row: BTC (Bitcoin testnet4) first, listed at 0 too, then tSEQ, issued assets and OpenAMP restricted assets side by side (app/lib/src/screens/shell.dart).
  • An asset's figure counts everything the wallet holds of it: on-chain coins, leaves (the leaf library's held less its own on-chain coins, which sit at the phrase's keys and are counted on-chain, so a leaf taken home by its exit counts once, as the coin on the chain), Lightning (the wallet's own channels in a CHANNELD_* state, its share with the channel reserve, balance_units, or spendable_units from an LSP that does not report it) and, for the Sequence token, what is staked (each bonded stake under either lock, each unbonding output not yet returned, and the delegation record; a stake returned to the wallet is on-chain again and counted there once), and what the wallet holds that cannot move before a date (see "What vests later" below). User mode shows one figure per row; a tap on the row shows what is staked, if any. What is still arriving is in the figure and is said only when a person tries to send it. Developer mode shows the parts beside each row, what is arriving, moving, redone or kept safe under it, with the Lightning controls (app/lib/src/data/portfolio.dart, app/lib/src/data/stakes.dart). What a payment can use is the spendable part, not the figure.
  • Both chains sync against Esplora-style REST APIs; last-known balances are cached on disk and shown instantly on launch, with an explicit offline/stale indicator when a scan fails.

Receive

  • One shared tb1... address for both chains, with QR code and cross-chain index cycling ("New address" and "New code" move to the next address, discouraging reuse). A new address is never 20 or more past the first one no scan has seen used: past that it goes back to that one, so every address handed out is found by a scan from the phrase alone after a restore (app/lib/src/data/receive_index.dart).
  • Opt-in confidential Sequentia address (blech32, tsqb1...) that hides amount and asset on-chain; the screen then also shows the matching transparent tb1 form, which is the one that can receive Bitcoin.
  • OpenAMP account id + enclave deposit address for receiving restricted assets, shown when the OpenAMP service is reachable.
  • The account key, on request, for a watch-only import elsewhere: the extended public key ([fingerprint/84h/1h/0h]tpub...) or a checksummed descriptor pair, receive and change, in the wpkh(...) form that matches this wallet's addresses or the legacy pkh(...) form. One key covers both chains, which share the m/84'/1'/0' account.

Send

  • Sequentia send of any held asset, with the signature Sequentia feature: an any-asset fee picker. The fee asset follows the wallet rule wherever Ambra builds a Sequentia transaction (app/lib/src/data/fee_asset_rule.dart): the asset being moved when the node accepts it, else the accepted asset whose largest coin covers the most fees. The Sequence token is never a default or a fallback; a wallet holding nothing the node accepts is told so. Any accepted asset can be picked instead, at the node's published exchange rates, the Sequence token's included. Optional fee-rate override, always denominated in the chosen fee asset's own units per vByte (never sat/vB; sats are Bitcoin-only) (app/lib/src/screens/send_screen.dart).
  • One asset picker, shared with the swap composer (app/lib/src/widgets/asset_sheet.dart): BTC first and picked by default, listed even at 0; then every asset the wallet holds on any rail (on-chain, Lightning, leaves); a search over every registry asset, or a pasted asset id, reaches the rest. The list scrolls, whatever its length and the screen's.
  • Bitcoin (testnet4) send: BTC pays its own fee in sat/vB (correct there, it is the Bitcoin chain).
  • A Lightning invoice, scanned or pasted into the recipient field, opens the Lightning pay screen, for BTC and for Sequentia assets (lntsqt… on the testnet).
  • The phone's signer approves Lightning payments up to a daily limit of 1,000 US dollars, held in each asset at the node's rate (Bitcoin at the price feed's), so it is worth the same in every asset (app/lib/src/data/ln_payment_limit.dart). A payment over it is refused in plain words and nothing is sent; developer mode sets another figure under More > Lightning payment limit.
  • QR scanning of recipient addresses using the first-party CameraX preview plus a pure-Dart ZXing decoder (zxing2), so the app needs no Google ML Kit and no Play Services (app/lib/src/screens/scan_screen.dart).
  • OpenAMP restricted assets are sent by account id through the enclave's transfer-approval flow (app/lib/src/data/openamp_service.dart).

History and stuck-transaction rescue

  • Transaction history with kind badges, per-asset deltas, and explorer deep links.
  • Each trade of the Swap tab is one row at the top: "Swapped for ", its time and, until settled, its status, with the amounts as -/+ and the fee (tradeHistoryRows, app/lib/src/screens/history_screen.dart).
  • In default mode a Sequentia transaction of the wallet's that has waited two blocks is sped up by itself, by a child that pays for both, the rate doubling at each further wait (app/lib/src/data/speed_up_service.dart); its row then reads "Taking longer than usual: the wallet paid a little more to speed it up." A coin received out of round is refreshed at the next round by itself wherever the operator can fund it (autoRefreshReceived, app/lib/src/data/leaf_service.dart), and still pays and trades meanwhile.
  • In developer mode, rescue actions on unconfirmed transactions (app/lib/src/screens/rescue_screen.dart):
    • RBF bump: re-send the same payment at a higher fee,
    • RBF replace: same inputs, brand-new recipient/asset/amount,
    • CPFP: pay a child fee, in any asset, to pull the parent in (with a suggested child fee rate from the core).

Swap (SeqDEX)

  • In user mode (the default) the Swap tab is a trading screen (app/lib/src/screens/user_composer.dart, its engine app/lib/src/data/user_trade.dart, the web wallet's user-composer.js and user-trade.js in Dart; the words follow the web wallet's docs/DEFAULT_MODE.md):

    • the chosen pair's market above it (app/lib/src/widgets/market_view.dart, data and words in app/lib/src/data/market_view.dart): the pair as "base / quote", its last price and 24-hour change, the day's high, low and volume, a step chart over 1D, 1W and 1M, the best bid and ask with the book's depth on each side, and the recent trades, all read from SeqDEX's relay every five seconds;
    • You pay and You receive, each an asset and an amount. Both pickers are the wallet's one asset chooser (app/lib/src/widgets/asset_sheet.dart): a search box, "Your assets" first (BTC always, then what the wallet holds, with balance and value), what the book offers now next, hidden assets left out until searched for. The two amounts are tethered: the one typed stays, the other follows the book's best price now (UserTradeEngine.estimate, no maker asked for firm terms), with "The book can fill up to … now." when it cannot, and reads "about" until Review. Under You pay, its balance and Max; between the two, ⇅ swaps the sides, each amount riding with its asset;
    • Review ("Getting the exact price…": the best four sources asked at once, the next four when none answers, each given 8 s from the asking (20 s when the BTC desk is the only source), a late answer left out and released; what the wallet itself checks of a price given in time is waited for up to 30 s more while no other is in hand, and the button then reads "Still getting the exact price: this can take up to half a minute…"; what the wallet can pay is taken from its last reading, never waited for behind the library; with no price 45 s after Review it says "Your wallet is still finishing something it started, so it could not get a price in time…" and lets a later price go), then Trade, which frees the screen after 1.5 s: the trade goes on under Open as "Sending…", then Sent, "Received, settling" and Settled, the same words as History.
    • What was entered, and a price being asked for, is kept across the background, the app lock and a restart (draftKey); the lock covers the open wallet instead of closing its screens.
    • BTC held at the wallet's address, none yet on the Bitcoin ark, is moved there for a trade that needs it (a board of at most the server's largest coin), and the trade says so and is priced again by itself; by itself the wallet keeps at most four such boards on the ark.

    BTC heads both pickers; You pay lists BTC and the assets the wallet holds, so a brand-new wallet lists BTC alone, and You receive adds what the book offers for the asset paid, and each picker shows what the wallet holds of an asset as its one figure on the balance (heldFigure, app/lib/src/data/ln_rail.dart: BTC in the wallet's own Bitcoin Lightning node included), while a trade is bounded by what can be spent now. The wallet's Lightning channels are read apart from the on-chain sync, so a sync that fails hides none of them. Review shows what you pay, what you receive and one line of fees, each in the asset it is paid in, before anything is signed; Trade confirms it, and the trade then reads Sent, Settled once its settling round is final, or Returned: nothing traded., with nothing to do either way. A row states a wait only as the leaf library states it, and otherwise the minutes it has waited: buying with BTC, until the asset is held for the wallet, "Keep the app open: your BTC is paid once what you buy is held for you, within about N minutes. Nothing has left your wallet yet. If the app closes first, nothing is traded." (N from lightning_receive_ready, and before its first answer the library's figure for the operator's next round), then "Paying your BTC. Keep the app open a moment more." and "Paid. What you bought is arriving, and it comes to your wallet even if the app closes." (the operator is handed the proof at once); a received trade settling in a round, "Received, settling (within about N min)" (the wallet's figure for a round of its operator). Past a stated wait by two minutes the row says it is taking longer than usual. Such trades are followed every few seconds. When what is paid waits only for the operator's next round (coins just received and not yet settled, too many payments from a round, of a format the other side does not read, or every coin of the asset in a round the wallet's own upkeep started), Review shows a ticket to accept now: You receive "about" the price now, "You receive at least … after fees, or the trade comes back and nothing is traded.", and "Goes through within about N minutes" as the leaf library states it ("Goes through by itself once what you pay is ready" until it does). Only Trade gives those coins to the round (settle_first); once through, the trade is priced again and goes by itself at that least or better, or reads "Returned: nothing traded. The price moved while it waited.", or, past twice the library's wait (ten minutes at least), "Returned: nothing traded. It took too long to get ready." A confirmation the library refuses for the same reason waits the same way, never failing. When the other side says its offer is gone (the network refused its completion), or a coin the trade paid from was spent elsewhere, the wallet takes its coins back at once and prices the trade again in the same row, going ahead only at the price accepted or better, the other side's own new offer first; otherwise "Returned: nothing traded. The price moved while it waited.", and after three gone offers "Returned: nothing traded." A pair offered within the last three minutes that nobody offers this moment reads "Getting a price for for : it takes a moment. Nothing has moved." and is asked again every few seconds. The phone keeps every unfinished trade's record and the newest 200 ended ones (1 MB at most); a trade whose record cannot be kept is not made, and nothing is signed. A purchase with BTC whose maker's invoice runs out while it waits asks the maker for a new one under the same hash, amount, lock and fee, and never pays one that ran out; when there is none, it reads "Returned: nothing traded. The other side's offer ran out while the trade waited." It trades only what settles in one step from the wallet's coins in a leaf operator's tree: an in-tree swap with a live leaf maker, a transparent covenant order taken in the operator's round, or an order resting in the operator's tree filled in one transfer the operator co-signs, choosing the one that gives the most, then the one with the fewest parties left to act. A covenant order is taken only as far as the operator can fund its round now (the fundable figure its info gives per asset), so a take never waits in a round for coins the operator does not have. It offers only the pairs the web wallet's reliability drill has passed on the chain (the web wallet's user-mode/pairs.json, read from the node's origin), and says "Not offered right now" in plain words for one nobody fills in one step; no screen of it names a rail, a round, a leaf, the operator, a covenant, an expiry or an atom. BTC trades against an asset the same way, in one hash-lock: the asset moves in the operator's tree and the BTC over Lightning, under the hash of whoever receives the BTC (app/lib/src/data/user_trade_btc.dart), with the leaf maker that quotes BTC at the node's origin (/leafmaker-btc, beside the in-tree maker at /leafmaker). In user mode the BTC is the wallet's BTC on the Bitcoin ark (app/lib/src/data/ark_btc_lightning.dart): buying with BTC pays the maker's invoice out of the ark, and selling for BTC is an invoice of the ark's, claimed into it, so no channel room is needed. When the ark is not open, and always in developer mode, it is the wallet's own hosted Bitcoin Lightning node (app/lib/src/data/btc_lightning.dart): selling makes a hold under a hash the wallet makes itself, its preimage kept on the phone and handed to the node only to settle a payment held there for the whole amount. A trade is finished on the rail it was priced on. Either way the wallet pays the maker's invoice only once the asset it receives is held for good, its fee and lock capped at the ones the ticket showed. The screens below are developer mode's.

  • One book, every rail: developer mode's composer matches against the unified order book, every relay's offers for the pair merged by price (the hosted-node service's /book/unified, the book the web wallet reads; app/lib/src/data/unified_book.dart). Its best offer on the side taken shows under the price, with where it rests, and stays the same whichever rails are chosen: the rails decide how the trade settles, never which offer it matches.

  • Same-chain atomic swap: pay one Sequentia asset, receive another, settled in a single atomic transaction against the SeqDEX daemon's order book (app/lib/src/screens/swap_screen.dart). The review sheet states finality honestly: it confirms in about one block and is final once its Bitcoin anchor is buried.

  • Cross-chain buy: buy a Sequentia asset by locking BTC in a testnet4 HTLC (app/lib/src/screens/xchain_swap_screen.dart). The preimage reveal is hard-gated on verifying the Sequentia leg's Bitcoin anchor; in-flight swaps persist across restarts and a BTC refund path opens after the timeout.

  • Instant (Lightning): a pure-Lightning BTC<->asset rail through the public hosted SeqLN LSP, non-custodial via an on-device signer (app/lib/src/screens/lightning_swap_screen.dart). It is on by default: the released APK points at wss://sequentiatestnet.com/lsp-ws-asset and /lsp-ws-btc with pinned host keys (Backend in app/lib/src/data/config.dart). Pointing the wallet at a custom node clears these, because a custom node has no hosted LSP, and the rail goes dark until you return to the default.

  • Peer-to-peer submarine swap: a rail crossing on the BTC leg settled directly with an interactive maker, no LSP in the value path. A buy pays Bitcoin over Lightning and receives the asset in one on-chain HTLC bound to the same secret; a sell funds the asset HTLC (app/lib/src/screens/submarine_swap_screen.dart).

  • Sub-asset rails: buy or sell a Sequentia asset over Lightning against Bitcoin on the testnet4 chain, served by the LSP (app/lib/src/screens/subasset_buy_screen.dart, subasset_sell_screen.dart).

  • Cross-market lift and walk: buy an asset with Bitcoin against one resting cross offer at a live maker quote fetched over the relay courier (app/lib/src/screens/cross_lift_screen.dart), or sweep several resting offers best price first, one leg at a time through the same path (app/lib/src/screens/cross_walk_screen.dart). The BTC is refundable after the timeout and the secret reveals only on an anchor-safe asset leg.

  • My orders: the maker's own resting covenant orders (funded on-chain, posted to the relay) with a reclaim path (app/lib/src/screens/my_orders_screen.dart).

The mode, and leaves

  • More > Mode is one setting, kept for each wallet, in the words every Sequentia wallet uses. User mode (the default): one figure per asset, and the wallet chooses how value moves. Developer mode: every rail by name, side by side (on-chain, leaves and Lightning), each with its balance and its manual controls, and the developer tools: each balance row splits into on-chain, leaves, Lightning and staked, with the Move to Lightning and Move to chain controls under it, and More > Leaves, More > Contracts and More > Lightning payment limit appear. BTC has no leaves: a tree on Sequentia holds no BTC (app/lib/src/data/dev_mode.dart).
  • A wallet that joined a leaf operator keeps its leaf wallet syncing in either mode, since its coins have dates to keep; user mode shows nothing of leaves but their value, in each asset's figure and in the headline.
  • Removing the wallet closes the leaf wallet and the Bitcoin ark wallet of its phrase and forgets what was read of them (LeafService.forget), so the next wallet, new or restored, shows and spends only its own.
  • User mode runs on the default node's operator by itself (LeafService.autoJoin, autoBoard, receiveCode in app/lib/src/data/leaf_service.dart), in the same words and ways as the web wallet:
    • A new or restored wallet that holds no leaf wallet joins the operator at <origin>/arca, only when the server shows the operator key pinned in app/lib/src/data/config.dart (Backend.arcaOperatorKey; a custom node pins none and joins nothing by itself). The join restores this phrase's leaves. While the operator cannot be reached the wallet works on the chain as before and tries again every two minutes. While the restore runs (LeafService.restoreOnce; one cut short, the app closed or the operator not answering, runs again at the next open, before the wallet opens), default mode says "Syncing… finding everything this wallet holds." rather than any figure (LeafService.findingWords): after two minutes that a long history takes a few minutes, after thirty that it takes far longer than it should; while the operator does not answer that its coins are not found yet and still its own, asking again every half minute, never showing the wallet empty. A payment asked meanwhile waits for the restore, or ends at once in those words. Once open, the coins the history gave up are checked half a second at a time (restore_history {budget_ms}) only while nobody asks the wallet for anything, so a receive code, a price or a payment waits for one slice at most.
    • Its words are the default-mode contract's (sequentia-web-wallet docs/DEFAULT_MODE.md), held in app/lib/src/data/default_words.dart and tested against the contract's forbidden words. Default mode shows no rail: a row's details show only Staked, what vests later, and a freeze, and nothing under the figure says part of it is on its way; the split by rail and the fee-rate fields are developer mode's.
    • What vests later. A vesting distribution (a token sale whose tokens vest, for one) pays a key of this wallet a coin nobody can move before its date. The wallet reads the leaf library's claims (under the OpenAMP key and the on-chain receive keys care scans) at most every two minutes and after each care, keeps the last reading so the balance shows it offline and while syncing, and counts what vests in the asset's figure and the headline, never in what can be spent: "100 ORNG vests on 3 November 2026" under the figure, one line for each date, and an asset held only this way still has its row. Every Max leaves it out, and Send, the Swap tab, Stake, a pool's membership, Mix and a site's sale refuse an amount that needs it, before anything is signed: "100 ORNG of this vests on 3 November 2026, and can be used from then. Nothing has moved." From that date the library's care takes it up by itself (at once, when a reading shows it open), and it is then part of the figure, arriving until final. Developer mode lists it with the rest of the claims on the Leaves screen and as "in vesting claims" beside the row (app/lib/src/data/vesting.dart, the web wallet's default-arca.js).
    • Receive is one card of three things, so a person can hold the screen up to be paid at once: the QR code, one line, "Scan or share to get paid in BTC or any asset.", and Copy. Everything else sits behind More options (Fewer options while open): where the payment name is changed, an amount to request, New code, Show full code, Confidential and Receive a restricted asset (the account id and a deposit address, in a card under the first). Leaving Receive closes More options and turns those off again. A payment coming in is said on the card under the line, "Payment arriving…", then "Received <amount> <TICKER>.", read from the figures Balance counts (receive_watch.dart, the web wallet's receive-watch.js), so a move of the wallet's own, coins of its own coming home or a trade says nothing. The QR code holds the wallet's payment name (below) while it has one, else its one receive code (app/lib/src/data/pay_code.dart, the web wallet's format), else, while a code is made ("Making your receive code…") or before the wallet holds coins with the operator or BTC on the ark, its address. The code is a BIP321 request, BITCOIN:<ADDRESS>?ark=<BITCOIN ARK ADDRESS>&sequentia=<SQR1…>. The address is the shared tb1 address, ark is where BTC arrives in seconds, and sequentia is the single-use receive request where an asset arrives in seconds, in its short form (SQR1…, about 230 characters where the library's own spelling runs to about 1,200; it carries every field of the library's request, reads included, and gives it back exactly). Neither extra part is required, so any Bitcoin wallet reads it as a plain request for the address. It is drawn in upper case as a QR code with alphanumeric segments at level M (payCodeQr), so it scans at a glance from another screen. The code shows at once from what the wallet last drew, syncing or not, gains a way to be paid in place when one opens, and is replaced when it is paid, when its request is within a day of lapsing, or on "New code", which also moves the code to the next address (the old one stays until the new one is ready). More options has one optional field, "Amount in BTC (optional)", with a menu beside it of what the amount is in: BTC, and each asset the operator receives over Lightning (the menu shows only when there is more than BTC; for an asset the field reads "Amount (optional)"). With an amount in BTC the code also carries amount= and a lightning= invoice from the Bitcoin ark for exactly that amount (BITCOIN:<ADDRESS>?amount=<BTC>&lightning=<INVOICE>&ark=…&sequentia=…), claimed while the wallet is open. With an amount in an asset it carries instead the operator's invoice in that asset (the leaf library's lightning_receive), which a wallet of another operator pays, and no amount=; once a payment is held for it the wallet syncs, which claims it. A new invoice comes with each new code and each new amount. No invoice is made for more than the operator takes in one payment over Lightning (below). Without an amount, a wallet with a payment name carries the name's LNURL-pay in lightning= (LUD-01 bech32, LNURL1…), which any Lightning wallet pays in an amount it chooses; readers give it apart (PayCode.lnurl), never as an invoice.
    • Under More options, one switch, Confidential: "Asks the payer to hide the amount, and the asset where it can, from everyone but you and them." What is hidden is the payer's wallet's doing: this one hides the amount, and says when the asset can be seen (Send, below). On, the code is the wallet's confidential address at the same index alone (tsqb1…), the card's line reads "Any Sequentia asset, any amount, paid to your confidential address.", and a second line says what stays public: that a payment was made; that a payment arriving in seconds is never confidential (the operator publishes each batch's leaves, asset and value), so this one arrives after the next block; and that BTC is never confidential, so receiving BTC needs the switch off. It is off each time Receive opens.
    • Your payment name (app/lib/src/data/lnaddr.dart, the web wallet's lnaddr.js; payment_name_service.dart): a name of the wallet's own at the node's domain (name@sequentiatestnet.com), which another wallet pays in an amount it chooses, a Lightning wallet included (it is a Lightning address, LNURL-pay). The name is held by a BIP340 key of the phrase (m/1017'/16'/0', name_key.dart), the same key the web wallet holds it with, so the phrase shows it again in either wallet. While the app runs it answers the service (the web wallet's tooling/lsp/lnaddr.mjs) with an invoice of the Bitcoin ark for the amount a Lightning payer chose, and keeps a stock of ten receive codes topped up there (name_stock.dart, the web wallet's name-stock.js): each a full code at an address of its own inside the twenty New code cycles through, so a restore finds every payment, each signed by the name's key over the name, the domain and the code. The service hands each out once to a Sequentia wallet paying the name, open or closed, then the most recent again, paid without its single-use part. Developer mode calls it Lightning address and keeps it on Receive, under the address. Only the default node has names. Every wallet holds one by default, made with nothing asked when it is opened in default mode (LnAddress.ensure): the name its key holds at the service, so a restored wallet gets its name back, else its word name. While the service does not answer the wallet asks again, after five seconds and then at a pause growing to a minute, and the name shows once it answers, without leaving the screen; while the service limits new names from the wallet's network, the card reads "Too many names were made from your network just now. Try again in a few minutes." and the wallet asks again by itself. A name kept from before shows only once the service has confirmed, since the wallet opened, that the key still holds it, and an open wallet stops showing a name the moment it is released or changed on another device. A name the person removed is never made again by itself, on this phone or any other holding the phrase: the service keeps the removal with the name's key, and a removal only this phone knows of is told to the service (decline). Default mode keeps the name's card in Settings (the More tab): the name, "Anyone can look this name up and pay you at it, in any amount they choose, and see the address each payment goes to. A Sequentia wallet can pay it while this wallet is closed; other wallets, while it is open.", Copy, Change name and Remove name. A released name answers no payer from then on and is never given to another wallet. Without a name the card offers Get a name, with Choose your own as a quiet link. Get a name gives the wallet its word name in one tap (word_name.dart, the web wallet's word-name.js): two words from a list, written together and shown with a capital for each word (AmberFalcon@sequentiatestnet.com), derived from the name's key, so a wallet restored from its phrase gets the same name back; a third word is added only when the two-word name is taken. The QR code, Copy and every lookup use the name in lower case, and lookups ignore case. The words are the EFF short wordlist less every BIP39 word, so no word of a recovery phrase is ever part of a public name (credit in NOTICE). A wallet holding a name of its own choosing sees Use a word name instead, a quiet link that swaps it for its word name.
    • With a name the service confirms and answers for, no amount and Confidential off, Receive's QR code is the name (nameQrText: the bare name@domain in lower case, about 30 characters, the spelling every wallet that pays names reads from a scan), and Copy copies it. More options then reads "Your payment name is AmberFalcon@sequentiatestnet.com. You can change or remove it in Settings." and offers Show full code: the full code in the QR code and written under it, with the line "For a wallet that can't look names up, or to pay without a connection. Each code is paid once; a new one shows when it is."; Show name goes back. An amount or Confidential gives the full code. While a code handed out in the last hour waits, the wallet reads for a payment every four seconds, and, while the app is in view, while any request it handed out waits (the name's stocked codes are handed out up to a day after they are made), every ten seconds; developer mode reads at every pass of its schedule while the app is in view. Out of view the passes keep the library's pace. A payment to a code another wallet of the phrase handed out (the phrase open in Ambra browser or the web wallet, or a store this phone held before) is taken in by that read; one the operator does not serve yet is kept and synced for once the leaf library's catch-up between the phrase's wallets is open by its own clock, a minute apart at least and ten minutes apart after ten attempts that ran no catch-up (the node or the operator not answering, or the catch-up answering with an error), until the wallet holds it, for at most six catch-ups or a day (app/lib/src/data/catch_up.dart, the web wallet's catchUpWait). Such a sync leaves out the watchtowers' step and makes the deposits right after it. The scheduled job carries the same wait while the app is closed (below). Developer mode shows the address, New address, the confidential address on request and the name under them.
    • Default mode keeps its money in coins, which every trade, swap and payment in the tree can spend: its care opens and folds no channel leaf (careArgs, channels: false), its receive codes and the payment name's stock codes name none (receiveArgs), and each live channel coin the wallet still holds is closed into a coin at the next round, by the app after its care (closeChannels, channelsToClose) and by the closed-app job after its own (background_sync, close_channels in ambra_core/src/leaves.rs), as the web wallet's default-mode contract says.
    • Payments that arrive at once, over channel leaves, in developer mode (app/lib/src/data/leaf_service.dart): where the operator makes channel leaves of an asset, the wallet's own care (careArgs, channels: true) opens one in each such asset from half of the wallet's leaves of it, reads it and folds the credit it was paid. The receive code names the wallet's payable channels (live, their round final) and is made again when they change, and the leaf library's send pays over a channel when the code it pays names one, with no round between. A payment the receiving channel cannot take is paid as any payment to a receive code. While it holds a channel the wallet reads its channels (channel_sync) every 300 ms while the app is in view and was used, opened, paid or showed a receive code within three minutes, else every five seconds, never while another leaf command runs or a person's payment is being reviewed (holdReads); a channel paid moves the asset's figure at once and Receive draws a new code. The wallet's own upkeep (a sync, then care, the claims and the bond's watch) reads the mailbox and the channels between each of its commands when a read is due (the mailbox every 4 s while a receive code handed out lately waits, else every 10 s), so a payment waits at most for the one command running, not for the whole pass. Developer mode's Leaves has a Channels card (each channel's sides and credit, with Read, Fold and Exit). The leaf library is arca at the revision ambra_core/Cargo.toml names, which carries the channel commands and the claim of a channel's credit after someone else closed it.
    • Send reads a receive code, typed, pasted or scanned (the scanner keeps the whole code), and picks its part without asking, instant first: an asset goes to the receive request when the wallet's leaves hold it (in seconds), and BTC goes to the ark address when the ark holds the amount, else to the code's invoice when the ark or the wallet's Lightning pays it. Anything else goes to the address, and the review says so first ("This can't arrive in seconds from what you hold now, so it goes to the address. …"). An invoice the ark would pay above the most the operator takes in one payment over Lightning goes to the code's address too, said first as "This can’t arrive in seconds right now, so it goes to the address." That limit is the operator's (max_payment in its info, per asset and for its Bitcoin node, each way; app/lib/src/data/ln_max_payment.dart); the wallet holds no figure of its own, and only when the operator publishes none holds one payment to 1,500 USD. A bare receive request is paid the same way. Every payment that leaves is in History at once, pending until its block when it waits for one, and BTC arriving at the wallet's latest addresses shows there as soon as the Bitcoin network has it. A payment name (name@domain, also read as lightning:name@domain or ₿name@domain, typed or scanned) is paid as what it stands for: a name at the node's own domain at a receive code its wallet left signed with the service, any asset, as any code is, once the signature checks out against the key published beside the name and the key this wallet first paid the name at (kept per wallet); otherwise "This name gave a receive code its wallet did not sign, so nothing was sent. Ask the recipient for their full code." or "This name now belongs to another wallet than the one you paid before, so nothing was sent. Ask the recipient for their full code."; a name at another domain in BTC only, at the invoice that service makes, which must be for BTC and for exactly the amount. An LNURL-pay (LNURL1… in either case, with lightning: before it or not, LUD-17's lnurlp://…, or a bitcoin: code whose one way to pay is its LNURL; lnurlOfSendInput) is paid the same way: the URL a payment name stands for (https://domain/.well-known/lnurlp/name) as that name, any other in BTC only, over Lightning, at the invoice it makes for exactly the amount. An invoice that carries a description hash must commit to the metadata the service served (LUD-06); one with a plain description, as the Sequentia name services make, is paid as it is. The service's answers are read over https only: a redirect from https to anything else stops the payment. Anything that is not a code, a name or an LNURL (an address, an invoice, an account id) takes the path it always took. An address send the chain cannot cover is paid out of the leaves (the library's offboard_quote, then offboard on the quote shown): "Send ?", "It arrives within minutes. Keep this screen open meanwhile." (the most the whole way to the other wallet takes: the operator's round interval, its block and certificate, the most the operator says it takes to unlock the payment in a block, ten minutes when it says none, and two minutes of reads, rounded up to five minutes, addressArrivalMinutes; fifteen on the testnet while its operator publishes no unlock time), and the fee when there is one. A move out of the Ark to the wallet's own address (for a stake, a pool, a mix) waits on no other wallet, and says so in its own minutes (moveOutMinutes). The wallet signs its part of the operator's settlement as it is made, and one closed before then makes nothing, so after Send it says "Sending . Keep this screen open until it is sent." until the library's offboards reads it made (unlocking or paid), and only then "Sent . It arrives within minutes." Each such payment is written down with the library's id for it and followed to its end while the app runs (app/lib/src/data/address_payments.dart): one that ended without being made says "Your payment of to was not made: nothing left your wallet. Send it again." once, as it ends or on a card above Balance's list with OK, and History reads it "Not sent", "Nothing left your wallet.", its amount struck through; one taken back before it arrived reads "did not arrive". A payment the leaves cannot pay yet because coins of it are still arriving (the change of a payment just made) says "Part of this is still arriving: it can be sent within minutes." A payment the chain's own coins cover gets default mode's review ("Send ?", to whom, the fee, "It arrives after the next block, in about a minute.", Cancel and Send); developer mode's sheet names the network, the fee asset and the estimate. The same amount to the same address asked again while the first is on its way is that first payment: the wallet says it is already on its way and sends nothing more. A quote the library refuses reads "This amount can't be sent to an address right now. Send it to a receive code, or pay an invoice." A confidential address (tsqb1…) is paid on the chain so that its amount is hidden (confidential_pay.dart, the web wallet's confidential-pay.js): beside the payment, a second blinded output to the wallet's own confidential address takes what the inputs hold beyond the payment and its fee, so the chain shows only the two together. When the chain holds too little, a round amount is moved out of the leaves to the wallet's own address first (all of the asset held there, or the next power of ten above the need, whichever is smaller; on_chain_need.dart, as for a stake), under the button: "Moving out of the Ark so it can be sent confidentially. They are ready in a few minutes. Keep this screen open." The review says "Anyone reading the chain can see that this payment is , but not how much." (this wallet spends only coins of the asset paid), or, when too little is held beside the payment, that its amount and asset can still be worked out. A move already under way is waited for, never asked twice; when none can be made, one sentence says why and nothing moves.
    • Coins that arrive on the chain, of every asset the operator serves, are boarded by the wallet itself (amount = what the chain holds less the board's fee, paid in the same asset, on the fee quoted), never while something a person asked for runs or in the minute after it, since the leaf wallet spends the same addresses' coins, nor while coins moved out for a person's payment, stake or mix wait to be used (up to an hour). What is not final yet is in the figure; developer mode shows it as " arriving" under the figure. The coins a board spends come off the chain's part of the figure only until a scan begun after the board reads the chain (onchainLessBoards), so a coin that reached the address meanwhile stays in the figure. Before boarding, the leaf wallet is handed keys (its address command) until it has handed out as many as the main wallet, so it reads every key the balance can show a coin at: it finds its on-chain coins by a gap past the last key holding an unspent coin, the main wallet by a gap past the last key with any history. A trade of more than the balance shows says "That is more than your ." at once. One whose asset the balance covers but no coin pays now asks for that board at once and, held on the chain or in the tree by the wallet's own round, is the ticket above, settled first; one held by an order the person placed says "Your is held by an order you placed, and can be traded once it is filled or cancelled. Nothing has moved."; BTC not payable yet says "Your BTC is not ready to trade yet: it is once the next Bitcoin blocks settle it. Nothing has moved." (at anchor depth 0, "Your BTC is on its way: it is ready to trade in a minute or two. Nothing has moved.").
    • An asset held in the wallet's own Lightning channel (a wallet made before its assets lived with the operator) moves into the tree by itself (tickAssets, app/lib/src/data/lightning_to_ark.dart): the leaf wallet asks to receive it over Lightning (lightning_receive: an invoice of the operator's node in that asset, under a hash whose preimage only the wallet holds), and the channel pays it, all it can spend less the route's fee, when that reaches the operator's smallest leaf, and at most what the operator takes in one payment over Lightning (max_payment.receive; the rest moves on a later pass, since the operator refuses a larger one). The operator holds the payment until the wallet's leaf is in the asset's next round; the leaf wallet's sync then claims the leaf with the preimage, which settles the payment. One move per asset at a time, never while something a person asked for runs, and a refused one waits fifteen minutes. Until the leaf is the wallet's the amount stays in the figure, and Balance says "Moving so it can be sent in seconds." under it; a payment that fails comes back to the channel. An asset the operator serves without a Lightning node stays in its channel, spendable as before. A supervised asset (one held only as a landing leaf) is never in a channel, so it has nothing to move.
    • History in user mode lists no board: moving the wallet's own coins into the tree is not a payment. The wallet keeps each board's transaction as it boards, and reads the ones it made before from the operator (boards).
  • User mode keeps BTC on the Bitcoin ark (app/lib/src/data/ark_btc_service.dart, ambra_core/src/ark_btc.rs): Second's Bark client, from arca's arca-wallet crate, opened from the same recovery phrase against the ark server the default node serves (Backend.bitcoinArk, gRPC on the node's own address; testnet4 here; a custom node has none). BTC stays native bitcoin, which the holder can always take on the chain.
    • What the ark holds is kept within a band in USD (app/lib/src/data/ark_limits.dart, the web wallet's ark-limits.js): it rests at 1,500 USD, and once it holds 3,000 USD everything above 1,500 moves to the wallet's own address in one move (an ark payment to the address, looked at every two minutes, never while a person is busy). A payment of 1,500 USD or more goes to the address, never into an ark: Send pays a receive code's address for it, saying first "A payment of 1,500 USD or more goes to the address.", and a receive code for such an amount carries neither the ark's address nor an invoice (Receive says the same sentence under the amount). No figure applies until the price feed values BTC; until then nothing moves in. A debug build takes other figures with --dart-define=AMBRA_ARK_LIMITS='{"btc":{"board":15,"hold":30,"direct":15}}'; a release build always holds the defaults.
    • Confirmed BTC at the shared address moves in by itself, only while the ark holds less than a quarter of the resting level, and then back up to it in one move: the kit pays it, less the fee, to a new board's funding address in one transaction, and the ark wallet boards that transaction (board_funding_address, board_psbt) and puts it on the network. The rest stays at the address, in the one BTC figure and sendable as ever. Every limit is the ark server's own, read from its info (max_board, min_board in ark_balance): a board carries at most the server's largest coin, the rest staying at the address for later boards, and none is made below the server's least board (with 1,000 sat over it for the fees) or before the server has answered. One board at a time, never while something a person asked for runs, or in the minute after; a board whose funding transaction the network has not known for ten minutes (its broadcast failed) holds nothing and no longer holds the next one back. Bark's own log goes to logcat, tagged bark.
    • BTC held in the wallet's own Lightning channel (a wallet made before BTC lived on the ark) moves in by itself too (app/lib/src/data/lightning_to_ark.dart): the channel pays an invoice of the wallet's own ark for all it can spend less the route's fee, from 5,000 sat and at most the ark server's largest coin, at most every fifteen minutes and never while something a person asked for runs. The payment leaves the wallet's own hosted node over whatever channel it has, to the ark server's Lightning node. Until it is paid the BTC stays spendable in the channel; meanwhile Balance says "Moving BTC so it can be sent in seconds." under BTC's figure.
    • A channel these moves emptied (BTC or an asset) is closed cooperatively to the wallet's own address when that is cheap and safe: locked in, nothing on its way from it, too little left to move, and its close estimated at under a quarter of what comes back. What it held stays in the figure until the wallet's scan counts the close's payment (at most two hours), and is then boarded like any other coin. Otherwise the channel stays, and developer mode says why under its Lightning part ("Channel stays open: …"). The rules are the web wallet's and Ambra browser's (lightning-to-ark.js).
    • Renewals are made in groups that each fit in the server's largest coin; a coin due that is larger than the server takes now (made before it lowered its limit) is offboarded with the server to the phrase's own address instead (offboarded in ark_sync's answer), and boarded again from there.
    • Before it schedules the server's renewals, each pass asks the library's Bitcoin ark watchtower plan (tower_plan), so a coin a tower holds is never also renewed; the tower plan's coins are left out (schedule_refreshes_except). Deposits with the site's tower (/btc-watchtower of the ark's origin) are sent only when TOWER_DEPOSITS in ambra_core/src/ark_btc.rs is on; withdrawals always, so a deposit never outlives its coin.
    • Send pays out of the ark, chosen without asking: an ark address in seconds, a BTC invoice (lntb…) over Lightning, a Bitcoin address on the chain after a Bitcoin block. An address the ark cannot cover, or one it refuses, is paid as before. A code or an invoice beyond what the ark holds reads "You can send up to BTC this way now." An invoice is paid only once its payee takes the payment: while the payee holds it (a hold invoice), Send says "On its way: waiting for the other side to accept it." and History shows it "On its way"; then "Sent BTC ( s)." when it is taken, or "Not paid: the payment came back, and the BTC is in your balance again." when it fails back, and History marks it "Not paid".
    • BTC another wallet pays into the ark (to its address, or an invoice of the receive code) is listed in History as received, read from the ark's own record of its movements (ark_history); the wallet's own moves into the ark (a board, its channel's BTC, a trade's leg) are not.
    • The same phrase on another device, or restored here, holds the same ark BTC: Bark recovers from the server's recovery mailbox when it creates its store, and on every open and every five minutes after the wallet catches up (catch_up_from_server) with what the phrase's other wallets boarded, received or spent since. A board whose device was lost before the board was registered is found on the chain from the phrase alone and taken in by the same catch-up.
    • Each pass of the wallet's sync schedules with the ark's server, for every coin that has none, a renewal the server runs by itself shortly before the coin's expiry (schedule_refreshes), so a phone left closed keeps its BTC renewed on time; the renewed coin is taken in at the next open, and the maintenance that renews coins near their expiry leaves a coin with a renewal scheduled to the server.
    • When the ark's server refuses the wallet or stops answering and a coin worth its exit is within a day of expiry, the wallet takes it to the chain alone: the same rule as the web wallet, bark-wasm's exit_auto (ambra_core ark_exit), in both modes. Bark broadcasts the coin's pre-signed exit, pays each step's fee from the wallet's own Bitcoin address (the phrase's BIP84 coins, given to Bark as its onchain wallet), and claims the coin to that address. BTC's row says what happened and what it cost; nothing is moved into the ark meanwhile. Developer mode adds Exit…, which prices each coin and refuses one not worth its exit.
    • BTC's one figure counts the ark; developer mode says what is on its way in as " BTC arriving". Developer mode opens the ark wallet too and counts it (its split reads "… on the Bitcoin ark"), but moves nothing into it or out of it by itself.
  • Leaves are coins held as leaves of an operator's covenant tree on Sequentia: paid and received off the chain with the operator's co-signature, and always takeable on-chain by the holder. The wallet is the operator's own wallet library (bark::arca from arca) linked into the Rust core (ambra_core/src/leaves.rs): every script, record, check, fee, schedule and refusal is the library's, and the app shows each refusal in the library's words.
  • More > Leaves (app/lib/src/screens/leaves_screen.dart): join an operator (pins its key and the node's chain, and restores this phrase's leaves), the leaf balance per asset and state, receive (a request shown as text and QR, copied or shared), send to a request, settle now (the refresh fee shown before anything is signed), every coin with its dates, the exit drill, board from on-chain, and what the wallet refused. While the operator cannot be reached (a sync's unreachable), Leaves says so under Operator, and every leaf still goes home by its exit drill, one at a time.
  • When the operator stops answering, Balance shows one card above the list, in either mode: "The service that holds your coins for instant payments is not answering. Your coins are still yours: wait for it to come back, or take them home to your own address now." and Take my coins home (app/lib/src/data/home_coins.dart, the web wallet's default-arca.js home functions). The button quotes every coin the wallet still holds (exit_quote; a channel leaf by channel_exit) and reviews it: one line per asset with the network fees the holder pays, about how many hours until it arrives, and what cannot go now. Take them home broadcasts each exit only on the fees shown; a coin whose shared steps another coin already put on the chain is quoted again and goes only for no more than was shown. Until they arrive the card reads " on its way to your own address: it arrives in about hours, once this wallet is open." Nothing of it asks the operator.
  • The Swap screen's leaf rail (developer mode, an operator joined, two Sequentia assets; app/lib/src/data/leaf_rail.dart, app/lib/src/screens/leaf_rail_panel.dart): "Pay from" and "Receive to" offer Leaf beside On-chain and Lightning, and a leg on Leaf is settled by the leaf panel in place of the screen's own review. Market, Leaf to Leaf: a take from leaves of the best on-chain order the operator's round can take (a transparent covenant order on the relay), its fill, price, fee and the operator's forfeit window shown first; beside it, accepting another wallet's in-tree swap offer, read first (what is got, given and paid, and the date by which the coins got must be taken on the chain) and accepted only on those terms. Limit, Leaf to Leaf: an in-tree swap offered to another wallet of the same operator (the offer holds the coins and signs nothing), completed with its acceptance in one reassignment the operator co-signs. BTC is never a leaf: a pair with BTC has no Leaf choice. An order placed on the chain from leaves is made in the web wallet or the browser wallet. User mode shows no Leaf choice.
  • More > Contracts (developer mode, app/lib/src/screens/contracts_screen.dart): a spend of a contract the kit carries (sequentia/faucet-drip, pignus/vault, pignus/offer, pignus/vault-threshold, pignus/offer-threshold, sequentia/capped-sale, sequentia/subscription-escrow, sequentia/one-key, sequentia/one-key-exit), pasted in the shape a site hands the browser extension's signContractSpend ({templateHash, instance, request | drip, fund?}). The kit's contract engine (SWK lwk_contracts, in ambra_core/src/contracts.rs) checks it against this wallet: with fund the wallet adds its own explicit coins and the change; every wallet input is checked against the wallet's own record of its coins, the contract coin and every foreign coin against the chain's record, read from the wallet's own explorer; every program runs against the final transaction. The screen shows the engine's summary (the template, the path, the parameters by role, every input by what it is, the wallet's balance change in every asset, where the coins go, and the five checks) and signs only the digest of what it showed, with a contract key the path names or, on a path that takes no signature, none; the wallet's funding keys sign only its own coins.
  • The leaf wallet's store is one SQLite file per recovery phrase in the app's support directory, opened by one process at a time. It keeps no phrase.
  • While the app runs, the leaf wallet syncs on the library's schedule, with a foreground service keeping the process alive (LeafSyncService.kt). While it is closed, a scheduled job (LeafSyncWorker.kt, WorkManager) runs the Dart entry point leafSyncJob in an engine with no UI: it syncs, runs care when it is due (in default mode followed by the close of each live channel coin, close_channels, before the coins it hands over are read), raises a notification for each payment received, and wakes again at the schedule's next_sync_at, at most a day ahead while a coin is off the chain or a receive request is open, and no later than the next sync of the wait for a payment to another wallet's code (jobOutcome), which it shares with the app: its sync's refusals join the wait, the coins its catch-up restores or the wallet holds leave it (each with a notification), and a pass that fails counts as an attempt and wakes again at the wait's cadence instead of an hour later (jobFailed). The app is the one writer of the kept wait: the job writes each pass as an entry of its own (the wait it read and what it made of it), which the app merges in by leaf id before every change, writes into the wait, and only then removes, so a pass the job writes meanwhile is never lost. While the app's upkeep runs on the wallet (it holds the wallet in this process and stamps every pass, kAppAliveKey, the stamp younger than twice its longest pass), the app carries the wait: the job only hands over the coins its own sync refused and the library's next catch-up time, and looks again once the stamp would go stale; an app whose engine ended without a word (Back on the home screen of older Android, with the sync service keeping the process alive) stops stamping, and the job carries the wait again. The job keeps running whatever the mode, so coins already held keep their refresh. When the leaf wallet opens and whenever the app comes back to the foreground it syncs once, whatever the schedule says (the schedule wakes a planned coin only at its plan's sync_by).
  • What the wallet does by itself, with no prompt, in either mode: at the first sync after the app starts and then at most every ten minutes (the app and the scheduled job keep one clock), it runs the library's care. care takes up every claim of a distribution named for an address the wallet handed out (it scans 20 past the wallet's next receive index, since the leaf wallet counts its keys apart from the main wallet); a claim taken up then counts in the asset's figure like any coin. It cancels each offline-refresh plan whose coin moved, and signs a plan for a leaf of a round once the plan's first step could run within ten days (the library's reach), two expiries ahead, so a wallet closed across an expiry keeps the coin, and the leaf is free to trade and pay out of round until then; a wallet closed earlier and kept away past the expiry has the coin repaid by the operator, less the late-refresh fee. Each step's fee is at most 0.2% of the coin and is taken from the coin in its own asset, never another; a coin the operator will not plan in its asset stays unplanned, and the sync refreshes it while the app is open. A coin of no round (a board, or a coin received or taken up out of round) is free to pay with, and is refreshed into a round once that refresh could run within ten days (it costs a fee, so it waits), then planned at a later sync.
  • A planned coin carries refund halves the wallet signed, so no wallet pays it out of round. A payment, a trade or an order that the unplanned coins cannot cover is made through the next round, by itself: the library refuses it naming the planned coins whose release covers it (kind planned), the app gives those up in the next round for leaves of its own that no plan names (plan_release), syncs every 15 seconds until that round is final and the new leaves are held, and asks again (at most three releases, and three hours of waiting, after which it says that nothing was paid and the payment can be asked again). The person waits one round and sees nothing else. The same path waits, and asks again, for whatever else only a round holds back: coins the library names to settle first (settle_first, kind settle_first: a payment received still arriving, coins at the operator's depth limit), put through the next round and read every five seconds until they can be spent, the wait said as "Goes through within about minutes", counted down to the time the library gives (settleWords; before it has said from the operator's round, blocks and anchor depth, settleMinutes, 6 on the testnet), "Taking longer than usual: this goes ahead by itself, or nothing is sent" two minutes past it, and after three hours "This payment could not go through yet: nothing was sent, and your money stays in your wallet."; channels whose side would cover it (in_channel), closed into the next round; coins too many payments deep (depth_limit), refreshed; the wallet's own refresh of the asset already in a round; and a coin the operator does not call live yet (not_live), asked again for two minutes. A payment that waits this way can be written down (LeafService.payPending, app/lib/src/data/pending_sends.dart): an app closed while it waits makes it at the next open, with what was reviewed; one closed while the library was being asked is never asked again and Balance says once that it may have gone; one made after reopening that does not go is said once as not sent. Every leaf command a screen starts goes through this one path (LeafService.pay, payThroughRelease in app/lib/src/data/leaf_service.dart), the user-mode Swap tab's included. A release costs the refresh fee the asset's schedule asks then (none in the coin's free window). Developer mode's Leaves screen shows the last care in a "Kept by itself" card (claims taken up, plans cancelled and made, coins refreshed into a round) with the distributions, the claims and the plans; each open plan has Cancel and Release (plan_release of the plan's current leaf, which ends the plan once that round is final), each planned leaf is marked under "Coins and their dates", and a "Paying through the next round" card stands while a payment waits for its round. User mode shows none of it.
  • Supervised assets: an asset whose issuer can freeze holdings by a rule of the chain is held, received and paid like any other, and counted in its one figure. The library holds a coin of such an asset only as a landing-1 leaf, whose way out of the tree pays one key of the wallet's own, its landing key (the first on-chain key of the phrase, landing_address in the leaf wallet's info). A board, a refresh, a payment received and the change of a payment sent all land there; the app computes none of it. When the issuer freezes that key, or pauses the asset, the frozen part shows under the asset's figure on the balance, in either mode, as one sentence ("… is frozen by its issuer: it can't be sent until the issuer lifts the freeze"); it is never hidden. A payment of it is refused, in user mode in plain words ("This asset is frozen by its issuer for this wallet: nothing was sent."). Developer mode's Leaves screen shows each leaf's landing and whether it is frozen, with the library's note, and the landed coins on the chain that are frozen; such a leaf leaves the tree only into the landing key (the exit drill, or sync before its exit date), where the coin stays frozen on the chain until the issuer lifts the freeze, and is then spent like any coin. The operator serves no take, no resting order and no Lightning payment in a supervised asset, so user mode's Swap tab offers such an asset only through an in-tree swap with a live maker (servedPairs, in app/lib/src/data/leaf_service.dart).
  • A payment the operator declines: the operator's signer refuses what it asks, and would refuse it again however often it were asked (the server's code declined), so the payment is refused for good. The library puts the coins back at once and sends nothing again; user mode reads "This payment was declined; nothing was sent.", or, when the operator declines because the wallet needs updating, "This wallet is out of date for this: update it, then try again. Nothing was taken.", and developer mode shows the operator's own words, which name the code. An operator that cannot be reached is no refusal: the payment stands, and the next sync sends it again.
  • The operator's bond: the operator posts an equivocation bond, which two different messages its key signs under one coin's salt burn whole. At care's pace, in either mode, while the app runs, the leaf wallet reads the bond (bond; once it has seen it bonded, it requires it from then on) and runs watch_bond, which checks the wallet's own evidence against the chain and the mempool and sends the slash itself should the operator key have signed twice. The library's gate does the rest: a receive or a swap is refused while the bond is missing or in notice, or when what the wallet would hold out of round is worth more than it. Nothing is said while the bond stands; a refusal reads, in user mode, "Not accepted: the security deposit that backs these instant payments is missing or being withdrawn, so this wallet takes no payment that rests on it. Nothing was signed." Developer mode's Leaves screen shows the bond (its state, asset and value, coin, when it can be withdrawn, whether this wallet requires it, whether it covers what the wallet holds out of round) and the last watch, with Watch now.
  • Issuer-operated assets: the operator may serve an asset issuer-operated, where the issuer mints each round's float through the asset's mint limiter and every batch's sweep can only burn. The library checks each new leaf against that profile by itself. Developer mode's Leaves screen shows each leaf's batch profile under "Coins and their dates" (issuer-operated, or open) and, for each asset the operator serves issuer-operated, Supply: the operator's report of what it minted, burned and holds under burn-only sweeps, each mint and burn read again from the wallet's own node. It checks the transactions the report lists; it does not prove the list complete. User mode shows none of it.

Connect to a site

  • A site such as SeqDEX trades through this wallet, and every trade it asks for is shown on the phone first (More > Sites > Connect to a site, app/lib/src/screens/sites_screen.dart). The site shows a nostrconnect:// code as a QR code, or as a link on the same phone; Ambra scans it, takes it pasted, or opens it from the link. The pairing shows the site's name and the address it says it has (any page can put any address in a code, so the owner checks it against the page in front of them). Approving it is the site's connection; More > Sites lists the sites connected, each with Forget.
  • The wire is the extension's doc/PAIRING.md: Nostr Connect framing over the relays the code names, each message a kind-24133 event, NIP-44 v2 encrypted and signed by its sender, with a key pair Ambra makes for that pairing alone (ambra_core/src/nostr.rs, tested against the official NIP-44 vectors). A request more than five minutes from the phone's clock, or with an id already answered, is dropped (app/lib/src/data/site_link.dart).
  • The site's methods are the provider protocol's (the extension's doc/PROVIDER.md): getCapabilities, getWalletMode, connect, getAccounts (the shared tb1 address), getBalances (assets on the chain, btc on testnet4, and apart from them leaves and btc_ark, what is held as leaves and in the Bitcoin ark, and spendable, what a trade can pay from now), placeOrder, getOrders and cancelOrder (app/lib/src/data/site_service.dart).
  • A market order is one trade of the Swap tab's own engine; a limit order is that trade when the book meets its price, and otherwise rests on the book at its price, placed from the wallet's leaves and listed by the wallet once it rests, to be taken back once its time has run out. The approval sheet names what is given, what is got, the fees and "Asked by" the site; declining it, or leaving it five minutes, answers the site "the user rejected the request" with nothing moved. The same rules as the web wallet's site-orders.js (app/lib/src/data/site_orders.dart).
  • A site reaches the wallet while Ambra is open: requests are read while the app runs, and one sent while it is closed goes unanswered.

Assets, staking, faucet, node

  • Issue a new asset, reissue (mint more of) an asset you hold the reissuance token for, and burn (app/lib/src/screens/assets_screen.dart). The issued amount, the asset and its reissuance token go to the wallet's own addresses as explicit outputs, as a send does (ambra_core/src/issuance.rs).
  • Stake the Sequence token (tSEQ) for block production: 40,000 tSEQ minimum, bonded to the staking key m/2/0 under a time-based lock of about 15 days (app/lib/src/screens/stake_screen.dart). Staking is the one thing the Sequence token is for; it is not privileged anywhere else in the wallet.
  • Every stake of the wallet's staking key is listed under "Your stakes", whichever Sequentia wallet made it: the app's own time lock and the height lock of 43,200 blocks the web wallet and the extension bond with are both looked up on the explorer, along with unbonding outputs not yet returned. Unbonding takes two steps. Once a stake's lock has passed, Unbond moves it into an unbonding output of the same key (the fee, at most 1% of the stake, comes out of it); once the unbonding period has passed (2,016 Bitcoin blocks after the Bitcoin block the unbond's block anchors to), Return to wallet pays it to a fresh address of the wallet. Where each stake stands is read from the chain every time, so a reorg moves it back (ambra_core/src/staking.rs).
  • In default mode the Stake screen speaks to a first-time staker (app/lib/src/data/stake_words.dart): what staking is for, how much, where it makes blocks, what it costs and how to get it back, then 1. Stake and 2. Choose a pool. A phone makes no blocks itself, so a stake makes them through a pool the person picks; each declared pool shows whether it is producing (the pool board's verdicts), its share of all stake, its members and what it pays, and none is picked for them. The two steps of taking a stake back read Take back and Return to wallet. Tokens held in the Ark are moved out to the wallet's address first when a stake or a first pool membership needs them (app/lib/src/data/on_chain_need.dart). Developer mode shows the staking key, lock heights and the pools' keys and full payout policies.
  • Faucet screen requesting BTC, tSEQ, USDX, EURX, GOLD, SILVR, or OILX from the public testnet faucet, once per wallet, with what the wallet has already received shown on its buttons.
  • Report a problem (More → Help): what happened, an optional Emissio account code to be credited, and the address only when ticked. The report carries the app's version, its mode and its recent uncaught errors, scrubbed of addresses, keys and invoices, shows exactly what will be sent, refuses a description carrying words of the phrase, and goes to Emissio's intake on the public testnet site whatever node the wallet uses (app/lib/src/data/problem_report.dart; the words are the web wallet's, docs/DEFAULT_MODE.md there).
  • Custom node: point the wallet at your own Sequentia node/backend (with optional HTTP auth) instead of the public testnet default (app/lib/src/screens/node_screen.dart).

Consensus rules the UX must respect

Bitcoin anchoring is supreme: every Sequentia block references a Bitcoin block header, and Sequentia reorganizes whenever Bitcoin reorganizes away an anchor, in real time, overriding checkpoints and immediate finality. A transaction's real safety depth is the Bitcoin confirmation depth of its block's anchor, not its Sequentia block depth. Ambra never presents Sequentia finality as stronger than a Bitcoin reorg: swap review sheets say "anchor-bound to Bitcoin (reverts only if Bitcoin reverts)", the cross-chain swap gates its preimage reveal on an anchor check, and only the pure Lightning rail (where nothing settles on-chain) is ever labeled final.

Backend endpoints

The wallet defaults to the public Sequentia testnet node and derives every endpoint from one origin (app/lib/src/data/config.dart), so switching to a custom node is one change:

Endpoint Purpose
<origin>/api Sequentia Esplora REST (sync, broadcast)
<origin>/testnet4/api Bitcoin testnet4 Esplora REST
<origin>/dex SeqDEX daemon (REST via grpc-gateway)
<origin>/feerates Per-asset fee exchange rates
<origin>/prices Reference-currency price server
<origin>/registry/index.minimal.json Asset registry labels
<origin>/faucet Testnet faucet
<origin>/openamp OpenAMP restricted-asset API
<origin>/lsp Hosted SeqLN LSP HTTP API
https://sequentiatestnet.com/emissio/api/problem-reports Report a problem (always the public site)

The default origin is https://sequentiatestnet.com. The Lightning rail's websocket endpoints and pinned host keys are separate constants in the same file and are enabled only while the default origin is in use.

Architecture

Flutter UI (app/)  --flutter_rust_bridge-->  ambra_core (Rust)  -->  SWK (lwk_wollet,
   Dart                                          |                    `sequentia` feature)
                                                 +-->  seqln-signer (Lightning device signer)
  • app/ is the Flutter application: screens, theme, and thin Dart service classes for the HTTP sidecars (faucet, prices, registry, SeqDEX, OpenAMP, LSP). See app/README.md.
  • ambra_core/ is the shared Rust crate exposed to Dart via flutter_rust_bridge (pinned to 2.12.0). It consumes SWK's lwk_wollet with the sequentia cargo feature ON, which is where the whole Sequentia send-flow lives: any-asset fees, RBF/CPFP, transparent-by-default addresses, staking, the Bitcoin testnet4 wallet (lwk_wollet::btc), and the cross-chain HTLC glue (lwk_wollet::btc::xchain). SWK's own UniFFI bindings (lwk_bindings) build with that feature OFF and cannot reach these code paths, which is why Ambra has a dedicated core crate. It links the operator's wallet library (arca-wallet from arca, the arca-core feature) for leaves, with the core's own HTTP client as its transport. It also embeds seqln-signer (from the seqln repo): the phone-side Lightning signing kernel + Noise_XK transport that keeps the LSP rail non-custodial.
  • docs/SPEC.md is the product/design spec (custody contract, navigation, design tokens, core API surface).

Key implementation detail: the core API is intentionally stateless per call. Dart passes the mnemonic into each operation; the core derives what it needs, signs, and returns. Scanned wallet state persists to the app's data dir (set once at startup) so cold starts resume instead of re-scanning.

Building from source

Verified toolchain: Linux host, Rust (stable), Flutter with Dart SDK >= 3.12, Android SDK with NDK 29.0.14206865 (pinned in app/android/app/build.gradle.kts), cargo-ndk, protoc (apt install protobuf-compiler; the arca library compiles a gRPC protocol), and flutter_rust_bridge_codegen 2.12.0 (only needed if you change the core API).

ambra_core consumes SWK and seqln by relative path: both checkouts must sit as siblings of the ambra repo (see [patch.crates-io] in ambra_core/Cargo.toml). The arca library comes from GitHub at the revision ambra_core/Cargo.toml pins, with its kit crates pointed at the same SWK checkout.

# 1. Sibling checkouts
git clone https://github.com/ConcatenaLabs/ambra.git
git clone -b sequentia https://github.com/ConcatenaLabs/SWK.git
git clone -b sequentia-stable https://github.com/ConcatenaLabs/seqln.git

# 2. Rust core (host build; also produces the cdylib the Flutter host tests load)
cd ambra/ambra_core
cargo build

# 3. Cross-compile the core for Android
rustup target add aarch64-linux-android
cargo install cargo-ndk
cargo ndk -t arm64-v8a -o ../app/android/app/src/main/jniLibs build --release
# (for the x86_64 emulator: rustup target add x86_64-linux-android; -t x86_64)

# 4. Build the app
cd ../app
flutter pub get
flutter build apk --release        # or: flutter run (device attached)

app/android/app/src/main/jniLibs/ is gitignored; the .so is rebuilt on demand by step 3. Release builds are signed with the Ambra release key when app/android/key.properties (gitignored) is present; without it Gradle silently falls back to the debug key, producing an APK that will not install over the published one (app/android/app/build.gradle.kts).

If you change the ambra_core::api surface, regenerate the bridge from app/ (config in app/flutter_rust_bridge.yaml):

flutter_rust_bridge_codegen generate

Tests

Rust core (from ambra_core/):

# Offline tests: architecture smoke test, Lightning signer conformance
# (a 99-frame corpus byte-compared against libhsmd's replies, less the device's two
# deliberate departures: covenant capabilities, watchtower-friendly penalties) and its payment limit
cargo test --test smoke --test signer_conformance --test payment_limit --test seqob_relay_offer

# Network tests (hit the live public testnet; run explicitly)
cargo test --test sync -- --nocapture

# Staking against a local sequentiad on a private elementsregtest chain: pools
# (join, move and leave confirmed in blocks, wrong signatures refused by a block) and
# stakes under both locks found, unbonded and returned (early steps refused by a block)
SEQUENTIAD_EXEC=/path/to/sequentiad cargo test --test stake_records -- --nocapture

# Contract spends against a local sequentiad: a faucet drip and a Pignus vault
# repaid with the wallet's own coins, each summary checked and each spend confirmed,
# and the refusals (a digest not shown, a wallet coin said to be in another asset,
# a foreign coin the chain does not back, a template the wallet does not carry)
SEQUENTIAD_EXEC=/path/to/sequentiad cargo test --test contracts -- --nocapture

# Leaves against a whole operator: a payment received while the app is closed,
# found by the scheduled job's pass, and two wallets swapping two assets in the
# tree through the core (offer, read, acceptance on the terms read, completion). Needs arca's long-running operator harness
# (bark-cli/tests/arca_operator_for_browsers.rs in the arca repo) at its control
# address; without the variable the test says so and passes without running.
AMBRA_LEAVES_HARNESS=http://127.0.0.1:18640 cargo test --test leaves -- --nocapture

# A vesting claim named under the staking key: listed with its date before it vests, taken
# up by care after. Needs a second harness started with ARCA_OPERATOR_NO_SWEEP=2592000
# (batches without a sweep, each collected a month after its round).
AMBRA_LEAVES_NO_SWEEP_HARNESS=http://127.0.0.1:18641 cargo test --test leaves a_vesting_claim -- --nocapture

A bare cargo test runs the network tests too, and fails stake_records and contracts unless SEQUENTIAD_EXEC is set, so prefer the explicit forms.

Flutter (from app/):

flutter test test/lsp_client_test.dart        # pure-Dart, mocked HTTP, runs anywhere
FAUCET_DIR=/path/to/sequentia-faucet flutter test test/faucet_once_test.dart   # against a real faucet, no coins
flutter test                                  # all tests; see the caveat below

Caveat: test/widget_test.dart and test/seqln_device_key_test.dart drive the real Rust core through flutter_rust_bridge on the host. They resolve the cdylib from $AMBRA_CORE_LIB, defaulting to ../ambra_core/target/debug/libambra_core.so (relative to app/), so run cargo build in ambra_core/ first or set the variable.

On a device or emulator, integration_test/default_ops_drive_test.dart drives default mode's everyday operations against the live testnet: Receive's one card and the wallet's payment name, money in from the faucet (assets as instant payments, BTC on the Bitcoin ark), Send to a receive code through the Send screen, a trade each way between USDX and EURX and each way with BTC through the Swap tab's engine, and BTC out to an address. It logs each operation's stated wait and the time it took, and saves a screenshot of each screen through test_driver/integration_test.dart, since an emulator's own screen capture reads the app back as black. It prints the new wallet's recovery phrase once, so the run's coins can be recovered; keep that line out of anything shared. Three optional steps take a second wallet beside the drive (its header names the --dart-defines): Send pays it, Send pays a bare LNURL of a payment name, and the drive waits for a payment to its own name made at a code another store of its phrase left as the name's stock, saying how soon it showed.

AMBRA_SHOTS=/tmp/shots flutter drive --driver=test_driver/integration_test.dart \
  --target=integration_test/default_ops_drive_test.dart -d <device> --dart-define=AMBRA_OPS_DRIVE=true

Sequentia ecosystem

Repo One-liner
Sequentia The Sequentia node (sequentiad, a fork of Elements 23.3.3): consensus, anchoring, proof of stake, open fee market, plus the canonical protocol documentation in doc/sequentia/.
SWK Sequentia Wallet Kit: a fork of Blockstream LWK, providing the Rust wallet library, CLI, and WASM bindings for building Sequentia (and Bitcoin testnet4) wallets.
sequentia-web-wallet Proof-of-concept browser wallet built on SWK, live at https://sequentiatestnet.com/wallet.
seqdex SeqDEX: non-custodial atomic-swap DEX with an on-chain covenant order book (SeqOB) served over a relay, same-chain swaps, and cross-chain BTC↔asset swaps made safe by Bitcoin anchoring.
seqln SeqLN: a Core Lightning fork that runs on Sequentia and Bitcoin from the same binary, with asset channels, any-asset payments, and pure-Lightning swaps.
openamp OpenAMP: open-source restricted-asset issuance/transfer-approval service (an AMP2 equivalent) with opt-in confidentiality; zero consensus changes.
fulmen Fulmen: desktop (Electron) wallet for SeqLN with a bundled Lightning node.
sequentia-extension Ambra for Chromium: the same dual-chain wallet as a browser extension, plus the window.sequentia API websites use to reach it.

Contributing

Development happens on main; open PRs against it. The Sequentia-specific logic worth knowing before you start: ambra_core/src/api/mod.rs (the whole FFI surface), app/lib/src/data/config.dart (endpoints + asset labels), and app/lib/src/screens/shell.dart (the tab shell and balance model). Never commit secrets: no real seeds, keys, or credentials belong in this public repo (test fixtures use only the well-known all-zero BIP39 vector).

License

MIT, in LICENSE and declared in ambra_core/Cargo.toml.

About

Ambra: non-custodial dual-chain (Bitcoin testnet4 + Sequentia) mobile wallet. Flutter UI over a Rust core (ambra_core) built on SWK: balances, send/receive, any-asset fees, RBF/CPFP, staking, asset issuance, and SeqDEX swaps.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages