Operations

Operator roles, external liveness, health scores, snapshots, activity logs, and policy history.

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.

grantOperatorRole / revokeOperatorRole

Delegate specific permissions to an operator without giving them full owner access. Operators can drive the execution lifecycle, refresh liveness, manage address lists, and take snapshots.

// Grant
await client.grantOperatorRole(owner, accounts, args);

// Revoke
await client.revokeOperatorRole(owner, accounts, now);

interface GrantOperatorRoleAccounts {
  owner: PublicKey;
  treasury: PublicKey;
  operator: PublicKey;    // the operator receiving permissions
  operatorRole: PublicKey;  // PDA: deriveOperatorRoleAddress(treasury, operator)
  systemProgram: PublicKey;
}

interface RevokeOperatorRoleAccounts {
  owner: PublicKey;
  treasury: PublicKey;
  operatorRole: PublicKey;
}

import { deriveOperatorRoleAddress } from '@aura-protocol/sdk-ts';
import BN from 'bn.js';

const [operatorRole] = deriveOperatorRoleAddress(treasury, operator.publicKey);

await client.grantOperatorRole(
  owner,
  {
    owner: owner.publicKey,
    treasury,
    operator: operator.publicKey,
    operatorRole,
    systemProgram: SystemProgram.programId,
  },
  {
    permissionsBitmap: 0b0000_0111,  // execution + liveness + snapshots
    expiresAt: new BN(Math.floor(Date.now() / 1000) + 86400 * 30),  // 30 days
    timestamp: new BN(Math.floor(Date.now() / 1000)),
  },
);

initExternalLiveness / refreshExternalLiveness

Track freshness of external dependencies (Encrypt network, dWallet network, balance oracle, compliance oracle). Required when LivenessConfig.require_*_freshness flags are set on the treasury.

// Init — creates the liveness PDA
await client.initExternalLiveness(owner, accounts, args);

// Refresh — updates the timestamp
await client.refreshExternalLiveness(operator, accounts, args);

interface InitExternalLivenessAccounts {
  owner: PublicKey;
  treasury: PublicKey;
  liveness: PublicKey;  // PDA: deriveExternalLivenessAddress(treasury)
  systemProgram: PublicKey;
}

interface RefreshExternalLivenessAccounts {
  operator: PublicKey;
  treasury: PublicKey;
  operatorRole?: PublicKey | null;
  liveness: PublicKey;
}

import { deriveExternalLivenessAddress } from '@aura-protocol/sdk-ts';
import BN from 'bn.js';

const [liveness] = deriveExternalLivenessAddress(treasury);

// Init once
await client.initExternalLiveness(
  owner,
  { owner: owner.publicKey, treasury, liveness, systemProgram: SystemProgram.programId },
  { dependencyFlags: 0b0011, timestamp: new BN(Math.floor(Date.now() / 1000)) },
);

// Refresh periodically
await client.refreshExternalLiveness(
  operator,
  { operator: operator.publicKey, treasury, operatorRole: null, liveness },
  { dependencyFlags: 0b0011, timestamp: new BN(Math.floor(Date.now() / 1000)) },
);

configureLivenessGuardrails

Update the LivenessConfig on the treasury to require freshness checks for specific external dependencies.

await client.configureLivenessGuardrails(owner, accounts, args);

await client.configureLivenessGuardrails(
  owner,
  { owner: owner.publicKey, treasury },
  {
    requireEncryptFreshness: true,
    requireDwalletFreshness: true,
    requireBalanceOracleFreshness: false,
    requireComplianceOracleFreshness: false,
    maxStalenessSecs: new BN(300),
    timestamp: new BN(Math.floor(Date.now() / 1000)),
  },
);

initHealthScore / refreshHealthScore / closeHealthScore

Compute and store a u8 health score (0–100) for the treasury. Used by takeSnapshot.

// Init
await client.initHealthScore(owner, accounts, now);

// Refresh
await client.refreshHealthScore(operator, accounts, now);

// Close (reclaim rent)
await client.closeHealthScore(owner, accounts);

interface InitHealthScoreAccounts {
  owner: PublicKey;
  treasury: PublicKey;
  healthScore: PublicKey;  // PDA — derived on-chain
  systemProgram: PublicKey;
}

interface RefreshHealthScoreAccounts {
  operator: PublicKey;
  treasury: PublicKey;
  operatorRole?: PublicKey | null;
  healthScore: PublicKey;
}

takeSnapshot

Record a point-in-time snapshot of the treasury's health score and key metrics.

await client.takeSnapshot(payer, accounts, snapshotIndex, now);

interface TakeSnapshotAccounts {
  payer: PublicKey;
  treasury: PublicKey;
  operatorRole?: PublicKey | null;
  healthScore: PublicKey;
  snapshot: PublicKey;  // PDA — derived on-chain
  systemProgram: PublicKey;
}

await client.takeSnapshot(
  payer,
  {
    payer: payer.publicKey,
    treasury,
    operatorRole: null,
    healthScore: healthScorePDA,
    snapshot: snapshotPDA,
    systemProgram: SystemProgram.programId,
  },
  0,  // snapshotIndex — slot in the ring buffer
  Math.floor(Date.now() / 1000),
);

initActivityLog / closeActivityLog

Initialize or close the activity log ring buffer for a treasury.

await client.initActivityLog(owner, accounts);
await client.closeActivityLog(owner, accounts);

interface InitActivityLogAccounts {
  owner: PublicKey;
  treasury: PublicKey;
  activityLog: PublicKey;  // PDA — derived on-chain
  systemProgram: PublicKey;
}

initPolicyHistory / recordPolicySnapshot / closePolicyHistory

Manage the policy history ring buffer — stores a rolling record of policy configuration changes.

// Init
await client.initPolicyHistory(owner, accounts);

// Record current policy as a snapshot
await client.recordPolicySnapshot(owner, accounts, now);

// Close (reclaim rent)
await client.closePolicyHistory(owner, accounts);

interface InitPolicyHistoryAccounts {
  owner: PublicKey;
  treasury: PublicKey;
  policyHistory: PublicKey;  // PDA — derived on-chain
  systemProgram: PublicKey;
}

Lifecycle

Session keys, dead man's switch, and treasury migration.

Budget

Budget envelopes and exposure groups.