> ## Documentation Index
> Fetch the complete documentation index at: https://aomi.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction pipeline

> See how a reviewed onchain action moves through build, simulation, authorization, and execution.

Every public execution follows one ordered contract:

**build → simulate → review → commit → resolve actions**

EVM and SVM encode actions differently, but both preserve the proposed action
between simulation and authorization. The model or calling application may
choose an operation and supply arguments. It cannot turn simulation evidence
into signing authority.

## Pipeline at a glance

| Stage    | What happens                                               | Result                                                              |
| -------- | ---------------------------------------------------------- | ------------------------------------------------------------------- |
| Build    | A catalog operation or caller assembles ordered actions.   | An attested Build with `status: "staged"` or `"simulated"`          |
| Simulate | Aomi evaluates the exact action order against chain state. | Typed balance, approval, fee, warning, guard, gas, and log evidence |
| Review   | The application renders the action and evidence.           | An explicit user or delegated-policy decision                       |
| Commit   | Aomi verifies the simulated Build and its digest.          | `status: "committed"` plus typed action requests                    |
| Resolve  | The wallet or authorized signer supplies an outcome.       | Submitted legs, signed outputs, or a rejection                      |

A Build carries an expiry, digest, and server attestation. Pass it unchanged
between lifecycle calls. Later stages cannot replace its action payload or
reorder the batch.

## Build and simulate

Use `POST /v1/pipeline/{chain}/build` when you want Aomi to resolve a
catalog operation, stage it, and simulate it in one request. Use separate
`stage` and `simulate` calls when your application already has explicit
chain actions.

A Build records its origin: the App, active skills, and catalog operations that
assembled it. This makes the result inspectable without treating rendered model
text as execution evidence.

A failed simulation stops the lifecycle before commit. Correct the operation or
action, produce a new Build, and simulate again.

## Commit and action requests

Commit accepts only a simulated Build. It revalidates the Build, checks expiry
and attestation, and returns the same digest with the resulting action
requests.

```json theme={null}
{
  "status": "committed",
  "digest": "sha256:…",
  "result": {},
  "requests": []
}
```

The EVM response has `result`; the SVM response has `results`. The
`requests` array contains typed execution or signing requests. An empty array
means the commit completed without a caller-resolved action. The Pipeline
status itself is only `committed`; submitted, signed, and rejected are action
outcomes.

When an Agent turn reaches the same boundary, it emits an `action` event.
Resolve that action through the versioned action-result route with its exact
revision and typed result.

## Signing authority

The active wallet policy decides who may sign. The App and model do not receive
private keys and do not choose a broader signing mode at commit time.

A request can lead to:

* a connected wallet reviewing and submitting;
* an authorized signer executing under an existing grant;
* a signature returned to an allowed venue continuation; or
* a refusal when policy, review, or chain validation fails.

The broadcaster recorded in the staged action constrains where submission may
occur. It does not grant signing authority.

## Plugin routes

A Rust plugin can return a `ToolReturn` that suggests the next host step.
Use route bindings for workflows in which a wallet signature or transaction
result must feed a later plugin tool.

```rust theme={null}
use aomi_sdk::{ToolReturn, host};
use serde_json::json;

let routed = ToolReturn::route(json!({ "quote_id": quote.id }))
    .next(|next| {
        next.add::<host::EvmCommitMessage>(json!({
            "typed_data": quote.typed_data
        }))
        .bind_as("signature");
    })
    .after::<SubmitQuote>(json!({ "quote_id": quote.id }))
    .awaits("signature")
    .build();
```

Preserve the tool-produced arguments and bound artifacts exactly. The host
injects the bound value into the awaiting tool arguments. Do not ask the model
to reconstruct a signature, transaction hash, quote ID, or route ID.

## Host namespaces

Plugins request only the host tool sets they use:

| Namespace      | Capability                                                          |
| -------------- | ------------------------------------------------------------------- |
| `evm-core`     | Full EVM read, stage, simulate, message-signing, and commit surface |
| `evm-reads`    | EVM account, contract, context, and read calls                      |
| `evm-sim`      | EVM staging and simulation without commit tools                     |
| `svm-core`     | Full SVM catalog                                                    |
| `svm-reads`    | SVM account, program, token, and context reads                      |
| `svm-write-ix` | Instruction-list stage, simulate, and commit lane                   |
| `svm-write-tx` | Complete-transaction stage, simulate, and commit lane               |

Use `namespaces = []` for an App that only calls an external API. Namespace
selection controls tool visibility; it does not authorize a signature.

## The invariant

A commit is bound to the Build that passed simulation. A caller cannot replace
the target, value, calldata, instruction bytes, or action order during commit.

**An action that fails simulation does not cross the signing boundary.**

<CardGroup cols={2}>
  <Card title="Pipeline API" icon="diagram-project" href="/docs/api-reference/pipeline">
    Drive the stateless lifecycle and inspect its schemas.
  </Card>

  <Card title="Permission model" icon="shield-check" href="/docs/security/permission-model">
    Learn how signing authority is granted and refused.
  </Card>
</CardGroup>
