Introduction

Sigil is a command bus built on the Solana ledger. Instead of connecting a wallet to a website, a user puts a small JSON command in a transaction memo and signs it. A relayer streams that transaction, and an interpreter validates, authorizes and runs it.

Because every command is signed, you get authentication for free. Because it is on-chain, you get ordering, timestamps and a public audit trail for free. You never deploy a smart contract of your own — the ledger is only the ordered message bus.

Quickstart

Install the SDK and run a command end to end. In simulate mode the interpreter validates, authorizes, dedupes and executes it, then returns a receipt — no wallet connection, no session.

$ npm i sigilsol-sdk
added 2 packages in 1.4s

import { createClient } from 'sigilsol-sdk'

const sigil = createClient({ signer: 'Demo7xQ…' })

const receipt = await sigil.simulate({
  app: 'board', cmd: 'post',
  args: { text: 'gm, on-chain' },
})
// → { status: 'done', result: { posted: true } }

The command envelope

A command is a small JSON object carried in the transaction memo. This v1 shape is frozen and validated with a strict schema on the way in — unknown top-level keys are rejected.

{
  "v": 1,            // frozen version
  "app": "board",    // namespace
  "cmd": "post",     // command name
  "args": { "text": "gm, on-chain" },
  "nonce": "1a2b3c"  // optional, idempotency
}

Apps & handlers

An app is a namespace, a set of commands with schemas, and the handlers that run them. Many apps run on one engine, isolated by namespace and control address.

registerApp({
  namespace: 'board',
  controlAddress: INBOX,
  commands: {
    post: {
      schema: z.object({ text: z.string().max(280) }),
      handler: (ctx) => board.add(ctx.signer, ctx.args.text),
    },
  },
})

The handler context (ctx) gives you the proven signer, the validated args, and the transaction signature. Commands are data, never code — there is no eval, ever.

Authorization

Anyone can send a memo to a public address, so the allowlist / role check must be airtight and fail closed. Authorization is enforced from the on-chain signer set: only holders, stakers or a multisig may issue a command.

• Authorization fails closed: signer → role → command.
• Unauthorized or garbage commands are rejected cheaply and never executed.
• Per-signer rate limits, per-command caps and a blast-radius kill switch.

Interpreter pipeline

Every command — real or simulated — flows through the same path:

• received — the relayer reads the transaction from the stream.
• signature verified — the Ed25519 signature is checked against the signer's public key; forgeries are rejected.
• schema valid — the args are validated against the command schema.
• signer authorized — the signer is checked against roles, fail closed.
• deduped — one command record per transaction signature.
• executing — enqueue on a serial queue keyed by resource so two commands never race.
• done — the handler runs and an optional on-chain receipt is posted.

Streaming

The relayer exposes a live transaction stream filtered to each registered control address — an app inbox. Backfill on startup and reconnect means a dropped socket never loses a command.

for await (const cmd of sigil.stream({ app: 'board' })) {
  console.log(cmd.cmd, cmd.status)
  // post received
  // post done
}

SDKs

Use the TypeScript SDK (sigilsol-sdk), or call the same HTTP API from any language. Native Rust and Python clients are on the roadmap.

$ npm i sigilsol-sdk       # TypeScript SDK — published on npm
$ # Rust & Python: call the HTTP API (native clients on the roadmap)

API reference

The same endpoints run the console. Every endpoint here exists in the backend today.

$ curl -s https://sigil-backend-production-41ef.up.railway.app/api/apps
{ "apps": [ { "namespace": "board", "commands": ["post"] } ] }

Try it

The fastest way to understand Sigil is to run a command and watch it move through the interpreter.