Grain

Full Definition

A Grain is the atomic unit of computation and isolation in the Sandstorm/Melusina OS architecture. Every grain runs in its own sandbox with its own persistent storage, its own capability set, and its own lifecycle — it can be started, stopped, snapshotted, and migrated independently. There is no ambient authority. A grain can only access what it has been explicitly granted through the Powerbox. Sails.to deploys two classes of grains:

• Station Grains (Orchestrators): DAO Manager, Broker Portal, Trustee Dashboard — these coordinate workflows and hold authority delegations
• Instance Grains (Workers): Offering, KYC, Investor — these execute specific tasks within a single bounded context

Why It Matters

In traditional platforms, a vulnerability in one module can cascade across the entire system. A compromised user service exposes the payment service. A bug in compliance leaks investor data. The grain model makes this architecturally impossible. Each grain is a fortress — its own filesystem, its own network namespace, its own capability boundary.

For regulated financial infrastructure, this isn't just good engineering — it's a compliance requirement materialized in architecture. When an auditor asks "can the Broker Portal access KYC data it hasn't been granted?", the answer is a provable, cryptographic no. The Cap'n Proto capability system enforces it at the protocol level.

How It Works

1. A grain is spawned from a package (SPK) containing its application code and dependencies
2. The Sandstorm supervisor creates an isolated container with a private filesystem and journal store
3. The grain communicates with other grains exclusively via Cap'n Proto RPC on FD3
4. Capabilities are acquired through the Powerbox — claim tokens become persistent sturdyRefs
5. When idle, grains are automatically suspended; when needed, they resume from their journal state

The result: thousands of grains running simultaneously, each provably isolated, each resumable, each auditable.

Related Terms