Protocol Overview

This page explains the core concepts of the Exec402 protocol: roles, tasks, and fees for on-chain execution.

Roles

Exec402 introduces four primary roles around a shared task registry (the Exec canister) and on-chain settlement contracts (ExecCore):

Initiator (user or agent wallet)

The initiator is the on-chain payer — the user or agent wallet that ultimately authorizes and funds an execution.

Signs x402-style payment authorizations instead of building raw transactions.
Does not send the final transaction directly or manage gas on the settlement chain.

Executor

The executor is an off-chain actor that turns tasks from the Exec canister into ExecCore transactions.

Monitors the Exec canister task registry (and potentially other compatible sources).
Selects tasks that are profitable to execute.
Pays gas, submits a transaction to the ExecCore contracts on the target chain.
Earns a share of the fee if the execution succeeds.

Executors are permissionless. Any wallet can attempt to execute any valid task.

Referrer (agent or dapp)

The referrer represents the agent or product that sourced the task.

Typically an agent, dApp, wallet, or service where the user initiated the action.
Identified by an address embedded in the task.
Earns a portion of the fee for bringing volume to the protocol.

Referrers can be:

First-party products (e.g. your own app).
Third-party integrators who embed Exec402 flows.

Protocol

The protocol is the Exec402 core itself:

Owns the canonical ExecCore contracts that validate and execute tasks.
Owns and maintains the Exec canister as a shared task registry.
Collects a protocol fee from every execution, with the split encoded on-chain.
May redistribute protocol fees to token holders or other treasuries (out of scope for this page).

Task

A task is the central data structure in Exec402. It has two layers:

a task envelope – metadata tracked by the Exec canister (id, type, status, timestamps, etc.);
a task payload – the actual on-chain call or transfer details that ExecCore uses.

A simplified TypeScript view (mirroring the SDK types) looks like this:


type TaskStatus = "Pending" | "Executed" | "Expired";
type TaskType = "Call" | "Transfer";
type PermitType = "eip3009" | "permit" | "permit2";
 
type PermitData = {
  permitType: PermitType;
  permitParams: `0x${string}`; // ABI-encoded permit params
  signature: `0x${string}`;    // permit signature
};
 
// Envelope stored by the Exec canister
type Task = {
  taskId: string;
  taskType: TaskType;
  payload: string;        // JSON-encoded payload (see below)
  status: TaskStatus;
  executor: string | null;
  createdAt: number;
  updatedAt: number;
  description?: string;
  url?: string | null;
  attestorSignature?: string | null;
  txHash?: string | null;
  blockNumber?: number | null;
  chainId?: number | null;
};
 
// Payload for a Call task
type CallTaskPayload = {
  token: `0x${string}`;
  target: `0x${string}`;
  data: `0x${string}`;
  amount: string;          // net amount to send to target (smallest unit)
  initiator: `0x${string}`;
  referrer: `0x${string}`;
  fee: string;             // absolute fee amount (smallest unit)
  permit: PermitData;
};
 
// Payload for a Transfer task
type TransferTaskPayload = {
  token: `0x${string}`;
  recipients: `0x${string}`[];
  amounts: string[];       // per-recipient amounts (smallest unit)
  initiator: `0x${string}`;
  referrer: `0x${string}`;
  fee: string;
  permit: PermitData;
};

In practice, the canister stores the payload as a JSON string, and ExecCore receives the decoded payload fields along with the task id and attestor signature. Together they give ExecCore everything it needs to verify a permit, pull tokens, and execute the call.

Flow at a glance

Initiator (agent or dapp) calls the Exec canister (for example, /call) via an SDK, describing the desired on-chain action and payment details.
If payment is required, the canister responds with an HTTP 402 Payment Required body describing what must be paid. The SDK guides the wallet to sign an x402-style payment authorization and retries the request with an X-PAYMENT header.
Once payment is authorized, the canister creates a task in its registry, assigning it a taskId and attaching an attestor signature so ExecCore can later verify it.
Executors poll the task registry for pending tasks. For each profitable task, an executor submits an ExecCore.call or ExecCore.transfer transaction on the target chain, passing the task id, payload, permit, and attestor signature.
The ExecCore contracts:
- verify the task id and attestor signature,
- validate the permit and pull tokens from the payer,
- send amount to the target contract or recipients,
- split the fee between protocol, referrer, and executor,
- emit events describing the outcome.

Fee model

Exec402 uses a transparent, on-chain fee model.

Conceptually:

For each task:
- A base amount amount is charged to the initiator and sent to the target contract or recipients.
- An explicit fee amount (in the same token) is charged in addition to amount.
- That fee is split between:
  - Protocol – a fixed 10% protocol fee.
  - Referrers – a configurable share of the remaining 90% (by default 60% of the total fee).
  - Executors – the remainder of the fee after protocol and referrer shares (by default 30% of the total fee).

The exact referrer share is set on-chain via ExecCore configuration, and the executor receives whatever is left after protocol and referrer fees. All fee math is encoded in the contracts and can be audited on-chain. The important properties are:

The fee math is done entirely on-chain.
The shares are deterministic and observable by anyone.
There is no opaque middleman taking undisclosed cuts.

Security model

Exec402 is designed so that:

Executors do not have special trust or privileges.
If an executor submits an invalid task or authorization, core contracts simply revert.
If an ExecCore transaction reverts, the entire operation is rolled back: no tokens are moved from the initiator and no fees are paid.
The Exec canister, ExecCore contracts, and the rest of the Exec402 infrastructure do not custody user funds outside of the execution flow — tokens move directly between the initiator, the target contracts or recipients, and fee recipients.
Executors are expected to simulate tasks and estimate gas before executing; malicious referrers can publish unprofitable or reverting tasks, but cannot steal funds or arbitrarily move user tokens.

As a result:

Users only need to trust the Exec402 core contracts and the token contracts they interact with.
Integrators and referrers do not need to operate their own trusted backend for execution.

For a practical overview of how to plug this into your product as a referrer, continue to the Referrers guide.