Protocol terms and state boundaries
This page defines concepts used throughout the protocol guides. For hosted InvisiPay merchant concepts, see Business Payments terms. Similar names do not make resources or authentication interchangeable.
Core instance and SDK types
A Core instance is a specific contract deployed on a chain, with its own funds, trees, authorization, and management state. Pin chain ID, contract address, runtime code identity, and deployment start block. Notes for the same token in different instances are separate inventory.
The SDK type Protocol represents this deployment context. Code identifiers such as Protocol, protocolAddress, and protocol retain their names. “Core instance address” in prose refers to the contract address in those APIs, rather than a separate contract.
Core integration describes operations; compatibility covers ABI, SDK, proof-resource, and service versions.
Note and Credit
| Term | Meaning | What it does not establish |
|---|---|---|
| Note | A private funds credential for settled assets; its opening contains amount, asset, receiving identity, and recovery material, while the chain stores a commitment | A commitment or membership path grants no spending authority and does not prove unspent status |
| Credit | Deferred debit authorization against an owner's wallet; private state records terms, expiry, and usage | A limit is neither deposited nor locked funds and guarantees neither owner balance nor allowance |
| commitment | A cryptographic commitment to a Note or Credit state | A shared wire format does not make the two credentials interchangeable |
| nullifier | A public marker preventing repeated consumption of an old state | An unconsumed Credit state does not establish that its original grant remains unrevoked |
| membership | Proof that a commitment belongs to an accepted root | Historical membership does not replace current consumption, revocation, and local-reservation checks |
| opening | Preimage material needed to recompute a commitment and recover private state | Complete Note viewing material can enable a full sweep to the original owner; it is not purely read-only |
Note funds flows and Credit authority explain their separate models. SDK, Core, and native IPP amounts use token base units. Hosted InvisiPay API amounts use decimal strings in currency units.
Participants and authority
| Role | Meaning in the protocol |
|---|---|
| owner | The Note owner or Credit grant owner; free spending and grant management require the corresponding authorization |
| spender | The party authorized to initiate a Credit draw, rather than an arbitrary EVM transaction sender |
| payer | The actual source of public ERC-20 funds, such as a depositor or an owner in a draw |
| recipient | The receiver of an output Note or public withdrawal; it can differ from the Credit spender |
| submitter | The account signing and broadcasting the EVM transaction and paying native gas; a Broadcaster can take this role |
| quoteSigner | The trusted signer of a Broadcaster quote; its quote does not replace owner or payer authorization |
| Provenance provider / issuer | The issuer of Provenance recognition, distinct from an external risk-data supplier or Chain RPC operator |
One party can hold several roles, but signatures, balance, allowance, and information-access permissions remain separate checks. See Security and trust.
Three kinds of completion
| State domain | What it establishes | What remains |
|---|---|---|
Chain included | The transaction is in a canonical block, and its receipt indicates success or revert | Verify native safe or finalized according to business policy |
Chain safe / finalized | A supported native confirmation head covers the transaction block | Authenticate canonical block identity and the source; never substitute elapsed time or fixed block depth |
| Wallet reconciliation | The original operation agrees with canonical receipts, consumption, outputs, and local inventory | Observe the required confirmation level separately; retain reservations while outcomes are unknown |
| IPP redemption | Facilitator validated evidence against fixed requirements before cutoff and atomically recorded one successful receipt | The merchant authenticates retrieval, binds its original order, and makes business fulfillment idempotent |
Broadcaster confirmed / reverted mean successful / reverted receipt execution, rather than native finalized. getConfirmation() observes confirmation without automatically releasing wallet reservations. HTTP 200, submission acceptance, or client-copied receipt JSON does not establish that a merchant should fulfill an order.
Provenance proof and recognition
The payer generates a source proof locally to establish input membership under a trusted issuer's recognition set for a specific operation. Recognition is the issuer's published statement after the service checks chain funding, required source decisions, and proofs. These are separate completion states.
broadcastDecision=allow is short-lived relay preflight. A proof job's valid means verification passed. Formal recognition requires the exact operation's recognized state, published checkpoint, current generation, and signed certificates, checked against canonical finalized anchors. Recognition does not establish identity, legal compliance, ownership, or unspent status.
See Provenance and the evidence workflow.
Native IPP and hosted Checkout
A native IPP Checkout is a launch object providing sessionUrl and checkoutUrl. PaymentSession holds options, current state, the fixed Request, and receipt. The wallet follows IPP links with a Session Token to read and confirm; wallet/Core authorization executes the actual payment.
A hosted InvisiPay Checkout is the merchant collection resource in the Business Payments API, with its own fields, Bearer API Key, states, and confirmation-speed contract. Even when both services use a /v1/checkouts path, their requests, tokens, amount units, and success criteria cannot be mixed.
Return to the goal-based reading paths, or continue with the protocol quickstart.