Build
Programs reference
Every instruction, account, event and error in the three Solana programs, generated from their Anchor IDLs. Program IDs are the localnet ones and will change when the programs are deployed to devnet.
neuron_allowance, Anchor clients fill in event_authority and program automatically.neuron_allowance
A USDC vault per assistant, spendable by its session key only within owner-set rules. Payments outside the rules become spend requests the owner approves or cancels. Events are emitted as CPI events (read them with cpiEventsOf).
Program ID (localnet)2ijbmFkxMRdwUYygdGfRwWW82zn3jjVbmZPHHsQbgKuh
Instructions
add_payee
Arguments
payeePubkey
Accounts
| Account | Flags | Notes |
|---|---|---|
owner | writable signer | |
allowance | writable | |
payee_entry | writable | PDA |
system_program | fixed | |
event_authority | PDA | |
program |
approve_request
Accounts
| Account | Flags | Notes |
|---|---|---|
owner | signer | |
allowance | writable | |
request | writable | |
mint | ||
vault | writable | |
destination | writable | Must still belong to the wallet the owner was shown when the request was made. |
rent_refund | writable | |
token_program | ||
event_authority | PDA | |
program |
cancel_request
Accounts
| Account | Flags | Notes |
|---|---|---|
signer | signer | |
allowance | writable | |
request | writable | |
rent_refund | writable | |
event_authority | PDA | |
program |
close_allowance
Fire the assistant: return the balance and close everything.
Accounts
| Account | Flags | Notes |
|---|---|---|
owner | writable signer | |
allowance | writable | |
mint | ||
vault | writable | |
destination | writable | Receives whatever is left in the vault. |
token_program | ||
event_authority | PDA | |
program |
create_allowance
Owner creates an allowance and its vault for one assistant.
Arguments
agent_id[u8; 32]agentPubkeyrulesAllowanceRules
Accounts
| Account | Flags | Notes |
|---|---|---|
owner | writable signer | |
allowance | writable | PDA |
mint | Classic SPL Token mints only (USDC is one). Token-2022 extensions such as transfer hooks, transfer fees or a permanent delegate would lock the vault, misreport amounts, or let the issuer move funds outside the rules. | |
vault | writable | `init_if_needed`: anyone can create an ATA for any owner, so with a plain `init` an attacker could block this allowance by pre-creating its vault. Anchor still checks the mint, authority and token program of an existing one. · PDA |
token_program | ||
associated_token_program | fixed | |
system_program | fixed | |
event_authority | PDA | |
program |
remove_payee
Accounts
| Account | Flags | Notes |
|---|---|---|
owner | writable signer | |
allowance | writable | |
payee_entry | writable | |
event_authority | PDA | |
program |
request_spend
Assistant asks the owner for a payment outside its rules.
Arguments
amountu64memo[u8; 32]
Accounts
| Account | Flags | Notes |
|---|---|---|
agent | signer | |
payer | writable signer | Pays rent for the request account (the assistant or a relayer). |
allowance | writable | |
destination | ||
request | writable | PDA |
system_program | fixed | |
event_authority | PDA | |
program |
set_agent
Arguments
agentPubkey
Accounts
| Account | Flags | Notes |
|---|---|---|
owner | signer | |
allowance | writable | |
event_authority | PDA | |
program |
set_paused
The Pause button.
Arguments
pausedbool
Accounts
| Account | Flags | Notes |
|---|---|---|
owner | signer | |
allowance | writable | |
event_authority | PDA | |
program |
spend
Assistant pays within its rules.
Arguments
amountu64memo[u8; 32]
Accounts
| Account | Flags | Notes |
|---|---|---|
agent | signer | The assistant's session key. Only signs; a relayer can pay the fee. |
allowance | writable | |
mint | ||
vault | writable | |
destination | writable | |
payee_entry | optional | Required when the allowance restricts payees: the allowlist entry for the destination's owner. |
token_program | ||
event_authority | PDA | |
program |
update_rules
Arguments
rulesAllowanceRules
Accounts
| Account | Flags | Notes |
|---|---|---|
owner | signer | |
allowance | writable | |
event_authority | PDA | |
program |
withdraw
Arguments
amountu64
Accounts
| Account | Flags | Notes |
|---|---|---|
owner | signer | |
allowance | ||
mint | ||
vault | writable | |
destination | writable | |
token_program | ||
event_authority | PDA | |
program |
Accounts
Allowance
One allowance per (owner, assistant). Holds the rules and owns the USDC vault.
| Field | Type | Notes |
|---|---|---|
owner | Pubkey | |
agent | Pubkey | Session key the assistant signs with. Rotating it revokes the old key instantly. |
agent_id | [u8; 32] | Stable assistant id (e.g. sha256 of the runtime's agent id). PDA seed, so it survives session-key rotation. |
mint | Pubkey | |
vault | Pubkey | Associated token account of this PDA for `mint`. |
period_limit | u64 | |
period_seconds | i64 | |
period_start | i64 | |
spent_in_period | u64 | Autonomous spend so far this period. Owner-approved requests don't count. |
approval_threshold | u64 | |
restrict_payees | bool | |
paused | bool | The Pause button. Blocks all assistant actions; the owner can still act. |
request_count | u64 | Monotonic id for the next spend request. |
pending_requests | u32 | |
payee_count | u32 | Number of allowlist entries; must be zero to close. |
bump | u8 |
PayeeEntry
Presence of this PDA means `payee` is on the allowance's allowlist.
| Field | Type | Notes |
|---|---|---|
allowance | Pubkey | |
payee | Pubkey | Wallet (token account owner) allowed to receive payments. |
bump | u8 |
SpendRequest
A payment outside the rules, waiting for the owner ("Found a $274 flight. Book it?").
| Field | Type | Notes |
|---|---|---|
allowance | Pubkey | |
id | u64 | |
destination | Pubkey | Token account that receives the funds if approved. |
destination_owner | Pubkey | Owner of `destination` when the request was made: what the owner reviews. Approval fails if the account's owner has changed since. |
agent | Pubkey | Session key that made the request. Approval fails if it has been rotated out. |
amount | u64 | |
memo | [u8; 32] | |
payer | Pubkey | Who paid rent for this account; refunded on approve or cancel. |
created_at | i64 | |
bump | u8 |
Types
AllowanceRules
The rules an owner sets for an assistant. Shown to users as: "Spend up to $20 a week" / "Ask me before anything over $10" / "Only buy from these stores".
| Field | Type | Notes |
|---|---|---|
period_limit | u64 | Max the assistant may spend on its own per period, in mint base units. |
period_seconds | i64 | Period length in seconds (604_800 = one week). |
approval_threshold | u64 | Single payments above this need the owner's approval (a spend request). |
restrict_payees | bool | When true, the assistant may only pay wallets on the allowlist. |
Events
AgentChanged
| Field | Type | Notes |
|---|---|---|
allowance | Pubkey | |
old_agent | Pubkey | |
new_agent | Pubkey |
AllowanceClosed
| Field | Type | Notes |
|---|---|---|
allowance | Pubkey | |
returned_amount | u64 |
AllowanceCreated
| Field | Type | Notes |
|---|---|---|
allowance | Pubkey | |
owner | Pubkey | |
agent | Pubkey | |
agent_id | [u8; 32] | |
mint | Pubkey | |
vault | Pubkey |
PauseChanged
| Field | Type | Notes |
|---|---|---|
allowance | Pubkey | |
paused | bool |
PayeeAdded
| Field | Type | Notes |
|---|---|---|
allowance | Pubkey | |
payee | Pubkey |
PayeeRemoved
| Field | Type | Notes |
|---|---|---|
allowance | Pubkey | |
payee | Pubkey |
RequestCancelled
| Field | Type | Notes |
|---|---|---|
allowance | Pubkey | |
request_id | u64 | |
cancelled_by | Pubkey |
RulesUpdated
| Field | Type | Notes |
|---|---|---|
allowance | Pubkey | |
period_limit | u64 | |
period_seconds | i64 | |
approval_threshold | u64 | |
restrict_payees | bool |
SpendRequested
| Field | Type | Notes |
|---|---|---|
allowance | Pubkey | |
request_id | u64 | |
destination | Pubkey | |
destination_owner | Pubkey | Wallet that owns `destination`: what the owner should be shown. |
amount | u64 | |
memo | [u8; 32] |
Spent
Emitted for every payment out of the vault, whether the assistant spent within its rules (`request_id = None`) or the owner approved a request.
| Field | Type | Notes |
|---|---|---|
allowance | Pubkey | |
destination | Pubkey | |
amount | u64 | |
memo | [u8; 32] | Hash linking this payment to its off-chain receipt / purpose. |
request_id | Option<u64> | |
spent_in_period | u64 | |
period_start | i64 |
Withdrawn
| Field | Type | Notes |
|---|---|---|
allowance | Pubkey | |
destination | Pubkey | |
amount | u64 |
Errors
| Code | Name | Message |
|---|---|---|
6000 | Paused | This assistant is paused |
6001 | ZeroAmount | Amount must be greater than zero |
6002 | NeedsApproval | Amount is above the ask-first threshold; create a spend request instead |
6003 | OverPeriodLimit | Spend would exceed this period's allowance; create a spend request instead |
6004 | PayeeNotAllowed | Payee is not on this allowance's allowlist |
6005 | InvalidPeriod | Period length must be greater than zero seconds |
6006 | MintMismatch | Token account mint does not match the allowance mint |
6007 | DestinationIsVault | The vault cannot pay itself |
6008 | Unauthorized | Only the owner or the assistant can cancel a spend request |
6009 | PendingRequests | Resolve pending spend requests before closing the allowance |
6010 | PayeesRemaining | Remove all allowlisted payees before closing the allowance |
6011 | Overflow | Arithmetic overflow |
6012 | UnsupportedMint | Only classic SPL Token mints are supported (Token-2022 extensions could bypass the rules) |
6013 | DestinationOwnerChanged | The destination token account changed owner since the request was made |
6014 | StaleRequest | This request was made by a session key that has since been replaced; cancel it instead |
6015 | TooManyPendingRequests | Too many pending spend requests; approve or cancel some first |
neuron_receipts
One constant-size log per assistant. The runtime posts Merkle roots of receipt batches; each batch extends a hash chain, and the last 8 roots stay on chain for direct verification.
Program ID (localnet)2tMDBHGbzZ2WeDdErsoFANGkNJdrgxk26FQ7jvKSufmb
Instructions
close_log
Accounts
| Account | Flags | Notes |
|---|---|---|
owner | writable signer | |
log | writable |
create_log
Arguments
agent_id[u8; 32]authorityPubkey
Accounts
| Account | Flags | Notes |
|---|---|---|
owner | writable signer | |
log | writable | PDA |
system_program | fixed |
post_batch
Arguments
expected_batch_indexu64root[u8; 32]leaf_countu32first_ati64last_ati64data_hash[u8; 32]
Accounts
| Account | Flags | Notes |
|---|---|---|
authority | signer | Only signs; a relayer can pay the fee. |
log | writable |
set_authority
Arguments
authorityPubkey
Accounts
| Account | Flags | Notes |
|---|---|---|
owner | signer | |
log | writable |
verify_receipt
Arguments
batch_indexu64leaf[u8; 32]leaf_indexu32proofVec<[u8; 32]>
Accounts
| Account | Flags | Notes |
|---|---|---|
log |
Accounts
ReceiptLog
One per assistant. Constant size no matter how many receipts are posted: batches live on as events plus a hash chain, and only recent roots are kept.
| Field | Type | Notes |
|---|---|---|
owner | Pubkey | |
authority | Pubkey | Key allowed to post batches (the assistant's session key or its runtime). |
agent_id | [u8; 32] | Same stable id the allowance uses (e.g. sha256 of the runtime's agent id). |
batch_count | u64 | |
receipt_count | u64 | |
chain | [u8; 32] | Running hash over every batch ever posted (see `merkle::next_chain`). |
last_posted_at | i64 | |
recent | [RecentBatch; 8] | Ring buffer, slot = batch_index % RECENT_BATCHES. Literal length so the IDL can describe it; the assertion below keeps it in sync with the constant. |
bump | u8 |
Types
RecentBatch
| Field | Type | Notes |
|---|---|---|
batch_index | u64 | |
root | [u8; 32] | |
leaf_count | u32 | Zero means the slot is empty. |
Events
AuthorityChanged
| Field | Type | Notes |
|---|---|---|
log | Pubkey | |
old_authority | Pubkey | |
new_authority | Pubkey |
BatchPosted
One per batch. The full list of these is what an auditor replays to recompute `chain` and prove no batch was dropped or altered.
| Field | Type | Notes |
|---|---|---|
log | Pubkey | |
batch_index | u64 | |
root | [u8; 32] | |
leaf_count | u32 | |
first_at | i64 | |
last_at | i64 | |
data_hash | [u8; 32] | sha256 of the published batch file holding the full receipts. |
chain | [u8; 32] | Hash chain value after this batch. |
posted_at | i64 |
LogClosed
| Field | Type | Notes |
|---|---|---|
log | Pubkey | |
batch_count | u64 | |
receipt_count | u64 |
LogCreated
| Field | Type | Notes |
|---|---|---|
log | Pubkey | |
owner | Pubkey | |
authority | Pubkey | |
agent_id | [u8; 32] | |
genesis_chain | [u8; 32] | Where this log's hash chain starts (replay from here). |
created_slot | u64 |
Errors
| Code | Name | Message |
|---|---|---|
6000 | EmptyBatch | A batch must contain at least one receipt |
6001 | InvalidTimeRange | Batch time range is invalid (first_at must be <= last_at) |
6002 | BatchNotRecent | That batch is no longer among the recent on-chain roots; verify it off-chain against the hash chain |
6003 | InvalidProof | Merkle proof does not match the batch root |
6004 | Overflow | Arithmetic overflow |
6005 | UnexpectedBatchIndex | expected_batch_index does not match the log's next batch index (already posted, or another poster got there first) |
neuron_settlement
Records the Neuron rollup's checkpoints on Solana: forward-only, parent-linked and hash-chained. Recent state roots are verifiable on chain after a challenge window.
Program ID (localnet)GkewMsEjtawJfjikMb3EajZFgfSQdZpLXBxxVKTv3yqu
Instructions
accept_admin
Accounts
| Account | Flags | Notes |
|---|---|---|
new_admin | signer | |
rollup | writable |
initialize
Arguments
chain_idu64sequencerPubkeygenesis_blockhash[u8; 32]genesis_state_root[u8; 32]
Accounts
| Account | Flags | Notes |
|---|---|---|
admin | writable signer | |
rollup | writable | PDA |
program | fixed | |
program_data | ||
system_program | fixed |
invalidate_checkpoint
Arguments
slotu64
Accounts
| Account | Flags | Notes |
|---|---|---|
admin | signer | |
rollup | writable |
post_checkpoint
Arguments
slotu64blockhash[u8; 32]state_root[u8; 32]prev_blockhash[u8; 32]
Accounts
| Account | Flags | Notes |
|---|---|---|
sequencer | signer | |
rollup | writable |
propose_admin
Arguments
new_adminPubkey
Accounts
| Account | Flags | Notes |
|---|---|---|
admin | signer | |
rollup | writable |
rewind
Recovery from a bad checkpoint: requires `set_paused(true)` first.
Arguments
to_slotu64
Accounts
| Account | Flags | Notes |
|---|---|---|
admin | signer | |
rollup | writable |
set_challenge_period
Arguments
secondsi64
Accounts
| Account | Flags | Notes |
|---|---|---|
admin | signer | |
rollup | writable |
set_paused
Arguments
pausedbool
Accounts
| Account | Flags | Notes |
|---|---|---|
admin | signer | |
rollup | writable |
set_sequencer
Arguments
sequencerPubkey
Accounts
| Account | Flags | Notes |
|---|---|---|
admin | signer | |
rollup | writable |
verify_state_root
Arguments
slotu64state_root[u8; 32]
Accounts
| Account | Flags | Notes |
|---|---|---|
rollup |
Accounts
RollupState
One per rollup. FIELD ORDER IS AN INTERFACE: the sequencer node reads raw byte offsets (admin 8..40, sequencer 40..72, chain_id 72..80, genesis_blockhash 80..112, latest_slot 112..120, latest_blockhash 120..152, latest_state_root 152..184, checkpoint_count 184..192, chain 192..224, last_posted_at 224..232, paused 232). Only ever append new fields after `bump`.
| Field | Type | Notes |
|---|---|---|
admin | Pubkey | |
sequencer | Pubkey | The only key allowed to post checkpoints. |
chain_id | u64 | |
genesis_blockhash | [u8; 32] | |
latest_slot | u64 | |
latest_blockhash | [u8; 32] | |
latest_state_root | [u8; 32] | |
checkpoint_count | u64 | |
chain | [u8; 32] | Hash chain over every checkpoint (and rewind) ever recorded. |
last_posted_at | i64 | |
paused | bool | |
recent | [Checkpoint; 8] | Ring buffer, slot = checkpoint index % RECENT_CHECKPOINTS. Literal length so the IDL can describe it; the assertion below keeps it in sync. |
bump | u8 | |
challenge_period | i64 | Seconds a checkpoint must age before `verify_state_root` accepts it. |
pending_admin | Pubkey | Proposed new admin (two-step handover); default = none. |
Types
Checkpoint
| Field | Type | Notes |
|---|---|---|
slot | u64 | |
blockhash | [u8; 32] | |
state_root | [u8; 32] | |
posted_at | i64 | |
invalidated | bool | Set by the admin (invalidate or rewind): no longer verifiable. |
Events
AdminChanged
| Field | Type | Notes |
|---|---|---|
rollup | Pubkey | |
old_admin | Pubkey | |
new_admin | Pubkey |
AdminProposed
| Field | Type | Notes |
|---|---|---|
rollup | Pubkey | |
proposed_admin | Pubkey |
ChallengePeriodChanged
| Field | Type | Notes |
|---|---|---|
rollup | Pubkey | |
challenge_period | i64 |
CheckpointInvalidated
A recent checkpoint was marked unusable (e.g. a bad state root).
| Field | Type | Notes |
|---|---|---|
rollup | Pubkey | |
slot | u64 |
CheckpointPosted
One per checkpoint. Replaying these from genesis must reproduce `RollupState::chain`.
| Field | Type | Notes |
|---|---|---|
rollup | Pubkey | |
index | u64 | |
slot | u64 | |
blockhash | [u8; 32] | |
state_root | [u8; 32] | |
prev_blockhash | [u8; 32] | |
chain | [u8; 32] | |
posted_at | i64 |
PauseChanged
| Field | Type | Notes |
|---|---|---|
rollup | Pubkey | |
paused | bool |
Rewound
Settlement was rewound to a known-good checkpoint; later ones were invalidated. Replays fold this in with `rewind_chain`.
| Field | Type | Notes |
|---|---|---|
rollup | Pubkey | |
to_slot | u64 | |
blockhash | [u8; 32] | |
state_root | [u8; 32] | |
chain | [u8; 32] |
RollupInitialized
| Field | Type | Notes |
|---|---|---|
rollup | Pubkey | |
chain_id | u64 | |
admin | Pubkey | |
sequencer | Pubkey | |
genesis_blockhash | [u8; 32] | |
genesis_state_root | [u8; 32] |
SequencerChanged
| Field | Type | Notes |
|---|---|---|
rollup | Pubkey | |
old_sequencer | Pubkey | |
new_sequencer | Pubkey |
Errors
| Code | Name | Message |
|---|---|---|
6000 | Paused | Checkpoints are paused by the admin |
6001 | SlotNotIncreasing | Checkpoint slot must be greater than the latest checkpoint's slot |
6002 | WrongParent | prev_blockhash does not match the latest checkpoint's blockhash |
6003 | UnknownCheckpoint | No valid recent checkpoint has that slot and state root |
6004 | SlotGapTooLarge | Checkpoint slot is too far ahead of the latest checkpoint |
6005 | ChallengeWindowOpen | That checkpoint is still inside its challenge window |
6006 | NotUpgradeAuthority | Only the program's upgrade authority can initialize a rollup |
6007 | NotPendingAdmin | Signer is not the proposed admin |
6008 | InvalidChallengePeriod | Challenge period must be zero or positive |
6009 | MustBePaused | Rewinding requires checkpoints to be paused first |