RPC confirmation and recovery
Confirmation answers three separate questions: has the local index observed the output, did transaction execution succeed, and what native confirmation level has its canonical block reached?
Native finality and index progress
invisi_getStatus returns indexedHead and finality.latest/safe/finalized. Each native head has status and block; status is available, unsupported, unavailable, or inconsistent.
unsupported: the upstream explicitly rejects the method or tag.unavailable: no valid head can currently be obtained, including transport failures or null.inconsistent: heads or previously accepted finalized history conflict.available: a usable native head, which can remain at the same height during a stall.
The service never converts block depth or elapsed time into safe/finalized. Native heads can be ahead of indexing; missing finality capability does not make every read unavailable. Compare the transaction block with the required native head according to business policy, rather than substituting index height.
Request trusted Note confirmation
This read-only example requires a POSIX shell, curl, and jq. Set PROTOCOL_RPC_URL to the full trusted chain route and NOTE_COMMITMENT to the full, nonzero, canonical BN254 scalar commitment recomputed from local receiving materials. jq constructs JSON safely.
: "${PROTOCOL_RPC_URL:?Set the full trusted chain RPC URL}"
: "${NOTE_COMMITMENT:?Set the full expected Note commitment}"
jq -n --arg commitment "$NOTE_COMMITMENT" \
'{jsonrpc:"2.0",id:"note-1",method:"invisi_getNote",params:[$commitment,{finality:"finalized"}]}' |
curl --fail-with-body -sS "$PROTOCOL_RPC_URL" \
-H 'Content-Type: application/json' --data-binary @-
Only safe and finalized are accepted; latest, null, and unknown selector fields are rejected. A successful confirmation-mode response contains versions, deployment, indexedHead, status, reason, output, membership, and confirmation.
For status:"confirmed", reason is null and confirmation includes finality, verifiedAt, and finalityHead. The verification anchor is the lower of the index and native finality heads. The service checks the successful receipt, canonical block, path, and contract root at that anchor, then rechecks canonicality and finality.
For status:"pending", output, membership, and confirmation are null. Do not persist these nulls as permanent absence.
| reason | Application action |
|---|---|
not_observed | Keep the order open and continue checking the expected commitment |
pending_index | Wait for indexing to catch up |
confirmation_pending | Wait for the required native level |
finality_unsupported | Use a capable trusted source or explicitly revise business policy |
finality_unavailable | Suspend confirmation and retry with bounded backoff |
finality_inconsistent | Stop automatic redemption and investigate trusted chain sources |
An RPC error is not pending and cannot become confirmed. Server confirmation contains no merchant order, private opening, or local redemption state; the application must atomically record receipt and fulfillment itself.
Per-transaction availability
invisi_getTransactionNoteUpdates and its Credit counterpart return status, indexedHead, and optional block and receiptStatus fields.
| status | Meaning |
|---|---|
not_found | No mined receipt obtained; the transaction may be unknown or pending |
pending_index | A canonical receipt exists but the local canonical index is not ready |
indexed | The transaction's indexed projections are available |
Before indexing, notes / states / transitions are null; afterward they are arrays, including empty arrays. receiptStatus 0 means reverted and 1 means successful execution, independently of index availability. Unrelated or reverted transactions can have empty arrays. Settlement-operation lookup always initializes operations to an empty array and has a separate failed status; do not reuse the typed-update null contract there.
Errors and retries
Check HTTP before JSON-RPC. For HTTP 429, respect Retry-After and use bounded exponential backoff with jitter. For 413 reduce the request; for 415 fix Content-Type; for 404 check the route and active chain. The backend adds no CORS/authentication by default, so browser integration depends on the operator's gateway policy.
JSON-RPC -32601 means unknown method, -32602 argument decoding failure, and -32000 semantic, storage, or upstream rejection. Public errors are sanitized; do not classify failures using backend message substrings. Do not endlessly retry invalid parameters.
Bodies are limited to 1 MiB, batches to 20 calls, and batch responses to 16 MiB. Match batch responses by id rather than order. Use identified requests whenever completion evidence matters; notifications have no response. After a reorg, reacquire trusted anchors, roll back local orphan projections, and resume synchronization.