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.

Signers. Instructions marked signer need that key's signature. The fee payer can be anyone (a relayer), which is how assistant session keys never need SOL. In 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

  • payee Pubkey

Accounts

AccountFlagsNotes
ownerwritable signer
allowancewritable
payee_entrywritablePDA
system_programfixed
event_authorityPDA
program

approve_request

Accounts

AccountFlagsNotes
ownersigner
allowancewritable
requestwritable
mint
vaultwritable
destinationwritableMust still belong to the wallet the owner was shown when the request was made.
rent_refundwritable
token_program
event_authorityPDA
program

cancel_request

Accounts

AccountFlagsNotes
signersigner
allowancewritable
requestwritable
rent_refundwritable
event_authorityPDA
program

close_allowance

Fire the assistant: return the balance and close everything.

Accounts

AccountFlagsNotes
ownerwritable signer
allowancewritable
mint
vaultwritable
destinationwritableReceives whatever is left in the vault.
token_program
event_authorityPDA
program

create_allowance

Owner creates an allowance and its vault for one assistant.

Arguments

  • agent_id [u8; 32]
  • agent Pubkey
  • rules AllowanceRules

Accounts

AccountFlagsNotes
ownerwritable signer
allowancewritablePDA
mintClassic 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.
vaultwritable`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_programfixed
system_programfixed
event_authorityPDA
program

remove_payee

Accounts

AccountFlagsNotes
ownerwritable signer
allowancewritable
payee_entrywritable
event_authorityPDA
program

request_spend

Assistant asks the owner for a payment outside its rules.

Arguments

  • amount u64
  • memo [u8; 32]

Accounts

AccountFlagsNotes
agentsigner
payerwritable signerPays rent for the request account (the assistant or a relayer).
allowancewritable
destination
requestwritablePDA
system_programfixed
event_authorityPDA
program

set_agent

Arguments

  • agent Pubkey

Accounts

AccountFlagsNotes
ownersigner
allowancewritable
event_authorityPDA
program

set_paused

The Pause button.

Arguments

  • paused bool

Accounts

AccountFlagsNotes
ownersigner
allowancewritable
event_authorityPDA
program

spend

Assistant pays within its rules.

Arguments

  • amount u64
  • memo [u8; 32]

Accounts

AccountFlagsNotes
agentsignerThe assistant's session key. Only signs; a relayer can pay the fee.
allowancewritable
mint
vaultwritable
destinationwritable
payee_entryoptionalRequired when the allowance restricts payees: the allowlist entry for the destination's owner.
token_program
event_authorityPDA
program

update_rules

Arguments

  • rules AllowanceRules

Accounts

AccountFlagsNotes
ownersigner
allowancewritable
event_authorityPDA
program

withdraw

Arguments

  • amount u64

Accounts

AccountFlagsNotes
ownersigner
allowance
mint
vaultwritable
destinationwritable
token_program
event_authorityPDA
program

Accounts

Allowance

One allowance per (owner, assistant). Holds the rules and owns the USDC vault.

FieldTypeNotes
ownerPubkey
agentPubkeySession 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.
mintPubkey
vaultPubkeyAssociated token account of this PDA for `mint`.
period_limitu64
period_secondsi64
period_starti64
spent_in_periodu64Autonomous spend so far this period. Owner-approved requests don't count.
approval_thresholdu64
restrict_payeesbool
pausedboolThe Pause button. Blocks all assistant actions; the owner can still act.
request_countu64Monotonic id for the next spend request.
pending_requestsu32
payee_countu32Number of allowlist entries; must be zero to close.
bumpu8

PayeeEntry

Presence of this PDA means `payee` is on the allowance's allowlist.

FieldTypeNotes
allowancePubkey
payeePubkeyWallet (token account owner) allowed to receive payments.
bumpu8

SpendRequest

A payment outside the rules, waiting for the owner ("Found a $274 flight. Book it?").

FieldTypeNotes
allowancePubkey
idu64
destinationPubkeyToken account that receives the funds if approved.
destination_ownerPubkeyOwner of `destination` when the request was made: what the owner reviews. Approval fails if the account's owner has changed since.
agentPubkeySession key that made the request. Approval fails if it has been rotated out.
amountu64
memo[u8; 32]
payerPubkeyWho paid rent for this account; refunded on approve or cancel.
created_ati64
bumpu8

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".

FieldTypeNotes
period_limitu64Max the assistant may spend on its own per period, in mint base units.
period_secondsi64Period length in seconds (604_800 = one week).
approval_thresholdu64Single payments above this need the owner's approval (a spend request).
restrict_payeesboolWhen true, the assistant may only pay wallets on the allowlist.

Events

AgentChanged

FieldTypeNotes
allowancePubkey
old_agentPubkey
new_agentPubkey

AllowanceClosed

FieldTypeNotes
allowancePubkey
returned_amountu64

AllowanceCreated

FieldTypeNotes
allowancePubkey
ownerPubkey
agentPubkey
agent_id[u8; 32]
mintPubkey
vaultPubkey

PauseChanged

FieldTypeNotes
allowancePubkey
pausedbool

PayeeAdded

FieldTypeNotes
allowancePubkey
payeePubkey

PayeeRemoved

FieldTypeNotes
allowancePubkey
payeePubkey

RequestCancelled

FieldTypeNotes
allowancePubkey
request_idu64
cancelled_byPubkey

RulesUpdated

FieldTypeNotes
allowancePubkey
period_limitu64
period_secondsi64
approval_thresholdu64
restrict_payeesbool

SpendRequested

FieldTypeNotes
allowancePubkey
request_idu64
destinationPubkey
destination_ownerPubkeyWallet that owns `destination`: what the owner should be shown.
amountu64
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.

FieldTypeNotes
allowancePubkey
destinationPubkey
amountu64
memo[u8; 32]Hash linking this payment to its off-chain receipt / purpose.
request_idOption<u64>
spent_in_periodu64
period_starti64

Withdrawn

FieldTypeNotes
allowancePubkey
destinationPubkey
amountu64

Errors

CodeNameMessage
6000PausedThis assistant is paused
6001ZeroAmountAmount must be greater than zero
6002NeedsApprovalAmount is above the ask-first threshold; create a spend request instead
6003OverPeriodLimitSpend would exceed this period's allowance; create a spend request instead
6004PayeeNotAllowedPayee is not on this allowance's allowlist
6005InvalidPeriodPeriod length must be greater than zero seconds
6006MintMismatchToken account mint does not match the allowance mint
6007DestinationIsVaultThe vault cannot pay itself
6008UnauthorizedOnly the owner or the assistant can cancel a spend request
6009PendingRequestsResolve pending spend requests before closing the allowance
6010PayeesRemainingRemove all allowlisted payees before closing the allowance
6011OverflowArithmetic overflow
6012UnsupportedMintOnly classic SPL Token mints are supported (Token-2022 extensions could bypass the rules)
6013DestinationOwnerChangedThe destination token account changed owner since the request was made
6014StaleRequestThis request was made by a session key that has since been replaced; cancel it instead
6015TooManyPendingRequestsToo 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

AccountFlagsNotes
ownerwritable signer
logwritable

create_log

Arguments

  • agent_id [u8; 32]
  • authority Pubkey

Accounts

AccountFlagsNotes
ownerwritable signer
logwritablePDA
system_programfixed

post_batch

Arguments

  • expected_batch_index u64
  • root [u8; 32]
  • leaf_count u32
  • first_at i64
  • last_at i64
  • data_hash [u8; 32]

Accounts

AccountFlagsNotes
authoritysignerOnly signs; a relayer can pay the fee.
logwritable

set_authority

Arguments

  • authority Pubkey

Accounts

AccountFlagsNotes
ownersigner
logwritable

verify_receipt

Arguments

  • batch_index u64
  • leaf [u8; 32]
  • leaf_index u32
  • proof Vec<[u8; 32]>

Accounts

AccountFlagsNotes
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.

FieldTypeNotes
ownerPubkey
authorityPubkeyKey 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_countu64
receipt_countu64
chain[u8; 32]Running hash over every batch ever posted (see `merkle::next_chain`).
last_posted_ati64
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.
bumpu8

Types

RecentBatch

FieldTypeNotes
batch_indexu64
root[u8; 32]
leaf_countu32Zero means the slot is empty.

Events

AuthorityChanged

FieldTypeNotes
logPubkey
old_authorityPubkey
new_authorityPubkey

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.

FieldTypeNotes
logPubkey
batch_indexu64
root[u8; 32]
leaf_countu32
first_ati64
last_ati64
data_hash[u8; 32]sha256 of the published batch file holding the full receipts.
chain[u8; 32]Hash chain value after this batch.
posted_ati64

LogClosed

FieldTypeNotes
logPubkey
batch_countu64
receipt_countu64

LogCreated

FieldTypeNotes
logPubkey
ownerPubkey
authorityPubkey
agent_id[u8; 32]
genesis_chain[u8; 32]Where this log's hash chain starts (replay from here).
created_slotu64

Errors

CodeNameMessage
6000EmptyBatchA batch must contain at least one receipt
6001InvalidTimeRangeBatch time range is invalid (first_at must be <= last_at)
6002BatchNotRecentThat batch is no longer among the recent on-chain roots; verify it off-chain against the hash chain
6003InvalidProofMerkle proof does not match the batch root
6004OverflowArithmetic overflow
6005UnexpectedBatchIndexexpected_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

AccountFlagsNotes
new_adminsigner
rollupwritable

initialize

Arguments

  • chain_id u64
  • sequencer Pubkey
  • genesis_blockhash [u8; 32]
  • genesis_state_root [u8; 32]

Accounts

AccountFlagsNotes
adminwritable signer
rollupwritablePDA
programfixed
program_data
system_programfixed

invalidate_checkpoint

Arguments

  • slot u64

Accounts

AccountFlagsNotes
adminsigner
rollupwritable

post_checkpoint

Arguments

  • slot u64
  • blockhash [u8; 32]
  • state_root [u8; 32]
  • prev_blockhash [u8; 32]

Accounts

AccountFlagsNotes
sequencersigner
rollupwritable

propose_admin

Arguments

  • new_admin Pubkey

Accounts

AccountFlagsNotes
adminsigner
rollupwritable

rewind

Recovery from a bad checkpoint: requires `set_paused(true)` first.

Arguments

  • to_slot u64

Accounts

AccountFlagsNotes
adminsigner
rollupwritable

set_challenge_period

Arguments

  • seconds i64

Accounts

AccountFlagsNotes
adminsigner
rollupwritable

set_paused

Arguments

  • paused bool

Accounts

AccountFlagsNotes
adminsigner
rollupwritable

set_sequencer

Arguments

  • sequencer Pubkey

Accounts

AccountFlagsNotes
adminsigner
rollupwritable

verify_state_root

Arguments

  • slot u64
  • state_root [u8; 32]

Accounts

AccountFlagsNotes
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`.

FieldTypeNotes
adminPubkey
sequencerPubkeyThe only key allowed to post checkpoints.
chain_idu64
genesis_blockhash[u8; 32]
latest_slotu64
latest_blockhash[u8; 32]
latest_state_root[u8; 32]
checkpoint_countu64
chain[u8; 32]Hash chain over every checkpoint (and rewind) ever recorded.
last_posted_ati64
pausedbool
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.
bumpu8
challenge_periodi64Seconds a checkpoint must age before `verify_state_root` accepts it.
pending_adminPubkeyProposed new admin (two-step handover); default = none.

Types

Checkpoint

FieldTypeNotes
slotu64
blockhash[u8; 32]
state_root[u8; 32]
posted_ati64
invalidatedboolSet by the admin (invalidate or rewind): no longer verifiable.

Events

AdminChanged

FieldTypeNotes
rollupPubkey
old_adminPubkey
new_adminPubkey

AdminProposed

FieldTypeNotes
rollupPubkey
proposed_adminPubkey

ChallengePeriodChanged

FieldTypeNotes
rollupPubkey
challenge_periodi64

CheckpointInvalidated

A recent checkpoint was marked unusable (e.g. a bad state root).

FieldTypeNotes
rollupPubkey
slotu64

CheckpointPosted

One per checkpoint. Replaying these from genesis must reproduce `RollupState::chain`.

FieldTypeNotes
rollupPubkey
indexu64
slotu64
blockhash[u8; 32]
state_root[u8; 32]
prev_blockhash[u8; 32]
chain[u8; 32]
posted_ati64

PauseChanged

FieldTypeNotes
rollupPubkey
pausedbool

Rewound

Settlement was rewound to a known-good checkpoint; later ones were invalidated. Replays fold this in with `rewind_chain`.

FieldTypeNotes
rollupPubkey
to_slotu64
blockhash[u8; 32]
state_root[u8; 32]
chain[u8; 32]

RollupInitialized

FieldTypeNotes
rollupPubkey
chain_idu64
adminPubkey
sequencerPubkey
genesis_blockhash[u8; 32]
genesis_state_root[u8; 32]

SequencerChanged

FieldTypeNotes
rollupPubkey
old_sequencerPubkey
new_sequencerPubkey

Errors

CodeNameMessage
6000PausedCheckpoints are paused by the admin
6001SlotNotIncreasingCheckpoint slot must be greater than the latest checkpoint's slot
6002WrongParentprev_blockhash does not match the latest checkpoint's blockhash
6003UnknownCheckpointNo valid recent checkpoint has that slot and state root
6004SlotGapTooLargeCheckpoint slot is too far ahead of the latest checkpoint
6005ChallengeWindowOpenThat checkpoint is still inside its challenge window
6006NotUpgradeAuthorityOnly the program's upgrade authority can initialize a rollup
6007NotPendingAdminSigner is not the proposed admin
6008InvalidChallengePeriodChallenge period must be zero or positive
6009MustBePausedRewinding requires checkpoints to be paused first