Recipes

Working snippets for common NorthStar patterns. Each recipe extends the Hello World shape; copy-paste ready.

1. Always-on agent loop

A Bun service that opens a persistent session, runs a deterministic policy each tick, and re-emits each decision over Server-Sent Events. This is the shape the Mach Sandbox runs in production.

import { AgentLoop, currentRatioBps, DEFAULT_POLICY } from "@mach/agent";

const loop = new AgentLoop({
  manifest, agent, owner, mintA, mintB,
  rpc: ER_RPC,
  intervalMs: 1_000,
  onCycle: (event) => {
    eventBus.publishTx({
      tSendUnixMs: event.timestampMs,
      signature: event.signature,
      direction: event.decision.kind === "swap" ? event.decision.direction : null,
      // …
    });
  },
});
loop.start();

The onCycle callback fires per tick with the policy decision, vault snapshot, and any submitted signature. Wire it to whatever consumer you need — SSE, NDJSON file, OpenTelemetry.

2. Confirm-status reconciliation

ER confirmation can be faster than the L1-tuned confirmTransaction timeout. Use a separate getSignatureStatuses poller to upgrade pending rows once the chain catches up:

const reconciler = setInterval(async () => {
  for (const seq of pending) {
    const [status] = (await ER_RPC.getSignatureStatuses([seq.signature], {
      searchTransactionHistory: true,
    })).value;
    if (!status) continue;
    if (status.err) markFailed(seq, status.err);
    else if (status.confirmationStatus === "confirmed") markConfirmed(seq, status.slot);
  }
}, 1_500);

3. Settle on TTL approach

Sessions auto-expire when their TTL elapses. To rotate gracefully, open the next session in parallel a few minutes before expiry, warm it (delegate accounts), then swap your traffic over and close the old one:

async function rotateBeforeTTL(currentSession: Session, currentSlot: bigint) {
  const slotsLeft = currentSession.expirySlot - currentSlot;
  const slotsBeforeRotate = 200n;          // ~ 80s buffer at 400ms slots

  if (slotsLeft > slotsBeforeRotate) return;

  const next = await sdk.openSession({ owner, gridId: currentSession.gridId + 1n, ttlSlots, feeCap });
  for (const account of currentSession.delegatedAccounts) {
    await sdk.delegate({ owner, gridId: next.gridId, account, ownerProgram });
  }
  await sdk.closeSession({ owner, gridId: currentSession.gridId });

  return next;
}

4. Custom-fee grid (USDC)

import { FeeStructure } from "@sonicsvm/northstar-sdk";

const usdcMint = new PublicKey("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU");

await sdk.openSession({
  owner,
  gridId: 1n,
  ttlSlots: 86_400n,
  feeCap: 0n,                                  // gasless from the user's perspective
  feeStructure: FeeStructure.custom({
    token: usdcMint,
    perTxLamports: 10_000n,                    // ~ 0.001 USDC per tx
    revenueSplitBps: 5_000,                    // 50% to grid operator
  }),
});

See Programmable Economics for the full schema.

5. Subscribe to live activity

The Portal's session account is just a Solana account; subscribe to it like any other:

const subId = erRpcConnection.onAccountChange(sessionAddress, (acct) => {
  console.log(`Session bytes changed at slot ${acct.lamports} …`);
});

For per-tx feeds, use the program's instruction accounts:

const programSubId = ER_RPC.onLogs(programId, (logs) => {
  console.log("ix logs:", logs);
});

See also

• Hello World

• Confirmation lifecycle

• API reference