About Processing Intents

When a participant creates an intent — a request to move value between wallets — the ledger does not simply execute it. The intent passes through a processing pipeline with three stages, each serving a distinct purpose. Understanding this pipeline is essential for bridge developers because it tells you exactly where your bridge fits and what it does not need to worry about.

The three processing stages

Every intent passes through three stages in order:

Aspects run first. These are synchronous validation hooks — business rules, compliance checks, transaction limits, fraud scoring. Aspects execute before any bridge is contacted. If an aspect rejects the intent, processing stops immediately and no bridge ever sees the transaction. Aspect configuration through processing policies is documented in the Structuring Data section.

Orchestration runs second. This is where bridges participate through the two-phase commit protocol. The ledger coordinates a distributed transaction across every bridge involved in the intent, ensuring that either all external systems commit or all abort. This stage is covered in detail in the orchestration page.

Effects run last. These are asynchronous notifications — webhooks, event listeners, status callbacks — that fire after the intent reaches its final state. Effects cannot change the outcome of the intent. Effect configuration is covered in the Connecting Systems advanced guides.

This ordering matters. Your bridge does not need to implement business-rule validation that belongs in aspects, and it does not need to worry about downstream notifications that belong in effects. The bridge's job is narrow and well-defined: participate in the orchestration stage to coordinate real operations on the external system it represents.

Intents and claims

An intent is the ledger's unit of work. It represents a request to move value — a payment, a transfer, a settlement. Every money movement on the ledger starts as an intent.

An intent contains one or more claims. Each claim describes a single movement of value: an action (typically transfer), a source wallet, a target wallet, a symbol (currency), and an amount. A simple person-to-person payment has one claim. A more complex operation — like a fee split or a multi-party settlement — can have several claims in a single intent.

{
  "handle": "20250405123456789TFY000000332217523",
  "schema": "payment",
  "claims": [
    {
      "action": "transfer",
      "amount": 44212,
      "source": { "handle": "svgs:85620797@bancoamarillo.com.co" },
      "symbol": { "handle": "cop" },
      "target": { "handle": "svgs:84660643@bancorojo.co" }
    }
  ],
  "custom": {
    "paymentNetwork": "TFY",
    "description": "Pago de servicios"
  }
}

The handle is a unique identifier for the intent. Payment networks often use a structured format like YYYYMMDDHHMMSS{network}{uniqueID} for end-to-end tracking and reconciliation.

The schema identifies the type of intent. Different schemas can trigger different validation rules through aspects and different processing behavior through policies.

The custom object carries application-specific metadata that travels with the intent through the entire processing pipeline. Bridges receive this data in their prepare, commit, and abort calls, which makes it useful for passing context like payment descriptions, routing codes, or compliance identifiers.

Payment initiation

Creating an intent is a straightforward API call. The initiator sends POST /v2/intents with the intent data and a cryptographic signature from the initiating signer.

The ledger validates the request structure, checks that the referenced wallets and symbols exist, and runs any applicable aspects. If everything passes, the intent is recorded with status pending and the ledger begins the orchestration stage — coordinating the bridges that need to participate.

Intent status flow

An intent moves through a defined set of statuses as it is processed:

• pending — the intent has been created and validated. Aspects have passed. The orchestration stage is about to begin.
• prepared — all participating bridges have submitted prepared proofs. The ledger is ready to commit.
• committed — commit requests have been sent to all bridges. Awaiting committed proofs.
• completed — all bridges have confirmed commit. The intent is fully processed.
• rejected — the intent was aborted because one or more bridges failed during prepare. All side-effects have been reversed.

The status transitions are deterministic. Once an intent reaches prepared, it will either advance to completed (all commits succeed) or rejected (an error forced an abort). There is no path from committed back to rejected — once commit is sent, it must succeed.

To receive notifications when an intent reaches a final state, register an effect that filters on intent status changes. Effects deliver notifications asynchronously — either as a webhook to any URL or through the bridge's POST /v2/effects/:handle endpoint if the bridge declares the events trait. This keeps status tracking outside the core orchestration interface.

What bridges see

When the orchestration stage begins, each bridge involved in the intent receives the full intent context as part of its prepare call. The debit or credit entry sent to the bridge includes:

• The entry handle (e.g., deb_01u9RGCevt4rEkRMV) — the bridge's idempotency key
• The amount and symbol for this specific entry
• The source and target wallet handles with any custom metadata
• The complete intent record — all claims, custom data, access rules, and current proofs

This means your bridge has everything it needs to make a decision during prepare. It can validate the operation, check business rules specific to the claim, and inspect the full intent context before deciding to accept or reject.

For the detailed protocol of how bridges interact during orchestration — prepare, commit, abort, and proofs — see About Orchestrating Systems.