How to build, test, and run every part of this repo locally. Commands were verified on Linux with Go 1.26 on 2026-07-08; binary names, flags and subcommands were re-checked against the code on 2026-08-22. For what the parts are and how they fit together, read the README and daemon/README.md first (ARCHITECTURE.md is a 2026-07-08 snapshot).
- A recent Go toolchain (Go 1.26 verified; the daemon's release build script
uses
CGO_ENABLED=1). - For anything on-chain: a built Sequentia node, i.e.
sequentiadandsequentia-clifrom https://github.com/ConcatenaLabs/Sequentia (about an hour to build; see that repo's docs). - Optional:
buffor proto codegen, Docker for the inherited upstream compose files, a SeqLN node for the Lightning rails (submarine, pure-LN, sub-asset).
The repo holds seven Go modules; the two that matter are daemon/ and
wallet/ (the others are the top-level proto/gen module and small
self-contained modules under daemon/pkg and daemon/cmd/migration). Build
the two service modules:
cd daemon && go build ./...
cd ../wallet && go build ./...Binaries you will actually run:
cd daemon
go build -o ../bin/seqobd ./cmd/seqobd # order-book relay
go build -o ../bin/seqob-maker ./cmd/seqob-maker # order-book maker
go build -o ../bin/seqob-cli ./cmd/seqob-cli # order-book taker CLI
go build -o ../bin/seqob-octl ./cmd/seqob-octl # ocean account helper
go build -o ../bin/seqob-settler ./cmd/seqob-settler # passive covenant settler
go build -o ../bin/seqob-covenant ./cmd/seqob-covenant # covenant builder CLI
go build -o ../bin/tdexd ./cmd/tdexd # RFQ trade daemon
go build -o ../bin/tdex ./cmd/tdex # RFQ operator CLI
cd ../wallet
go build -o ../bin/seqdex-wallet ./cmd/oceand # wallet daemon(Upstream make build in daemon/ builds tdexd via scripts/build with
CGO and -ldflags="-s -w"; the plain go build above is fine for
development.)
Unit tests need no node and pass on a clean checkout:
cd daemon && go test ./internal/seqob/... ./pkg/xchain/... ./pkg/covenant/...
cd ../wallet && go test ./pkg/...Notes:
daemon/pkg/xchaincontains real two-chain integration tests (TestCrossChainSwap,TestReverseCrossChainSwap, anchor negative tests). They automatically start and stop a two-chain regtest viapkg/xchain/testdata/start-regtest.shwhen they can find the node binaries, and skip (not fail) otherwise. Point them at your node clone withSEQUENTIA_REPO=/path/to/Sequentia(the script expects$SEQUENTIA_REPO/build-linux/src/sequentiadandsequentia-cli, falling back to the legacyelementsd/elements-clinames), or at already-running nodes with the test-only env knobsSEQDEX_XCHAIN_PARENT_RPC/SEQDEX_XCHAIN_SEQ_RPC.- The consensus-level covenant proofs (
test/regtest/feature_seqob_*.py) run against a real node via the node repo's functional test framework; see ../test/regtest/README.md. - The submarine/Lightning integration tests additionally want
SEQLN_SOCK1/SEQLN_SOCK2(two SeqLNlightning-rpcsockets) and skip without them. - The test suites under
wallet/internal/core/...are upstream Ocean's, run on Sequentia's regtest parameters with mocks; they are not a regression signal for the Sequentia paths. daemon/test/e2e(make integrationtest) is the inherited upstream TDEX docker loop against a Liquid regtest; it has not been adapted to Sequentia.
Everything cross-chain (and the most faithful same-chain testing) runs against a pair of nodes: a parent Elements-mode node standing in for Bitcoin (the anchor source) and an anchored Sequentia node. The committed harness brings both up:
export SEQUENTIA_REPO=$HOME/Sequentia # your node clone (build-linux/src/*)
daemon/pkg/xchain/testdata/start-regtest.sh up # parent RPC :18000, seq RPC :18001
daemon/pkg/xchain/testdata/start-regtest.sh stop
daemon/pkg/xchain/testdata/start-regtest.sh clean # stop + wipe /tmp/seqdex-xchain-regtestIt starts both nodes with -signblockscript=51 -con_any_asset_fees=1 -blindedaddresses=0 ..., wires the Sequentia node's anchoring to the parent
(-con_bitcoin_anchor=1 -validateanchor=1 -mainchainrpc*), and creates a
wallet w on each. Cross-chain flows against a real bitcoind (testnet4 or
Bitcoin regtest) are also supported by every binary via -btc-chain.
Plain sequentiad -chain=regtest runs in Bitcoin serialization mode, which the
go-elements transaction parsers the wallet relies on cannot decode. Real
Sequentia runs in Elements mode. For a faithful standalone node (without the
harness) use:
sequentiad -datadir=<dir> -server -daemon \
-con_elementsmode=1 -signblockscript=51 -validatepegin=0 \
-bech32_hrp=bcrt -blech32_hrp=bcrt -pubkeyprefix=111 -scriptprefix=196 -blindedprefix=4 \
-rpcport=19996 -rpcuser=s -rpcpassword=s \
-fallbackfee=0.0001 -acceptnonstdtxn=1 -txindex=1 -blockfilterindex=1
# create a descriptor wallet, mine ~110 blocks, then read getsidechaininfo.pegged_assetThese parameters match wallet/pkg/seqnet.SequentiaRegtest (bech32/blech32
bcrt, base58 111/196, confidential prefix 4). Note the harness's nodes run
with anchoring on, which is what exercises Sequentia's anchored PoS header
path; the wallet's scanner deliberately reads block and header structure via
JSON-RPC verbosity (not raw-header deserialization) because go-elements cannot
parse anchored/PoS headers.
OCEAN_NETWORK=sequentia-regtest \
OCEAN_NATIVE_ASSET=<getsidechaininfo.pegged_asset hex> \
OCEAN_NODE_RPC_ADDR=http://s:s@127.0.0.1:19996 \
OCEAN_BLOCKCHAIN_SCANNER_TYPE=elements \
OCEAN_DB_TYPE=badger OCEAN_NO_TLS=true \
OCEAN_DATADIR=<datadir> \
./bin/seqdex-walletOCEAN_NODE_RPC_ADDRmust be a full URL with credentials.OCEAN_NATIVE_ASSETis required: Sequentia's policy asset is genesis-derived, read it from the node, never hardcode it.- Leave
OCEAN_ESPLORA_URLunset for node-RPC-only operation; the elements scanner polls the node tip every ~2s. - Networks:
sequentia|sequentia-testnet(default) |sequentia-regtest. - Default gRPC port:
18000.
Verified flow: GenSeed -> CreateWallet -> Unlock -> CreateAccount ->
DeriveAddresses -> fund the derived bcrt1... address from the node -> the
wallet syncs the UTXO/balance. Drive it with the ocean CLI
(wallet/cmd/ocean) or seqob-octl.
-
Relay (holds nothing, needs nothing but a port):
./bin/seqobd -listen :9955
-
Prepare a maker account on the running wallet daemon and fund the printed address from your node:
./bin/seqob-octl -ocean 127.0.0.1:18000 -account mm -action create ./bin/seqob-octl -ocean 127.0.0.1:18000 -account mm -action balance
-
Maker: posts a signed offer and serves lifts over the courier.
./bin/seqob-maker \ -relay http://127.0.0.1:9955 -ocean 127.0.0.1:18000 -account mm \ -node-rpc http://s:s@127.0.0.1:19996 \ -base <GOLD hex> -quote <USDX hex> -side sell \ -base-amount 100 -quote-amount 4500 \ -min-anchor-depth 0 -confidential=true -expiry 1h
-
Taker: inspect the book, then lift.
./bin/seqob-cli taker-key -file taker.key # once: makes the keys, prints the address to fund ./bin/seqob-cli book -relay http://127.0.0.1:9955 -base <GOLD hex> -quote <USDX hex> ./bin/seqob-cli lift -relay http://127.0.0.1:9955 \ -base <GOLD hex> -quote <USDX hex> \ -offer-id <id> -maker-pubkey <hex> -amount 100 \ -esplora <esplora url> -taker-key-file taker.key
taker-keywrites the taker's signing and blinding keys to the file, mode 600, and prints the address that pays them (unblinded, and its blinded form); fund it with what the lift pays. The keys can also be given as-taker-priv/-taker-blinding(orSEQOB_TAKER_PRIV/SEQOB_TAKER_BLINDING), the flags putting them on the command line. Without-esploraand a key the lift runs in demo mode against an in-memory stub wallet (it exercises the courier handshake but settles nothing on-chain); with them the taker funds and broadcasts a real swap.seqob-crossertakes the same-taker-key-filefor its same-chain legs.
seqob-cli post can also place an offer without running a maker process, but
settling a lift requires the maker online (interactive co-signing; the relay
evicts a disconnected maker's offers).
Maker (sells an asset for real BTC, or the reverse; both need a Sequentia node and a BTC-side node):
./bin/seqob-maker -mode cross \
-relay http://127.0.0.1:9955 \
-base <asset hex> -side sell \
-base-amount 100 -quote-amount 15000 \
-btc-rpc http://user:pass@127.0.0.1:48332 -btc-wallet w -btc-chain testnet4 \
-xseq-rpc http://s:s@127.0.0.1:19996 -xseq-wallet w \
-xstate-dir xmaker-sessions
# in -mode cross the pair is always base=asset, quote=the "BTC" sentinel;
# -base-amount is asset atoms, -quote-amount is BTC sats; no partial fillsTaker:
# buy the asset with BTC (forward; you hold the secret)
./bin/seqob-cli xlift -relay ... -asset <hex> -offer-id ... -maker-pubkey ... \
-btc-rpc ... -btc-wallet ... -btc-chain testnet4 -seq-rpc ... -seq-wallet ... -state-file lift.json
# sell the asset for BTC (reverse; the maker holds the secret)
./bin/seqob-cli xsell ...same flags...
# refunds after an abort, once the CLTV passes
./bin/seqob-cli xrefund -state-file lift.json -btc-rpc ... -btc-wallet ... -wait
./bin/seqob-cli xrefund-seq -state-file sell.json -seq-rpc ... -seq-wallet ... -waitA node URL carries its RPC password, and anything on a command line is
readable by every user on the machine (ps, /proc/<pid>/cmdline). So every
seqob-cli flag that holds one also reads its environment when it is not given:
-seq-rpc from SEQOB_SEQ_RPC, -btc-rpc from SEQOB_BTC_RPC, -xseq-rpc
from SEQOB_XSEQ_RPC, -taker-priv and -taker-blinding from
SEQOB_TAKER_PRIV and SEQOB_TAKER_BLINDING; seqob-maker reads
SEQOB_NODE_RPC, SEQOB_BTC_RPC, SEQOB_XSEQ_RPC and SEQOB_MAKER_PRIV
the same way. On a shared machine, set them from a mode-600 environment file
(a systemd EnvironmentFile=) and leave the flags out. A usage text never
prints a value read from the environment.
After a maker crash, ./bin/seqob-maker -resume -xstate-dir xmaker-sessions ...
finishes every non-terminal session (claim or refund) and exits.
Requires a SeqLN/CLN node on the BTC side for each party (https://github.com/ConcatenaLabs/seqln):
# maker: base = the asset, quote = the BTC sentinel
./bin/seqob-maker -mode lightning -ln-socket /path/to/lightning-rpc \
-sub-anchor-depth 3 ...
# taker: sell the asset, receive BTC over LN
./bin/seqob-cli xsublift -ln-socket ... -relay ... -asset <hex> ...
# taker: buy the asset, pay BTC over LN (anchor-gate before paying)
./bin/seqob-cli xsubbuy -ln-socket ... -min-anchor-depth 2 ...Pure-LN: both legs over Lightning, so each party needs a SeqLN node on Sequentia (the asset leg) and one on Bitcoin (the BTC leg); nothing touches a chain and there is no anchor wait.
# maker: base = the asset, quote = the BTC sentinel (or -quote-asset <hex> for asset-for-asset)
./bin/seqob-maker -mode pureln -relay ... -base <asset hex> -side sell \
-base-amount 100 -quote-amount 15000 \
-asset-ln-socket /path/to/seq/lightning-rpc -ln-socket /path/to/btc/lightning-rpc
# taker
./bin/seqob-cli xpln -relay ... -side buy -asset <hex> -offer-id ... -maker-pubkey ... \
-asset-ln-socket ... -ln-socket ...Sub-asset (the submarine's mirror: the asset over Lightning, BTC as an on-chain HTLC):
# maker sells the asset over LN against on-chain BTC
./bin/seqob-maker -mode subasset -relay ... -base <asset hex> \
-base-amount 100 -quote-amount 15000 \
-asset-ln-socket ... -btc-rpc ... -btc-wallet ... -btc-chain testnet4
# taker pays BTC on-chain, receives the asset over LN
./bin/seqob-cli xsubas -relay ... -asset <hex> -offer-id ... -maker-pubkey ... \
-btc-rpc ... -btc-wallet ... -btc-chain testnet4 -asset-ln-socket ... -state-file subas.json
# the reverse direction is -mode subasset-sell / seqob-cli xsubas-sell (+ xsubas-claim-btc)A covenant order is funded on-chain, so the maker needs nothing running after
placement. The end-to-end proofs are the regtest scripts in test/regtest/
(feature_seqob_covenant_fill.py, feature_seqob_joint_covenant.py,
feature_seqob_matcher_covenant.py, feature_seqob_watcher.py,
feature_seqob_bridge.py, feature_seqob_multi_fill.py,
feature_seqob_simplicity_order.py, feature_seqob_simplicity_book.py,
feature_seqob_book_remainder.py); they drive the
production Go builders through the CLIs:
-expiry is the order's REFUND lock, expiry_locktime: a block height below
500,000,000, or a median time past (unix seconds) from it, which the same leaf
takes unchanged; the relay, the settler and the web wallet read both. Prefer a
median time: a height lock opens later than planned when an anchor rollback
disconnects blocks, and an Arca operator refuses orders whose refund opens
within six hours, counting a height at 60 seconds a block. -prog is the
maker's credit program and must be a plain key, never an Arca leaf or board
script: one maker-and-operator signature pair over such a script spends two
equal credits paid to it at once.
# -num, -den and -minlot below 2^63 (the FILL leaf reads a larger term as negative)
./bin/seqob-covenant derive -a <A> -b <B> -num N -den D -minlot M -prog P -expiry E -makerx X
./bin/seqob-covenant fill ...derive flags... -locked L -filled F -k K
./bin/seqob-covenant filltx < spec.json # several orders, order k at input k
./bin/seqob-covenant check ...derive flags... -tx HEX -k K -locked L
# a Simplicity order (template seqdex/order): -maker is the payout scriptPubKey.
# Post it as an offer whose settlement is simplicity_covenant (offer.proto), with
# template_hash from simderive; seqob-cli covfill fills it like any covenant offer.
./bin/seqob-covenant simderive -a <A> -b <B> -num N -den D -minlot M -maker SPK -expiry E -refund X
./bin/seqob-covenant simwitness ...simderive flags... -path fill|whole|refund [-sig SIG]
./bin/seqob-covenant simcheck ...simderive flags... -tx HEX -k K -locked L [-partial]
# a pool (seqdex/pool) and a clearing round of round orders (seqdex/round-order);
# each reads a JSON spec on stdin, documented in cmd/seqob-covenant/pool_round.go
./bin/seqob-covenant poolderive < pool.json
./bin/seqob-covenant round < round.json # price, fills, layout, the clearer's signature
echo '<cross json>' | ./bin/seqob-settler plan
./bin/seqobd -listen :9955 -node-rpc 127.0.0.1:19996 -node-rpc-user <user> -node-rpc-pass <pass>
# ^ the relay runs the covenant chain-watcher when given -node-rpc# wallet daemon up first (see above), then:
SEQDEX_WALLET_ADDR=127.0.0.1:18000 \
SEQDEX_NODE_RPC=http://s:s@127.0.0.1:19996 \
SEQDEX_NO_MACAROONS=true SEQDEX_NO_OPERATOR_TLS=true \
./bin/tdexdThen initialize and drive it with the helpers (regtest) or the tdex CLI:
seqdex-initwallet (create), seqdex-unlock (unlock; this starts the Trade
interface on :9945), seqdex-market (create/fund/open a market),
seqdex-taker (perform a same-chain swap). tdexd serves same-chain trades
only; for cross-chain runs use the order book ("Cross-chain over the order
book" above).
The standalone contract copy under proto/ regenerates with buf:
cd proto && buf dep update && buf generate # -> proto/gen/goThe daemon and wallet vendor their own generated stubs under
daemon/api-spec/protobuf/gen and wallet/api-spec/protobuf/gen
(make proto in each directory; requires buf).
- Branch from
main, open PRs againstmain. - Go code is gofmt-formatted (
make lintindaemon/runs golangci-lint). - Module import paths are
github.com/aejkcs50/seqdex/...(a historical GitHub username; the modules are self-contained so this only affects import strings, not fetching). - Never commit keys, seeds, RPC credentials, or wallet files; the repo is public.