Shielded Pool RPCs

The BTX shielded pool uses the SMILE v2 proof system. In the v0.33 release line, shielded RPC support is limited to strict shielded-to-transparent exits, wallet integrity checks, and recovery for existing shielded state. Transaction families for deposits, z-to-z sends, re-shielding, and bridge shield ingress may still be decoded for compatibility, but those flows are not production-supported.

Current status: Shielded pool credits and new shielded appends are disabled at height 125000; public-flow and direct-send shielding are disabled at height 128000; the unshield velocity quota ends at height 135000.

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

Shielded Transaction Lifecycle

The production lifecycle is now exit/recovery-only:

1. Recover: Wallets scan the shielded tree, verify key material, and recover existing notes that belong to the wallet.
2. Exit: Existing shielded notes can be consumed and settled to transparent payout addresses.
3. Disabled flows: Transparent-to-shielded deposits, z-to-z sends, re-shielding, and bridge shield ingress are not production-supported after the sunset heights above.

Bridge Settlement Flow

Bridge RPCs still expose plan/build/decode surfaces, but current production support is limited to exits and recovery/refund handling:

1. Exit: bridge_planout, bridge_buildunshieldtx, and bridge_submitunshieldtx cover shielded-to-transparent payout plans.
2. Refund: bridge_buildrefund creates a refund-path PSBT once refund_lock_height is reached.
3. Disabled ingress: bridge_planin, bridge_planbatchin, bridge_buildshieldtx, and bridge_submitshieldtx remain compatibility surfaces and must not be presented as accepted production shield ingress.

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 (Disabled Deposit / Shield Surfaces)

The bridge-in RPCs below are documented for compatibility, decoding, and controlled testing. They do not describe an active production deposit path: shielded pool credits and new appends are disabled at height 125000, and public-flow/direct-send shielding is disabled at height 128000.

bridge_planin

Build a deterministic bridge-in plan for historical or testing workflows. Production bridge shield ingress is disabled; do not use this RPC as a current transparent-to-shielded deposit path.

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	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) -- Historical 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. The returned plan is not a production ingress authorization after the disable heights.

bridge_planbatchin

Build a deterministic bridge-in plan that aggregates many off-chain credits into one historical shielded settlement note. Production shielded credit creation is disabled at height 125000.

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 the fields below. Shielded credit and shielded payout leaves are compatibility surfaces, not active production shield ingress:

• 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. The returned plan does not reopen production shield ingress.

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 for the disabled bridge-in normal path. On production networks after the sunset heights, treat this as historical/testing compatibility rather than an accepted shield ingress transaction.

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 for compatibility or testing environments. This is not a current production shield ingress flow after the disable heights.

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 (disabled)	bridge_planin compatibility	bridge_buildshieldtx disabled	bridge_submitshieldtx disabled
Batch deposit (disabled)	bridge_planbatchin compatibility	bridge_buildshieldtx disabled	bridge_submitshieldtx disabled
Withdrawal	bridge_planout	bridge_buildunshieldtx	bridge_submitunshieldtx
Refund (timeout)	(from original plan)	bridge_buildrefund	(sign + sendrawtransaction)