sigilsol-sdk

TypeScript SDK for Sigil — the signed command bus for Solana.

Sigil turns the Solana ledger into a programmable command bus: a user drops a JSON command into a transaction memo, signs it, and your backend interprets and runs it. No wallet sessions, nothing live to phish. This SDK lets you build, simulate and stream those commands from Node or the browser.

Install

npm install sigilsol-sdk

Requires Node.js 18+ (uses the global fetch). Works in modern browsers too.

Quickstart

import { createClient } from 'sigilsol-sdk';

// Defaults to the hosted devnet backend (simulate mode).
const sigil = createClient({
  signer: 'Demo7xQpfz9wY3k2Lr8bN4sV6tH1cJmA5dRgB3uPq2eF',
});

// List the available apps and their commands.
const apps = await sigil.apps();
console.log(apps.map((a) => a.namespace)); // ['board','counter','vote','ops','game']

// Run a command end to end (no broadcast). Returns a receipt.
const receipt = await sigil.simulate({
  app: 'board',
  cmd: 'post',
  args: { text: 'gm, on-chain' },
});

console.log(receipt.status); // 'done'
console.log(receipt.result); // { posted: true, total: 1 }
console.log(receipt.stages.map((s) => s.stage));
// ['received','schema valid','signer authorized','deduped','executing','handler executed','done']

A rejected command is not an exception — it comes back as a receipt with status: 'rejected' and a reason:

const r = await sigil.simulate({ app: 'board', cmd: 'post', args: { text: '' } });
// r.status === 'rejected'
// r.reason  === 'schema: text: String must contain at least 1 character(s)'

Live command stream

Subscribe to every command flowing through the interpreter over WebSocket. The returned object is an async iterable and also supports a callback:

const stream = sigil.stream(); // or sigil.stream({ app: 'board' })

// callback style
stream.on((event) => {
  if (event.type === 'result') console.log('done', event.app, event.cmd, event.result);
  if (event.type === 'rejected') console.log('rejected', event.app, event.reason);
});

// or async-iterator style
for await (const event of sigil.stream({ app: 'vote' })) {
  console.log(event.type, event.app, event.cmd);
}

// stop when you're done
stream.close();

API

createClient(options?)

| option | type | default | description | | --------- | -------- | ---------------------- | -------------------------------------------------------- | | baseUrl | string | hosted backend | API base URL, e.g. https://api.sigilsol.io. | | signer | string | — | Default signer attached to commands (simulate mode). |

Returns a SigilClient:

• apps(): Promise<AppInfo[]> — catalog of apps and their command schemas.
• simulate(input, opts?): Promise<Receipt> — run a command end to end without broadcasting. input is either a full Envelope or a shorthand { app, cmd, args?, nonce? }. A nonce is generated if omitted.
• send(input, opts?): Promise<Receipt> — submit a signed transaction on live devnet. Phase 2 (hosted relayer + demo signer) — not enabled yet; use simulate today.
• stream(opts?): SigilStream — live WebSocket feed, optionally filtered by { app }. Async-iterable with .on(handler) and .close().
• health(): Promise<{ ok, mode, ... }> — backend status.

buildEnvelope({ app, cmd, args?, nonce? }): Envelope

Helper to construct a frozen v1 envelope:

import { buildEnvelope } from 'sigilsol-sdk';
const env = buildEnvelope({ app: 'counter', cmd: 'inc', args: { by: 5 } });
// { v: 1, app: 'counter', cmd: 'inc', args: { by: 5 } }

Types

All types are exported: Envelope, Receipt, Stage, AppInfo, CommandInfo, ArgField, StreamEvent, plus SigilClient, SigilStream, ClientOptions, CommandInput, CallOptions.

Notes

• The hosted backend runs in simulate mode: commands are validated, authorized, deduped and executed by the interpreter, but nothing is broadcast to a chain. Live devnet broadcast (send) is on the roadmap.
• Point the client at your own deployment by passing baseUrl.

Links

• Site & live console: https://sigilsol.io
• Docs: https://sigilsol.io/#/docs

License

MIT