The BitVMX Client provides the core functionality for interacting with the BitVMX protocol and the Bitcoin blockchain.
This library is currently under development and may not be fully stable. It is not production-ready, has not been audited, and future updates may introduce breaking changes without preserving backward compatibility.
Clone the repository and initialize the submodules:
git clone git@github.com:FairgateLabs/rust-bitvmx-client.gitcargo buildRelease build with debug symbols:
cargo build --profile release-with-debugNormal vX.Y.Z tags build the client image and must match the version in
Cargo.toml. To force an image build with a different version, push a
force/client/vX.Y.Z tag (prerelease suffixes are supported). It publishes the
image with tag vX.Y.Z and does not trigger a types release.
The mirror workflow exports the wire contract to
rust-bitvmx-client-types.
Normal v* client release tags publish types only when the exported files change.
To force a types release independently of the client version, push a
force/types/vX.Y.Z tag (prerelease suffixes such as -rc.1 are supported):
git tag force/types/v0.8.8-rc.1
git push origin refs/tags/force/types/v0.8.8-rc.1This publishes v0.8.8-rc.1 on the types repo's release/v0.8.8-rc.1 branch,
with crate version 0.8.8-rc.1, even if the exported files are unchanged.
The source tag remains force/types/v0.8.8-rc.1 in generated headers and mirror.toml
so the types repo can verify against the original source. The client image build
does not run for force/types/* tags, and the client's Cargo.toml version stays as is.
Mirrored git dependencies keep the client's existing tags; types-only releases
require those dependencies to be tag-pinned in the client's manifest.
Manual runs also accept a force/types/vX.Y.Z tag input to force publication.
Select the matching source tag with --ref and set publish=true to publish,
or publish=false to regenerate and test. Existing output tags are never replaced.
To use encrypted configuration files read the setting README.md
NOTE: BitVMX-CPU release binary should be built beforehand
cd BitVMX-CPU
cargo build --releaseRun the client tests:
RUST_BACKTRACE=1 cargo test --release -- --ignored test_allIf you are running a bitcoin node, you should stop it before running the integration test (as it handles its own node).
RUST_BACKTRACE=1 cargo test --release -- --ignored test_fullThis project is licensed under the MIT License - see LICENSE file for details.
This repository is a component of the BitVMX Ecosystem, an open platform for disputable computation secured by Bitcoin. You can find the index of all BitVMX open-source components at FairgateLabs/BitVMX.
Documentation for the BitVMX client API message system and request/response patterns. The API uses JSON RPC over the BitVMX broker.
This table shows the mapping between request messages and their expected response messages based on the correlation ID system used in the BitVMX client, organized by functional categories.
| Request Message | Expected Response Message | Notes |
|---|---|---|
Ping(uuid) |
Pong(uuid) |
Basic connectivity test |
GetCommInfo(uuid) |
CommInfo(uuid, coms_address) |
Get communication information |
| Request Message | Expected Response Message | Notes |
|---|---|---|
Setup(uuid, program_type, participants, leader_idx, setup_timeout_secs) |
SetupCompleted(uuid) or ApiError(uuid, error) |
Setup the program with an optional overall timeout in seconds (None defaults to one hour); returns ApiError for duplicate identifiers and non-fatal setup failures |
SetVar(uuid, key, value) |
Variable(uuid, key, value) or ApiError(uuid, error) |
Set a variable in the program; returns ApiError for an invalid key |
GetVar(uuid, key) |
Variable(uuid, key, value), NotFound(uuid, key) or ApiError(uuid, error) |
Get variable value; returns ApiError for an invalid key |
SetWitness(uuid, address, witness) |
Witness(uuid, key, witness) or ApiError(uuid, error) |
Set witness data; returns ApiError for an invalid key |
GetWitness(uuid, address) |
Witness(uuid, key, witness), NotFound(uuid, key) or ApiError(uuid, error) |
Get witness data; returns ApiError for an invalid key |
GetHashedMessage(uuid, name, vout, leaf) |
HashedMessage(uuid, name, vout, leaf, _), NotFound(uuid, error), or ApiError(uuid, error) |
Get hashed message; returns NotFound when the program is absent and ApiError for non-fatal lookup failures |
GetProtocolVisualization(uuid) |
ProtocolVisualization(uuid, visualization), NotFound(uuid, error), or ApiError(uuid, error) |
Get protocol visualization; returns NotFound when the program is absent and ApiError for non-fatal visualization failures |
DiscardDispatcherJob(uuid, job_id, reason) |
JobDiscarded(uuid, job_id) or ApiError(uuid, error) |
The configured L2 operator stops automatic retries for an unresolved runtime Garbler/Emulator job. Repeated discard is idempotent; setup and ZKP jobs cannot be discarded through this operation. |
| Request Message | Expected Response Message | Notes |
|---|---|---|
GetTransaction(uuid, txid) |
Transaction(uuid, transaction_status, name) |
Get transaction details |
GetTransactionInfoByName(uuid, name) |
TransactionInfo(uuid, name, transaction) |
Get transaction by name |
DispatchTransaction(uuid, transaction, confirmation_threshold, stuck_in_mempool_blocks) |
Transaction(uuid, transaction_status, name) or ApiError(uuid, error) |
Dispatch a transaction; returns ApiError for an invalid confirmation threshold |
DispatchTransactionName(uuid, name) |
Transaction(uuid, transaction_status, name), NotFound(uuid, error), or ApiError(uuid, error) |
Dispatch transaction by name; returns NotFound when the program is absent and ApiError for an invalid or missing transaction name |
GetSPVProof(uuid, txid) |
SPVProof(txid, spv_proof) |
Get SPV proof for transaction |
| Request Message | Expected Response Message | Notes |
|---|---|---|
SubscribeToTransaction(uuid, txid, confirmation_threshold) |
Transaction(uuid, transaction_status, name) or ApiError(uuid, error) |
Subscribe to transaction updates; returns ApiError for an invalid confirmation threshold |
SubscribeToSpendingUTXO(uuid, txid, vout, confirmation_threshold) |
SpendingUTXOTransactionFound(uuid, txid, vout, transaction_status) or ApiError(uuid, error) |
Track a UTXO and notify when it is spent; returns ApiError for an invalid confirmation threshold |
SubscribeToOutputPattern(uuid, filter, confirmation_threshold) |
OutputPatternTransactionFound(txid, transaction_status, tag) or ApiError(uuid, error) |
Subscribe to matching transaction outputs; returns ApiError for an invalid confirmation threshold |
SubscribeToRskPegin(uuid, confirmation_threshold) |
PeginTransactionFound(txid, transaction_status) or ApiError(uuid, error) |
Subscribe to RSK pegin transactions; returns ApiError for an invalid confirmation threshold |
| Request Message | Expected Response Message | Notes |
|---|---|---|
SetFundingUtxo(uuid, utxo) |
N/A | Set funding UTXO (no direct response) |
| Request Message | Expected Response Message | Notes |
|---|---|---|
GetFundingBalance(uuid) |
FundingBalance(uuid, balance), WalletNotReady(uuid), WalletError(uuid, error), or ApiError(uuid, error) |
Get funding balance; returns ApiError when the wallet is unavailable |
GetFundingAddress(uuid) |
FundingAddress(uuid, address), WalletError(uuid, error), or ApiError(uuid, error) |
Get funding address; returns ApiError when the wallet is unavailable |
SendFunds(uuid, destination, fee) |
FundsSent(uuid, txid), WalletNotReady(uuid), WalletError(uuid, error), or ApiError(uuid, error) |
Send funds; returns ApiError when the wallet is unavailable |
| Request Message | Expected Response Message | Notes |
|---|---|---|
SetupKey(uuid, addresses, operator_keys, leader_idx, setup_timeout_secs) |
ApiError(uuid, error) on failure; otherwise N/A |
Setup keys with an optional overall timeout in seconds (None defaults to one hour); returns ApiError for invalid participants, duplicate identifiers, or other non-fatal setup failures, and has no direct success response |
GetAggregatedPubkey(uuid) |
AggregatedPubkey(uuid, aggregated_pubkey), AggregatedPubkeyNotReady(uuid), or ApiError(uuid, error) |
Get aggregated public key; returns ApiError when the stored value is not a public key |
GetKeyPair(uuid) |
KeyPair(uuid, private_key, public_key) or ApiError(uuid, error) |
Generate key pair; returns ApiError when the aggregated key is missing or invalid, or for a non-storage key-manager failure |
GetPubKey(uuid, new_key) |
PubKey(uuid, pub_key) or ApiError(uuid, error) |
Get public key; returns ApiError when an existing aggregated key is missing or invalid, or for a non-storage key-manager failure |
GetEvenPubKey(uuid) |
PubKey(uuid, pub_key) or ApiError(uuid, error) |
Generate an adjusted public key; returns ApiError for a non-storage key-manager failure |
SignMessage(uuid, payload_to_sign, public_key_to_use) |
SignedMessage(uuid, signature_r, signature_s, recovery_id) or ApiError(uuid, error) |
Sign a message; returns ApiError for an invalid payload or a non-storage key-manager failure |
| Request Message | Expected Response Message | Notes |
|---|---|---|
Encrypt(uuid, payload_to_encrypt, public_key_to_use) |
Encrypted(uuid, encrypted_message) or ApiError(uuid, error) |
Encrypt a message; returns ApiError for a non-storage key-manager failure |
Decrypt(uuid, payload_to_decrypt, public_key_to_use) |
Decrypted(uuid, decrypted_message) or ApiError(uuid, error) |
Decrypt a message; returns ApiError for a non-storage key-manager failure |
| Request Message | Expected Response Message | Notes |
|---|---|---|
GenerateZKP(uuid, payload_to_sign, name, execution_timeout_secs) |
ZKPResult(uuid, proof, journal), ProofGenerationError(uuid, error), ProofNotReady(uuid) or ApiError(uuid, error) |
Generate zero-knowledge proof; the response is sent when the job ends and already carries the proof, so no follow-up request is needed. Repeating the request for an existing job does not dispatch it again: it is answered at once with ProofNotReady while the job runs, or with the job's result once it has ended. The optional timeout defaults to 900 seconds. Reusing a job id with a different timeout returns ApiError |
GetZKPExecutionResult(uuid) |
ZKPResult(uuid, proof, journal) or ProofNotReady(uuid) or ProofGenerationError(uuid, error) or ApiError(uuid, error) |
Query the status or result of a ZKP job at any time; returns ApiError when a successful job is missing its proof or journal |
- Named transactions dispatched internally by the protocols will be sent to all protocol participants as response message
Transactionwithout needing to request aGetTransactionmessage
- Successful subscription requests have no direct response; they generate events when relevant transactions are found. An invalid confirmation threshold produces an immediate
ApiError(uuid, error)response. Shutdown(uuid)requests a node shutdown and has no direct response
Errors come in two shapes.
Reply-style errors answer a request and carry its UUID: ApiError, NotFound,
WalletNotReady, WalletError, and ProofGenerationError. ApiError represents request validation
or business-state failures that do not have a more specific response type. The UUID ensures that
responses are matched to the correct request even in error cases. These appear in the tables above.
Push-style errors are unprompted — the client detected something and is telling you. There is exactly one such message, and because it answers no request it appears in no table:
Error(ErrorReport { scope, kind, detail })
scope says who it concerns: Node (the client itself), Program(uuid), or Request(uuid).
A Request-scoped report is delivered to whoever issued that request, not to L2.
kind says what happened:
| Kind | Meaning |
|---|---|
SetupFailed { step, peer, reason } |
A setup cannot complete. Terminal: no further messages for that program, and its id cannot be reused. |
JobDispatcherUnresponsive(which) |
A job dispatcher stopped answering pings within the timeout. It may be gone, or far enough behind on its inbox to look that way, so treat it as a warning about job progress rather than proof the process died. |
JobDispatcherRecovered(which) |
That dispatcher is answering again. |
JobFailed { job_id, dispatcher } |
A dispatcher declared a runtime attempt failed. The program remains active and the job is retained for automatic redispatch; detail contains the reason. Use DiscardDispatcherJob to stop retries explicitly. |
BitcoinRpcUnavailable |
The bitcoin node is unreachable. The client keeps running and retrying. |
BitcoinRpcRecovered |
The bitcoin node is reachable again. |
Fatal |
The client cannot continue and is exiting — storage or the message broker failed. Best-effort: it may not arrive. |
NodeStopping |
The client is stopping on an error that does not indicate corrupted state. It exits zero, unlike Fatal, so it is not asking to be restarted. Carrying on past these is not implemented yet. |
TransactionDispatchFailed { txid } |
Dispatch retries exhausted; the transaction will never confirm. |
SpeedupDispatchFailed { txid } |
A CPFP/RBF speedup could not be dispatched. |
TransactionStuckInMempool { txid } |
A transaction has sat in the mempool past its threshold. |
FeeRateTooHigh { estimated, max } |
The estimated fee rate exceeded the configured cap; nothing was dispatched. |
MaxFeeRateReached { txid, effective_fee_rate } |
A speedup hit the fee cap. No further boosts will be applied. |
InsufficientFunds { available, required } |
A funding UTXO could not cover a speedup fee. |
FundingNotAvailable |
No funding UTXO is available at all. |
InvalidFundingUtxo { amount, min_required } |
A funding UTXO was provided but is unusable. |
detail is optional free text for logs and operators; never match on it.
The liveness kinds are reported on change, not repeatedly: one message when the condition starts, one when it clears.
- All correlation IDs are generated using the
request_to_correlation_id()andresponse_to_correlation_id()functions - UUID-based correlation IDs ensure that multiple concurrent operations can be tracked independently
- Some operations (like
SetFundingUtxo,SetupKey) don't have direct response messages - The system supports both named and unnamed transaction dispatching with different correlation ID patterns