Skip to Content
Early draft of the Exec402 docs. Interfaces and APIs may change.
Executors

Executors

Executors are off-chain actors that:

  • monitor the Exec canister for new tasks,
  • decide which tasks are profitable,
  • submit transactions to ExecCore on supported chains,
  • earn a portion of the task fee when executions succeed.

This page focuses on how executors fit into Exec402 and what running one looks like in practice.

Why executors exist

Without shared executors, every product that wants good UX would have to:

  • operate hot wallets and manage gas across multiple chains,
  • implement custom retry / failure handling,
  • monitor protocols for execution results.

Executors specialize in this instead:

  • they watch the shared task registry (Exec canister),
  • compete to execute tasks that are profitable,
  • turn “user/agent signed and paid once” into “final on-chain result”.

Exec402 is designed so that anyone can become an executor; there is no allow-list.
More independent executors make the network more robust, tasks execute faster, and overall execution efficiency improves.

Incentives and fee split

For every successfully executed task:

  • a fixed 10% protocol fee is taken,
  • a configurable referrer share (currently 60% of the total fee) is paid to the referrer address,
  • the remaining 30% goes to the executor that executed the task.

This split is enforced by the ExecCore contracts on-chain. There is no off-chain settlement with a central operator.

More executors improve liveness and robustness; competition encourages better execution and pricing strategies over time.

Trust and risk model

Executors are permissionless and untrusted:

  • They cannot arbitrarily move funds; they can only submit ExecCore calls for tasks published by the Exec canister.
  • ExecCore verifies:
    • the task id and attestor signature,
    • permit validity and amounts,
    • and then executes the target call.
  • 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 Exec402 do not custody user funds outside of the execution flow.

For executors themselves:

  • they are responsible for their own strategy — which tasks to execute, at what gas price, on which chains,
  • malicious referrers can publish unprofitable or reverting tasks, but cannot steal funds or move user tokens outside what the task and permits describe; the main economic risk for executors is wasting gas on bad tasks if they ignore their own checks.

What an executor does (conceptually)

Any executor implementation — including the reference executor-bot — follows roughly this lifecycle:

  1. Discover tasks
    • poll the Exec canister for Pending tasks per chain.
  2. Filter and evaluate
    • apply allow-lists (chains, tokens, targets);
    • skip tasks that are expired, missing signatures, or clearly invalid;
    • estimate gas cost and reward (using estimateTxFee + getTokenPrice).
  3. Decide profitability
    • compare expected reward (task fee) vs. estimated gas in USD;
    • apply thresholds like minProfitUsd, minMargin, maxGasUsd.
  4. Execute profitable tasks
    • call ExecCore.call or ExecCore.transfer with:
      • the task id,
      • parsed payload (token, target/recipients, amounts, fee),
      • permit data,
      • attestor signature.
  5. Record outcome and metrics
    • update per-chain stats (seen, skipped, executed, failed, rewards, gas);
    • log execution time and any errors.

The reference executor-bot

Anyone can build their own executor implementation and choose their own execution strategy.
The Exec402 team also maintains an open source reference bot at https://github.com/exec402/executor-bot .

The executor-bot package in the Exec402 repositories is a Node.js daemon built on @exec402/core:

  • polls the Exec canister by status=Pending and chainId,
  • prices the task fee token to USD and compares it with estimated gas,
  • respects per-chain and per-token allow-lists,
  • logs structured JSON metrics and periodic summaries,
  • supports dry-run mode for testing strategies without sending transactions.

Prerequisites

To run an executor-bot you need:

  • Node 20+,
  • RPC endpoints for the chains you want to execute on,
  • a funded private key (the executor’s on-chain wallet) for paying gas.

Quick start (high level)

From the repository root:

  1. Configure environment

    • copy .env.example to .env under executor-bot/,
    • set:
      • PRIVATE_KEY – executor wallet private key,
      • EXEC402_NETWORK – testnet or mainnet,
      • CHAINS – comma-separated chain ids (optional; defaults per network),
      • RPC URLs (RPC_8453, RPC_10, RPC_56, etc.).

  2. Install and run

    cd executor-bot
npm install
npm run dev   # or: npm run build && npm start

  3. Observe logs

    • watch JSON logs for:
      • listed tasks,
      • skip / execute decisions,
      • gas and reward estimates,
      • periodic per-chain summaries.

You can run one executor-bot per network or per chain set, and tune environment variables as your strategy evolves (MIN_PROFIT_USD, MIN_MARGIN, MAX_GAS_USD, allow-lists, etc.). You can also start with DRY_RUN=true to see decisions and metrics without actually sending transactions.

For full details, including Docker deployment and all configuration options, see the executor-bot README in the Exec402 repositories.

Last updated on
ReferrersFAQ