Executor

An executor discovers executable authorization graphs and performs the authorized transitions. Executors earn fees embedded in the authorization objects they consume.

Executors are not trusted operators. They are discoverers of executable authorization relationships.

Relationship to the node

An executor is a separate process from the node. It connects to a node via HTTP, fetches objects, evaluates graphs locally, and submits receipts back to the node as plain objects. The node has no knowledge of the executor. No registration is required. No node operator permission is required.

All execution logic lives in the aon-sdk package. The node stores and propagates objects. The SDK evaluates what those objects mean.

What an executor does

For aon-namespace-csd-usdc (aon:csd-usdc), the executor's role is narrow. The buyer has signed an authorization. The seller has locked the reserve and submitted the CSD proof. The executor recognizes that the graph is complete and acts:

1. Fetch objects from node filtered by namespace
2. Find executable graphs using SDK helpers
3. Verify the graph via the namespace adapter
4. Execute: submits the on-chain settlement transaction
5. Build a Receipt Object and submit it to the node via POST /v1/objects

The reserve is created by the seller, not the executor. The buyer's USDC is locked when the seller calls the settlement contract. The executor enters once the graph is complete and requires nothing more than settlement.

For aon-namespace-evm-spot (aon:evm-spot), the executor finds a compatible maker/taker pair, constructs the fill, and settles atomically in a single transaction. No reserve step; settlement is the lock.

Running an executor

Executors import the SDK and any namespace packages they want to support. Namespaces are registered before the loop starts; the executor only acts within its configured namespace:

import { runExecutor, registerNamespace } from "@intervalplace/aon-sdk";
import { csdUsdcNamespace } from "aon-namespace-csd-usdc";

registerNamespace(csdUsdcNamespace);

await runExecutor({
  nodeUrl:        "http://localhost:8787",
  namespace:      "aon:csd-usdc",
  mode:           "contract",
  pollIntervalMs: 5000,
  onExecuted: (graph, result) => {
    console.log("executed", result);
  },
  onError: (err, context) => {
    console.error("error in", context, err);
  },
});

The executor polls the node, evaluates graphs locally using the namespace driver, and submits receipts back as plain objects via POST /v1/objects. On poll failure it backs off exponentially: default 1s initial, 2x factor, 60s maximum. Resets to the configured interval on success.

Fees

Fees are specified by participants in their Authorization Objects, not by the network. A CSD/USDC authorization specifies executorFeeAmount: the portion of USDC paid to whichever executor completes the transition. An EVM spot session specifies maxExecutorFeeQuote.

Fees are paid by the settlement contract at the moment of settlement. There is no separate claiming step. Executors prioritize graphs with higher fees relative to execution cost. The fee is the incentive; speed is the competition.

Capital and risk

Executors do not commit capital. The reserve in aon-namespace-csd-usdc is the buyer's USDC, locked by the seller. By the time an executor sees an executable graph, assets are already committed and the proof is already verified. The executor's only exposure is gas.

For aon-namespace-evm-spot, settlement is atomic; if the transaction reverts, nothing moves.

Competition

Multiple executors may discover the same graph. The first valid settlement transaction included wins; subsequent attempts revert on-chain. The node rejects duplicate receipts referencing the same graph. The fee is the incentive. Speed is the competition.

Execution modes

The mode field controls what the executor actually does when it finds an executable graph:

contract  — submits real on-chain transactions
simulate  — dry run, no on-chain effect, no receipt submitted
off       — verifies only, no execution

What an executor cannot do

An executor cannot create permission. It cannot modify the terms of an authorization. It cannot override a proof. It cannot prevent another executor from acting on the same graph.

The role is powerful in a narrow sense: it turns executable graphs into completed transitions. Outside of that, it has no special standing in the network.