Hello World

The shortest path from zero to a transaction running inside a NorthStar session. Five steps; ~30 lines of code.

What we're going to build

Open a session, transfer SOL between two accounts inside the ER, settle back. Nothing fancy — but every step that matters is in there: session lifecycle, account delegation, ER-side execution, atomic settle-back.

Setup

import { NorthStarSDK } from "@sonicsvm/northstar-sdk";
import {
  Connection,
  Keypair,
  PublicKey,
  SystemProgram,
  Transaction,
} from "@solana/web3.js";

const PORTAL = new PublicKey("74iiMCqFw1afWyp3tdh9pUqfRfCRq7gfdC2YZoNGpovt");
const L1_RPC = new Connection("https://api.devnet.sonic.game", "confirmed");
const ER_RPC = new Connection("https://ephemeral.devnet.sonic.game", "confirmed");

const sdk = new NorthStarSDK({
  portalProgramId: PORTAL,
  customEndpoints: { solana: L1_RPC, ephemeralRollup: ER_RPC },
});

const owner = Keypair.generate();
const recipient = Keypair.generate();

// Fund the owner — devnet faucet, ~5 SOL is comfortable for the session.
// In your dev workflow, prefer the deploy payer at ~/.config/solana/id.json.

Step 1: Open a session

const gridId = 1n;
const ttlSlots = 2_000n;       // ~ 13 minutes at 400ms slots
const feeCap = 10_000_000n;     // 0.01 SOL fee budget

const { sessionAddress } = await sdk.openSession({
  owner,
  gridId,
  ttlSlots,
  feeCap,
});

console.log(`Session: ${sessionAddress.toBase58()}`);

The Portal program creates a session PDA derived from (portal, owner, gridId). From here, anything you delegate to this session is locked on L1 and writable on the ER.

Step 2: Delegate the recipient account

await sdk.delegate({
  owner,
  gridId,
  account: recipient.publicKey,
  ownerProgram: SystemProgram.programId,
});

The Portal records that recipient is now bound to this session. After this returns, the account is read-only on L1 and writable inside the ER.

Step 3: Run the transaction inside the ER

const transferIx = SystemProgram.transfer({
  fromPubkey: owner.publicKey,
  toPubkey: recipient.publicKey,
  lamports: 1_000_000,            // 0.001 SOL
});

const tx = new Transaction().add(transferIx);
tx.feePayer = owner.publicKey;
tx.recentBlockhash = (await ER_RPC.getLatestBlockhash()).blockhash;
tx.sign(owner);

const sig = await ER_RPC.sendRawTransaction(tx.serialize());
await ER_RPC.confirmTransaction(sig, "confirmed");
console.log(`ER tx confirmed: ${sig}`);

Same SystemProgram.transfer instruction you'd send to L1 — different RPC. The ER processes it locally; confirmation lands in milliseconds (see Real-time confirmation).

Step 4: Settle back

await sdk.closeSession({ owner, gridId });
console.log(`Session closed; recipient balance is now visible on L1.`);

CloseSession undelegates every account bound to this session in one atomic step. Recipient's new balance shows up on L1.

Step 5: Verify

const balance = await L1_RPC.getBalance(recipient.publicKey);
console.log(`Recipient L1 balance: ${balance} lamports`);
// Expected: 1_000_000 (the transfer landed, settle-back committed it)

What just happened

Five operations, two RPCs, one Transfer ix that runs identically to how it would on L1.

Where to go from here

• Recipes — patterns for agents, oracles, orderbooks.

• Concepts: sessions — the formal model.

• Migrate to NorthStar — for an existing Solana program.