Blockchain & On-Chain Agents Basics

mkdir onchain-agent-basics && cd onchain-agent-basics
npm init -y
npm install @solana/web3.js bs58 zod
export SOLANA_CLUSTER_URL="https://api.devnet.solana.com"
# DEVNET only. Do not put mainnet keys here.
export AGENT_PAYER_SECRET_BASE58="..."

node -e "const {Keypair}=require('@solana/web3.js'); const k=Keypair.generate(); console.log(require('bs58').encode(k.secretKey)); console.log(k.publicKey.toBase58());"

import { Connection, clusterApiUrl } from "@solana/web3.js";
 
const cluster = process.env.SOLANA_CLUSTER ?? "devnet";
if (cluster !== "devnet") {
  throw new Error(`Refusing to run basics against cluster=${cluster}`);
}
 
const connection = new Connection(
  process.env.SOLANA_CLUSTER_URL ?? clusterApiUrl("devnet"),
  "confirmed",
);
 
const version = await connection.getVersion();
console.log("rpc ok", version);

import { Keypair } from "@solana/web3.js";
import bs58 from "bs58";
 
function loadPayer(): Keypair {
  const secret = process.env.AGENT_PAYER_SECRET_BASE58;
  if (!secret) throw new Error("AGENT_PAYER_SECRET_BASE58 missing");
  return Keypair.fromSecretKey(bs58.decode(secret));
}
 
const payer = loadPayer();
console.log("payer", payer.publicKey.toBase58());

import { z } from "zod";
import { PublicKey, LAMPORTS_PER_SOL } from "@solana/web3.js";
 
const TransferSolArgs = z.object({
  to: z.string().refine((s) => {
    try {
      new PublicKey(s);
      return true;
    } catch {
      return false;
    }
  }, "invalid pubkey"),
  sol: z.number().positive().max(0.1), // hard tutorial cap
  intentId: z.string().min(8).max(128),
});
 
type TransferSolArgs = z.infer<typeof TransferSolArgs>;
 
// Example agent-facing description (framework-specific wiring omitted):
// name: transferSOL
// description: Send a small amount of SOL on the pinned cluster. Always pass a unique intentId.

import {
  Connection,
  Keypair,
  PublicKey,
  SystemProgram,
  Transaction,
  sendAndConfirmTransaction,
  LAMPORTS_PER_SOL,
} from "@solana/web3.js";
 
const seenIntents = new Set<string>(); // demo only; use durable storage in real agents
 
export async function transferSOLTool(input: unknown, connection: Connection, payer: Keypair) {
  const args = TransferSolArgs.parse(input);
  if (seenIntents.has(args.intentId)) {
    return { status: "duplicate", intentId: args.intentId };
  }
 
  const tx = new Transaction().add(
    SystemProgram.transfer({
      fromPubkey: payer.publicKey,
      toPubkey: new PublicKey(args.to),
      lamports: Math.round(args.sol * LAMPORTS_PER_SOL),
    }),
  );
 
  const signature = await sendAndConfirmTransaction(connection, tx, [payer], {
    commitment: "confirmed",
  });
 
  seenIntents.add(args.intentId);
  return {
    status: "confirmed",
    intentId: args.intentId,
    signature,
    cluster: "devnet",
    to: args.to,
    sol: args.sol,
  };
}

// Pseudocode: replace with your framework's tool registry (LangGraph, OpenAI Agents SDK, etc.)
async function handleUserTurn(userText: string) {
  // 1) Model chooses tool + args (not shown)
  const modelArgs = {
    to: process.env.DEMO_RECIPIENT!, // known devnet address
    sol: 0.001,
    intentId: `demo-${Date.now()}`,
  };
 
  // 2) Runtime executes; model never sees the secret key
  const result = await transferSOLTool(modelArgs, connection, payer);
  return `On-chain result: ${JSON.stringify(result)}`;
}
 
console.log(await handleUserTurn("Tip the demo wallet 0.001 SOL on devnet"));

export async function getBalanceSol(connection: Connection, who: PublicKey) {
  const lamports = await connection.getBalance(who, "confirmed");
  return lamports / LAMPORTS_PER_SOL;
}
 
const bal = await getBalanceSol(connection, payer.publicKey);
if (bal < 0.01) {
  throw new Error(`Fund devnet payer first; balance=${bal}`);
}

export async function observeSignature(connection: Connection, signature: string) {
  const latest = await connection.getLatestBlockhash("confirmed");
  const conf = await connection.confirmTransaction(
    { signature, ...latest },
    "confirmed",
  );
  if (conf.value.err) {
    return { status: "failed", signature, err: conf.value.err };
  }
  return { status: "confirmed", signature };
}

function assertSafeSpendEnv() {
  if ((process.env.SOLANA_CLUSTER ?? "devnet") !== "devnet") {
    throw new Error("basics runner is devnet-only");
  }
  if (process.env.ALLOW_MAINNET_AGENT === "1") {
    throw new Error("ALLOW_MAINNET_AGENT is not valid in basics examples");
  }
}
 
function assertArgs(args: TransferSolArgs) {
  if (args.sol > 0.1) throw new Error("amount exceeds basics cap");
}