Build

Agent plugin

The Neuron plugin gives Neuron Agent assistants an on-chain allowance, a Pause button that stops every tool, and a verifiable receipt for every model call, tool call and payment.

Requires Neuron Agent, our renamed fork of OpenHermit, which ships the model events and the plugin loader.

What it does

Neuron Agent eventNeuron
tool.before@v1 (veto, runs last)Pause blocks every tool. Priced tools are paid from the allowance right before they run, or blocked with a reason the assistant can relay.
tool.after@v1Tool receipt: tool, committed args and result, ok, timing, payment
model.after@v1Model receipt: provider, model, committed request and output, usage, timing

Receipts are posted in batches to the assistant's receipt log: every 32 receipts, 10 seconds after the first queued one, and on shutdown.

Turn it on

  1. Build the plugin: npm run build:plugin.
  2. For each assistant, the owner creates its allowance and receipt log with agent_id = sha256("neuron:" + <agent id>), sets the session key as agent and authority, and funds the vault with USDC.
  3. Write ~/.neuron/network.json, or point NEURON_NETWORK_CONFIG at a file.
  4. Register the plugin and restart the gateway. Point at the entry file, because Node's ESM loader can't import a directory by path.
{
  "rpcUrl": "https://mainnet.helius-rpc.com/?api-key=${HELIUS_API_KEY}",
  "feePayerKeypair": "~/.neuron/keys/relayer.json",
  "agents": {
    "my-agent": { "owner": "<owner wallet>", "sessionKeypair": "~/.neuron/keys/my-agent.json" }
  },
  "tools": {
    "web_search": { "price": "0.02", "payTo": "<tool provider wallet>" }
  }
}
neuron gateway config set pluginPackages '["/path/to/neuron-network/plugins/agent/index.cjs"]'
# or: NEURON_PLUGIN_PACKAGES=/path/to/neuron-network/plugins/agent/index.cjs

Configuration

KeyDefaultMeaning
rpcUrlrequiredSolana RPC; ${ENV_VAR} is expanded
rpcHeadersnoneExtra headers for header-auth providers; values expand ${ENV_VAR}
feePayerKeypairrequiredRelayer that pays fees, and rent for a payee's first token account
agentsrequiredAgent id → owner and sessionKeypair. Unlisted agents are ignored.
toolsnoneTool name → price (decimal string, > 0) and payTo. Unlisted tools are free.
receiptsDir~/.neuron/receiptsWhere batch files and the payment journal live
batch.maxReceipts32Post when this many receipts are queued (1–1024)
batch.maxDelayMs10000Post at most this long after the first queued receipt
allowanceCacheMs3000How long an allowance read (pause flag, budget) is reused
allowanceFetchTimeoutMs2000Give up on a read and use the last known state
maxStalenessMs300000After this long without a successful read, every tool is blocked
confirmTimeoutMs30000How long a tool call waits for its payment to confirm
currencySymbol$Shown in messages
programsbundled IDLsOverride the allowance or receipts program id
paymentRail"allowance"How priced tools are paid. The only rail today is a public USDC transfer from the allowance vault; a private one is planned (why)

Use a private RPC

What the assistant sees

Neuron Agent returns the reason to the model as "Tool call … was blocked by a plugin: …":

Behaviour

Files on disk

Path under receiptsDir/<agent>/What
NNNNNNNN.receipts.jsonThe publishable batch: canonical receipts; sha256 equals the on-chain data_hash
NNNNNNNN.jsonPrivate record with the salts, signatures and payment links. Never publish it.
payments/<signature>.jsonPayments not yet confirmed (the journal)
pending-*.jsonReceipts that couldn't be posted (shutdown, overflow), kept rather than dropped