@helmmasters/agentvault-sdk

TypeScript SDK for Helm — programmable agent multisig on Solana.

Build AI agents that spend within on-chain policy. The vault enforces USD caps via Pyth oracles. The agent can never exceed them, no matter what its prompt says.

Install

npm install @helmmasters/agentvault-sdk @solana/web3.js

Quick start — propose a transaction as an agent

import { Connection, Keypair, Transaction, PublicKey, sendAndConfirmTransaction } from "@solana/web3.js";
import {
  proposeTransactionIx,
  derivePolicyPda,
  derivePendingPda,
  decodeVault,
  decodePolicy,
  SYSTEM_PROGRAM_ID,
} from "@helmmasters/agentvault-sdk";

const conn = new Connection("https://api.mainnet-beta.solana.com");
const VAULT = new PublicKey("AQt7LFqpfQ5qaNTTwQi88xKScAdknWbC4tJVBeh18cPS");
const agent = Keypair.fromSecretKey(/* your agent keypair bytes */);

const vault = decodeVault(Buffer.from((await conn.getAccountInfo(VAULT))!.data));
const policyPda = derivePolicyPda(VAULT);
const policy = decodePolicy(Buffer.from((await conn.getAccountInfo(policyPda))!.data));
const pendingPda = derivePendingPda(VAULT, vault.nonce);

// Build a SystemProgram.transfer instruction the vault will execute
const recipient = Keypair.generate().publicKey;
const transferData = Buffer.alloc(12);
transferData.writeUInt32LE(2, 0);              // SystemInstruction::Transfer
transferData.writeBigUInt64LE(100_000n, 4);    // lamports

const ix = proposeTransactionIx({
  agent: agent.publicKey,
  vaultPda: VAULT,
  policyPda,
  pythFeed: policy.pythFeedForCaps,
  args: {
    targetProgram: SYSTEM_PROGRAM_ID,
    instructionData: transferData,
    accounts: [
      { pubkey: VAULT, isSigner: true, isWritable: true },
      { pubkey: recipient, isSigner: false, isWritable: true },
    ],
    touchedMints: [],
    rawAmount: 100_000n,
    amountDecimals: 9,
  },
  pendingPda,
});

const sig = await sendAndConfirmTransaction(conn, new Transaction().add(ix), [agent]);
console.log("Proposed:", sig);

The vault decides what happens next:

• Under the instant cap → executes immediately
• Above the instant cap, below the delayed cap → creates a pending tx for the guardian
• Above all caps → rejected by the program

What's in the SDK

• Instruction builders for every Helm program instruction: initializeVaultIx, proposeTransactionIx, approveTransactionIx, vetoTransactionIx, executeTransactionIx, closePendingIx, suspendVaultIx, resumeVaultIx, updatePolicyIx, commitPolicyUpdateIx
• PDA helpers: deriveVaultPda, derivePolicyPda, derivePendingPda
• Account decoders: decodeVault, decodePolicy, decodePendingTransaction (with TypeScript types)
• Encoding utilities: Pyth price feed v1/v2 byte builders for testing
• Constants: PROGRAM_ID (mainnet), SYSTEM_PROGRAM_ID, Pyth feed IDs

Custom deployments

Every builder accepts programId as an optional override for custom devnet/local deployments:

import { PublicKey } from "@solana/web3.js";
const MY_DEPLOYMENT = new PublicKey("...");

const policyPda = derivePolicyPda(vaultPubkey, MY_DEPLOYMENT);
const ix = proposeTransactionIx({ ..., programId: MY_DEPLOYMENT });

Links

• App: app.helmagent.xyz
• Site: helmagent.xyz
• Code: github.com/HelmMasters/agentvault
• Bot: @HelmProtocolBot

License

Apache-2.0