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 event | Neuron |
|---|---|
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@v1 | Tool receipt: tool, committed args and result, ok, timing, payment |
model.after@v1 | Model 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
- Build the plugin:
npm run build:plugin. - For each assistant, the owner creates its allowance and receipt log with
agent_id = sha256("neuron:" + <agent id>), sets the session key asagentandauthority, and funds the vault with USDC. - Write
~/.neuron/network.json, or pointNEURON_NETWORK_CONFIGat a file. - 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
| Key | Default | Meaning |
|---|---|---|
rpcUrl | required | Solana RPC; ${ENV_VAR} is expanded |
rpcHeaders | none | Extra headers for header-auth providers; values expand ${ENV_VAR} |
feePayerKeypair | required | Relayer that pays fees, and rent for a payee's first token account |
agents | required | Agent id → owner and sessionKeypair. Unlisted agents are ignored. |
tools | none | Tool name → price (decimal string, > 0) and payTo. Unlisted tools are free. |
receiptsDir | ~/.neuron/receipts | Where batch files and the payment journal live |
batch.maxReceipts | 32 | Post when this many receipts are queued (1–1024) |
batch.maxDelayMs | 10000 | Post at most this long after the first queued receipt |
allowanceCacheMs | 3000 | How long an allowance read (pause flag, budget) is reused |
allowanceFetchTimeoutMs | 2000 | Give up on a read and use the last known state |
maxStalenessMs | 300000 | After this long without a successful read, every tool is blocked |
confirmTimeoutMs | 30000 | How long a tool call waits for its payment to confirm |
currencySymbol | $ | Shown in messages |
programs | bundled IDLs | Override 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
- Keep the key out of the file.
${ENV_VAR}is expanded inrpcUrlandrpcHeaders, so the config can be committed. A missing variable stops the assistant at startup with an error that names the variable, never a value. - Never leaked. web3.js errors quote the full URL, so the plugin scrubs credentials from every log line and every message shown to the assistant.
- No WebSocket needed. Payments are confirmed by polling, so an HTTP-only endpoint works.
What the assistant sees
Neuron Agent returns the reason to the model as "Tool call … was blocked by a plugin: …":
This assistant is paused by its owner."book_flight" costs $274.00, which is above the ask-first limit of $10.00. Ask the owner to approve it."deep_research" costs $9.00, but only $2.00 of this week's allowance is left.The payment for "web_search" ($0.02) is still being confirmed. Don't retry yet: …Couldn't reach Solana to pay for "web_search". Nothing was charged; try again shortly.
Behaviour
- Fails closed for money. If anything goes wrong while paying, the paid tool doesn't run. Each payment is journaled to disk before it's sent, and reconciled at the next start if the process dies.
- An unclear outcome isn't a failure. If a payment was sent but its confirmation timed out, the assistant is told not to retry. If it lands, its receipt is recorded and it becomes a credit the next identical call uses, so nobody is charged twice.
- Blocked after payment. If the tool then needs owner approval in Neuron Agent (
BLOCKED: …), the payment becomes a credit for the retry. Other tool failures keep the payment, like a paid API call that errors. - Pause fails closed. If the allowance can't be read for
maxStalenessMs, or ever, every tool is blocked. - A wrong setup refuses to start. A missing receipt log, or a log or allowance that belongs to a different key, stops the assistant from loading.
Files on disk
Path under receiptsDir/<agent>/ | What |
|---|---|
NNNNNNNN.receipts.json | The publishable batch: canonical receipts; sha256 equals the on-chain data_hash |
NNNNNNNN.json | Private record with the salts, signatures and payment links. Never publish it. |
payments/<signature>.json | Payments not yet confirmed (the journal) |
pending-*.json | Receipts that couldn't be posted (shutdown, overflow), kept rather than dropped |