RPC Integration Patterns

Tidecoin exposes the Bitcoin Core JSON-RPC model plus Tidecoin-specific PQHD and AuxPoW RPCs. This page covers integration idioms and workflows. For command schemas and return fields, use RPC Reference. For binding, authentication, and access control, use RPC Security.

Ownership boundary

Node health gate

Every long-running integration should gate work on node health:

tidecoin-cli getblockchaininfo
tidecoin-cli getnetworkinfo

Before enabling deposits or withdrawals, check:

Block tailing

Prefer waitfornewblock for low-latency block tailing, with a polling fallback for process restarts.

tidecoin-cli waitfornewblock 60

Store both height and hash. Heights can be reused during a reorg; hashes identify the actual block.

Recommended loop:

1. Read current tip from getblockchaininfo.
2. If this is startup, backfill from the last finalized height you have processed.
3. Call waitfornewblock <timeout>.
4. Fetch the block by hash with getblock <hash> 2.
5. Process transactions idempotently.
6. Store the processed block hash, height, and previous block hash.

Reorg handling

Never treat height alone as a primary key.

For every processed block, store:

On a new tip:

1. Compare the new block’s previousblockhash to your stored tip hash.
2. If it matches, append normally.
3. If it does not match, walk backward with getblockheader or getblock until you find a common ancestor.
4. Mark transactions from disconnected blocks as unconfirmed or reversed.
5. Replay blocks from the common ancestor to the new tip.

Wallet deposit monitoring

For wallet-backed deposits, listsinceblock is the simplest cursor API. Use a confirmation target so transactions are re-reported until they are deep enough.

tidecoin-cli -rpcwallet="deposits" listsinceblock "<lastblock>" 6 true true

Typical handling:

If you do not use the wallet, scan blocks directly with getblock and decode outputs with your own address index.

Raw transaction lookup

Use getrawtransaction carefully:

tidecoin-cli getrawtransaction "<txid>" 2 "<blockhash>"

Passing a blockhash avoids ambiguity and avoids depending on mempool or global transaction index availability. For wallet transactions, use gettransaction on the wallet endpoint.

Mempool observation

Mempool data is policy-local. It is useful for withdrawal monitoring and broadcast feedback, but it is not consensus state.

Useful checks:

tidecoin-cli testmempoolaccept '["<rawtxhex>"]'
tidecoin-cli sendrawtransaction "<rawtxhex>" "<maxfeerate>"

Handle RPC_VERIFY_REJECTED (-26) as a rejection and store the message for operator review. Common rejection reasons include low fee, dust, non-standardness, pre-activation witness/script use, and invalid signatures.

Batching and rate limits

JSON-RPC supports batching at the HTTP layer. Use it for independent lookups such as getblockhash or getrawtransaction, but do not batch state-changing wallet operations unless your application can tolerate partial success and retry ambiguity.

Rules:

Retry policy

Source of truth

See also: Reference / RPC Reference, Reference / RPC Error Codes, Exchange Integration.