Accounts & Fetching

Pre-alpha — not production ready

@aura-protocol/sdk-ts targets Solana devnet only. APIs may change without notice. Do not use for real funds until a stable release and audit are published.

AuraClient provides three methods for fetching treasury accounts. All return typed TreasuryAccountRecord objects deserialized from the Anchor IDL.

Fetching Methods

getTreasuryAccount

Fetch by PDA. Throws if the account does not exist on-chain.

async getTreasuryAccount(treasury: PublicKey): Promise<TreasuryAccountRecord>

const account = await client.getTreasuryAccount(treasuryPDA);
console.log('Agent ID:', account.agentId);
console.log('Is paused:', account.executionPaused);

getTreasuryAccountNullable

Fetch by PDA, returning null if the account doesn't exist.

async getTreasuryAccountNullable(treasury: PublicKey): Promise<TreasuryAccountRecord | null>

const account = await client.getTreasuryAccountNullable(treasuryPDA);
if (!account) {
  console.log('Treasury not yet created');
}

getTreasuryForOwner

Derive the PDA from owner + agentId and fetch in one call. Returns account: null if the treasury has not been created yet.

async getTreasuryForOwner(
  owner: PublicKey,
  agentId: string,
): Promise<{ treasury: PublicKey; account: TreasuryAccountRecord | null }>

const { treasury, account } = await client.getTreasuryForOwner(
  ownerPublicKey,
  'agent-prod-1',
);
if (account) {
  console.log('Daily limit:', account.policyConfig.dailyLimitUsd.toString());
}

Account Types

TreasuryAccountRecord

The root on-chain account for an AI agent treasury.

interface TreasuryAccountRecord {
  schemaVersion: number;
  bump: number;
  owner: PublicKey;
  aiAuthority: PublicKey;
  agentId: string;
  createdAt: BN;
  updatedAt: BN;
  nextProposalId: BN;
  totalTransactions: BN;
  executionPaused: boolean;
  agentState: number;
  pendingTransactionTtlSecs: BN;
  currentPolicyVersion: number;
  policyConfig: PolicyConfigRecord;
  policyState: PolicyStateRecord;
  confidentialGuardrails: ConfidentialGuardrailsRecord | null;
  pendingAiRotation: PendingAiRotationRecord | null;
  pendingConfigChange: PendingConfigChangeRecord | null;
  circuitBreaker: CircuitBreakerRecord;
  lastOwnerActivityAt: BN;
  deadMansSwitch: DeadMansSwitchRecord | null;
  highRiskThreshold: number;
  highRiskRequireGuardian: boolean;
  lastLargeTxAt: BN | null;
  lastLargeTxAmountUsd: BN;
  parentTreasury: string | null;
  childAgents: string[];
  childSpendBudgetUsd: BN | null;
  sanctionsCheckEnabled: boolean;
  complianceOracle: PublicKey | null;
  shutdownInitiatedAt: BN | null;
  shutdownRecoveryPubkey: PublicKey | null;
  lastSnapshotAt: BN | null;
  reputation: AgentReputationRecord;
  fees: ProtocolFeesRecord;
  dwallets: DWalletRecord[];
  pendingQueue: PendingProposalRecord[];
  multisig: MultisigConfigRecord | null;
  swarm: SwarmConfigRecord | null;
}

PolicyConfigRecord

All policy rules for a treasury.

interface PolicyConfigRecord {
  dailyLimitUsd: BN;
  perTxLimitUsd: BN;
  daytimeHourlyLimitUsd: BN;
  nighttimeHourlyLimitUsd: BN;
  velocityLimitUsd: BN;
  allowedProtocolBitmap: BN;
  maxSlippageBps: BN;
  maxQuoteAgeSecs: BN | null;
  maxCounterpartyRiskScore: number | null;
  bitcoinManualReviewThresholdUsd: BN;
  sharedPoolLimitUsd: BN | null;
  weeklyLimitUsd: BN | null;
  monthlyLimitUsd: BN | null;
  recipientLimits: RecipientLimitRecord[];
  cooldownConfig: CooldownConfigRecord | null;
  anomalyConfig: AnomalyConfigRecord | null;
  reputationPolicy: ReputationPolicyRecord;
  budgetEnvelopes: BudgetEnvelopeRecord[];
  approvalLadder: ApprovalLadderRecord | null;
  scopedPauseEntries: ScopedPauseEntryRecord[];
  livenessConfig: LivenessConfigRecord;
}

PolicyStateRecord

Current execution and spending counters — updated every time a proposal is submitted or finalized.

interface PolicyStateRecord {
  spentTodayUsd: BN;
  lastResetTimestamp: BN;
  hourlySpentUsd: BN;
  hourlyBucketStartedAt: BN;
  recentAmounts: BN[];
  dailyBuckets: BN[];        // 7-element ring buffer
  dailyBucketHead: number;
  sevenDayWindowStartedAt: BN;
  thirtyDaySpentUsd: BN;
  thirtyDayWindowStartedAt: BN;
  peakSingleTxUsd: BN;
  peakDaySpendUsd: BN;
  recipientSpend: RecipientSpendRecord[];  // per-address spend tracking
}

PendingProposalRecord

A proposal queued for execution or policy evaluation. Stored in account.pendingQueue (a Vec).

interface PendingProposalRecord {
  proposalId: BN;
  proposalDigest: string;
  policyGraphName: string;
  policyOutputDigest: string;
  policyOutputCiphertextAccount: string | null;
  policyOutputFheType: number | null;
  targetChain: number;
  txType: number;
  amountUsd: BN;
  recipientOrContract: string;
  protocolId: number | null;
  submittedAt: BN;
  expiresAt: BN;
  lastUpdatedAt: BN;
  executionAttempts: number;
  status: number;            // 0=Pending, 1=Approved, 2=Denied, 3=Cancelled, 4=Expired
  decision: PolicyDecisionRecord;
  riskScore: number;
  requiredApprovalLevel: number;
  satisfiedApprovalLevel: number;
  earliestExecutionAt: BN;
  requiresGuardianCosign: boolean;
  policyVersion: number;
}

const account = await client.getTreasuryAccount(treasury);

// Most recent pending proposal (queue is ordered by submission time)
const pending = account.pendingQueue[account.pendingQueue.length - 1];
if (pending) {
  console.log('Proposal ID:', pending.proposalId.toString());
  console.log('Amount USD:', pending.amountUsd.toString());
  console.log('Expires:', new Date(pending.expiresAt.toNumber() * 1000));
  console.log('Status:', pending.status);
}

DWalletRecord

A registered dWallet reference on the treasury.

interface DWalletRecord {
  chain: number;
  dwalletId: string;
  address: string;
  balanceUsd: BN;
  balanceUpdatedAt: BN;
  balanceOracle: PublicKey | null;
  dwalletAccount: PublicKey | null;
  authorizedUserPubkey: PublicKey | null;
  messageMetadataDigest: string | null;
  publicKeyHex: string | null;
  curve: number;
  signatureScheme: number;
}

MultisigConfigRecord

Emergency guardian multisig configuration, when set.

interface MultisigConfigRecord {
  requiredSignatures: number;
  guardians: PublicKey[];
  pendingOverride: PendingOverrideRecord | null;
  pendingGuardianChange: PendingGuardianChangeRecord | null;
}

SwarmConfigRecord

Shared agent swarm configuration, when set.

interface SwarmConfigRecord {
  swarmId: string;
  memberAgents: string[];
  sharedPoolLimitUsd: BN;
  totalSwarmSpentUsd: BN;
}

Working with BN Values

All on-chain numeric fields use BN from bn.js. Use .toString() for display and .toNumber() only for values you know fit in a JS number.

const daily = account.policyConfig.dailyLimitUsd;

console.log(daily.toString());   // "10000"
console.log(daily.toNumber());   // 10000

// Arithmetic stays in BN
const remaining = daily.sub(account.policyState.spentTodayUsd);
console.log('Remaining:', remaining.toString());

A note on account type definitions

All account types (TreasuryAccountRecord, PolicyConfigRecord, etc.) are IDL-derived via IdlAccounts<AuraCore> and IdlTypes<AuraCore>. The interfaces shown on this page are accurate approximations based on the current IDL, but the canonical source of truth is the generated packages/sdk-ts/src/generated/aura_core.ts. If a field type looks wrong at runtime, check the generated types directly.