Skip to main content

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.

reasonApplication action
not_observedKeep the order open and continue checking the expected commitment
pending_indexWait for indexing to catch up
confirmation_pendingWait for the required native level
finality_unsupportedUse a capable trusted source or explicitly revise business policy
finality_unavailableSuspend confirmation and retry with bounded backoff
finality_inconsistentStop 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.

statusMeaning
not_foundNo mined receipt obtained; the transaction may be unknown or pending
pending_indexA canonical receipt exists but the local canonical index is not ready
indexedThe 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.