Shielded Pool RPCs

The BTX shielded pool uses the SMILE v2 proof system. Shielded transactions are organized into families: v2_send (private transfers), v2_ingress_batch (deposits), v2_egress_batch (withdrawals), v2_rebalance (reserve domain netting), and v2_settlement_anchor. Legacy families (legacy_shield, legacy_unshield, legacy_direct) are also decoded for backwards compatibility.

Prerequisite: Shielded keys require an encrypted wallet. Call encryptwallet before using any shielded features, and walletpassphrase to unlock before signing.

Shielded Transaction Lifecycle

The lifecycle of a shielded deposit-transfer-withdraw cycle:

1. Deposit (shield): Transparent BTX is locked in a bridge P2MR output. The bridge operator settles it into the shielded pool, creating a shielded note.
2. Transfer: Shielded notes can be privately transferred between shielded addresses using v2_send family transactions.
3. Withdraw (unshield): A shielded note is consumed and settled to a transparent payout address via a bridge-out plan.

Bridge Settlement Flow

The bridge uses a plan-build-submit pattern with deterministic P2MR script trees:

1. Plan: bridge_planin or bridge_planbatchin creates a deterministic bridge plan with operator/refund keys, amount, and settlement parameters.
2. Fund: The transparent side funds the P2MR output (external to these RPCs).
3. Build: bridge_buildshieldtx creates a PSBT that settles the funded output into the shielded pool.
4. Submit: bridge_submitshieldtx signs, finalizes, and broadcasts in one step (or use the build + external-sign + finalize path).
5. Refund: If settlement fails, bridge_buildrefund creates a refund-path PSBT once refund_lock_height is reached.

z_verifywalletintegrity

Verify that all shielded and PQ key material is present, derivable, and properly persisted. Run this before backupwallet or backupwalletbundlearchive to confirm the backup will contain complete key material.

btx-cli z_verifywalletintegrity

Key response fields:

Field	Description
integrity_ok	True if all key material is present and consistent
shielded_keys_total	Total shielded key sets
spending_keys_loaded	Spending keys available for signing
viewing_keys_loaded	Viewing keys available for decrypting notes
spending_keys_missing	Spending keys not yet derived (wallet may be locked)
master_seed_available	True if master seed is accessible for key derivation
shielded_notes_total	Total tracked shielded notes
shielded_notes_unspent	Unspent shielded notes
tree_size	Shielded Merkle tree commitment count
scan_height	Last scanned block height
scan_incomplete	True if scan could not complete (e.g. pruned blocks)
pq_descriptors	Number of PQ descriptors in wallet
pq_descriptors_with_seed	PQ descriptors with seed stored
pq_seed_capable_descriptors	PQ descriptors with pqhd() that can carry a local seed
pq_seed_capable_with_seed	Seed-capable PQ descriptors that have their local seed
pq_public_only_descriptors	PQ descriptors with public key material only (e.g. imported multisig cosigner descriptors)
warnings	Array of issues found (missing seeds, incomplete scans)
notes	Informational notes that do not affect integrity

Bridge-In RPCs (Deposit / Shield)

bridge_planin

Build a deterministic bridge-in plan for funding a P2MR bridge output and settling it into the shielded pool.

Parameter	Type	Required	Description
operator_key	string (hex)	Yes	Operator PQ pubkey (ML-DSA-44 or SLH-DSA-128s)
refund_key	string (hex)	Yes	Refund PQ pubkey (ML-DSA-44 or SLH-DSA-128s)
amount	amount	Yes	Shielded bridge amount
options	object	No	Bridge planning options (see below)

Options object fields:

• bridge_id (hex, required) -- Bridge instance id
• operation_id (hex, required) -- Bridge operation id
• refund_lock_height (number, required) -- Absolute refund lock height
• recipient (string, optional) -- Shielded recipient address; if omitted, a new local address is generated
• shielded_anchor (hex, optional) -- Shielded anchor override
• memo / memo_hex (optional) -- UTF-8 or hex memo bytes
• batch_commitment_hex (hex, optional) -- Canonical bridge batch commitment; cannot combine with memo
• operator_view_pubkeys (array, optional) -- ML-KEM public keys for bridge audit payload grants

btx-cli bridge_planin "" "" 5 \
  '{"bridge_id":"01","operation_id":"02","refund_lock_height":200,"recipient":"btxs1..."}'

Returns the bridge plan object with recipient, recipient_generated, shielded_anchor, and plan artifacts.

bridge_planbatchin

Build a deterministic bridge-in plan that aggregates many off-chain credits into one shielded settlement note.

Parameter	Type	Required	Description
operator_key	string (hex)	Yes	Operator PQ pubkey
refund_key	string (hex)	Yes	Refund PQ pubkey
leaves	array	Yes	Canonical batch leaves or signed authorizations
options	object	No	Bridge planning options (same as bridge_planin plus external_anchor)

Each leaf object contains:

• kind -- shield_credit, transparent_payout, or shielded_payout
• wallet_id (hex) -- Source wallet/account identifier hash
• destination_id (hex) -- Destination identifier hash
• amount -- Leaf amount
• authorization_hash (hex) -- Hash of the off-chain user authorization
• authorization_hex (hex, optional) -- Signed bridge batch authorization (overrides other leaf fields)

The external_anchor option (for bridging from external DA layers) contains domain_id, source_epoch, and optional data_root / verification_root.

btx-cli bridge_planbatchin "" "" \
  '[{"authorization_hex":""}]' \
  '{"bridge_id":"01","operation_id":"02","refund_lock_height":200}'

Returns the batch plan with batch_commitment, batch_commitment_hex, batch_commitment_hash, leaves, and authorizations.

bridge_planout

Build a deterministic bridge-out plan for settling a bridge output to a transparent payout template.

Parameter	Type	Required	Description
operator_key	string (hex)	Yes	Operator PQ pubkey
refund_key	string (hex)	Yes	Refund PQ pubkey
payout_address	string	Yes	Transparent payout address
amount	amount	Yes	Payout amount

btx-cli bridge_planout "" "" "btx1z..." 5

Bridge Build and Submit RPCs

bridge_buildshieldtx

Build a PSBT that settles a funded bridge-in output into the shielded pool using the plan's normal path. Use this when an external signer or manual PSBT review is required.

Parameter	Type	Required	Description
plan_hex	string (hex)	Yes	Hex-encoded bridge plan
txid	string (hex)	Yes	Funding transaction id
vout	number	Yes	Funding output index
amount	amount	Yes	Funding output amount

btx-cli bridge_buildshieldtx "<plan_hex>" "<txid>" 0 5

Returns the PSBT plus selected_path ("normal"), bridge_root, ctv_hash, and relay fee analysis.

bridge_submitshieldtx

Sign, finalize, and broadcast a funded bridge-in settlement in one step.

Parameter	Type	Required	Description
plan_hex	string (hex)	Yes	Hex-encoded bridge plan
txid	string (hex)	Yes	Funding transaction id
vout	number	Yes	Funding output index
amount	amount	Yes	Funding output amount

btx-cli bridge_submitshieldtx "<plan_hex>" "<txid>" 0 5

Returns txid, locktime, selected_path, bridge_root, and ctv_hash.

bridge_buildunshieldtx

Build a PSBT that settles a funded bridge-out output to the plan's transparent payout template.

Parameter	Type	Required	Description
plan_hex	string (hex)	Yes	Hex-encoded bridge plan (must be a bridge-out unshield plan)
txid	string (hex)	Yes	Funding transaction id
vout	number	Yes	Funding output index
amount	amount	Yes	Funding output amount

btx-cli bridge_buildunshieldtx "<plan_hex>" "<txid>" 0 5

Returns the PSBT plus selected_path, bridge_root, ctv_hash, and relay fee analysis.

bridge_submitunshieldtx

Sign, finalize, and broadcast a funded bridge-out settlement in one step.

Parameter	Type	Required	Description
plan_hex	string (hex)	Yes	Hex-encoded bridge plan
txid	string (hex)	Yes	Funding transaction id
vout	number	Yes	Funding output index
amount	amount	Yes	Funding output amount

btx-cli bridge_submitunshieldtx "<plan_hex>" "<txid>" 0 5

Returns txid, locktime, selected_path, bridge_root, and ctv_hash.

Bridge Refund

bridge_buildrefund

Build a refund-path PSBT for a bridge plan once the refund lock height is eligible. The refund path allows recovering funds if the bridge operator fails to settle.

Parameter	Type	Required	Description
plan_hex	string (hex)	Yes	Hex-encoded bridge plan
txid	string (hex)	Yes	Funding transaction id
vout	number	Yes	Funding output index
amount	amount	Yes	Funding output amount
destination	string	Yes	Refund destination address
fee	amount	Yes	Refund fee
enforce_timeout	boolean	No (default true)	Reject if chain has not reached refund_lock_height

btx-cli bridge_buildrefund "<plan_hex>" "<txid>" 0 5 "btx1z..." 0.0001

Returns the refund PSBT plus selected_path ("refund"), bridge_root, ctv_hash, refund_lock_height, current_height, and relay fee analysis.

Bridge Decode RPCs

bridge_decodeattestation

Decode canonical bridge attestation bytes and return the message body plus the CSFS-domain hash.

Parameter	Type	Required	Description
attestation_hex	string (hex)	Yes	Hex-encoded canonical attestation bytes

btx-cli bridge_decodeattestation "<attestation_hex>"

Returns message (decoded attestation body), bytes (hex), hash (attestation hash), and matches_active_genesis (boolean indicating whether the attestation references the current chain's genesis block).

Bridge Settlement Quick Reference

Operation	Plan RPC	Build RPC	Submit RPC
Single deposit	bridge_planin	bridge_buildshieldtx	bridge_submitshieldtx
Batch deposit	bridge_planbatchin	bridge_buildshieldtx	bridge_submitshieldtx
Withdrawal	bridge_planout	bridge_buildunshieldtx	bridge_submitunshieldtx
Refund (timeout)	(from original plan)	bridge_buildrefund	(sign + sendrawtransaction)