Documentation Index

Fetch the complete documentation index at: https://docs.kynesys.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​

Storage Program Operations

import { Demos } from "@kynesyslabs/demosdk/websdk"
import { StorageProgram } from "@kynesyslabs/demosdk/storage"

const demos = new Demos()
await demos.connect("https://node2.demos.sh")
await demos.connectWallet(process.env.MNEMONIC!)

// 1. Build payload via a StorageProgram.* static helper
// 2. const tx = await demos.storagePrograms.sign(payload)
// 3. const validityData = await demos.confirm(tx)
// 4. await demos.broadcast(validityData)   // or demos.broadcastAndWait

​

Operation overview

​

CREATE — provision a new program

const ownerAddress = demos.getAddress()
const nonce = await demos.getAddressNonce(ownerAddress)

const payload = StorageProgram.createStorageProgram(
    ownerAddress,
    "userProfile",
    { displayName: "Alice", stats: { posts: 0 } },
    "json",                  // encoding: "json" | "binary"
    { mode: "public" },      // ACL: { mode, allowed?, blacklisted?, groups? }
    { nonce, salt: "v1" },   // options.nonce is required
)

const tx = await demos.storagePrograms.sign(payload)
await demos.broadcast(await demos.confirm(tx))

​

Pre-flight checks

• Nonce. options.nonce is required. Fetch the sender’s current nonce with demos.getAddressNonce(ownerAddress) — without it the helper throws "nonce is required for storage program creation". The nonce is mixed into address derivation so two creates from the same deployer with the same programName produce different addresses.
• ACL choice. Pick the mode you want now — you can change it later with UPDATE_ACCESS_CONTROL, but until you do, the default is "owner" (only the owner can read or write).
• Encoding. "json" for structured Record<string, any>, "binary" for base64-encoded blobs. Granular operations (setField, appendItem, etc.) are rejected on "binary" programs.
• Size. Validate against the 1 MB ceiling before signing:
  if (!StorageProgram.validateSize(myData, "json")) {
      throw new Error("Payload exceeds MAX_SIZE_BYTES (1 MB)")
  }
  if (!StorageProgram.validateNestingDepth(myData)) {
      throw new Error("JSON nesting exceeds MAX_JSON_NESTING_DEPTH (64)")
  }
  
• Fee budget. StorageProgram.calculateStorageFee(data, encoding) returns a bigint of the fee in OS (1 DEM = 10⁹ OS). Storage is billed at 1 DEM per 10 KB chunk, minimum 1 DEM.
• Predict the address up front (optional).
  const addr = StorageProgram.deriveStorageAddress(ownerAddress, "userProfile", nonce, "v1")
  

​

WRITE — replace the full document

• Binary programs. Granular operations don’t apply — every update is a full replacement.
• Full snapshots. You’re computing a new state from scratch (e.g. importing from another source) and don’t need to reason about diffs.
• Atomic multi-field rewrites. When you want every changed field to land in a single transaction even though there are no granular WRITE_MANY semantics.

const writePayload = StorageProgram.writeStorage(
    storageAddress,
    { displayName: "Alice", bio: "Web3 builder", stats: { posts: 1 } },
    "json",
)
const tx = await demos.storagePrograms.sign(writePayload)
await demos.broadcast(await demos.confirm(tx))

​

Granular operations — surgical JSON updates

const a = StorageProgram.setField(storageAddress, "bio", "Updated bio")
const b = StorageProgram.appendItem(storageAddress, "posts", { id: 7 })
const c = StorageProgram.setItem(storageAddress, "posts", -1, { id: 8 })
const d = StorageProgram.deleteField(storageAddress, "legacyConfig")
const e = StorageProgram.deleteItem(storageAddress, "posts", 0)

// Each returns a StorageProgramPayload — same sign / confirm / broadcast flow.

• You’re editing a small slice of a large document — fee is computed on the operation payload, not the whole stored document.
• You want concurrent writers each touching different fields without overwriting each other’s changes.
• You want the transaction to fail loudly if the field doesn’t have the shape you expect (e.g. setItem on a non-array).

• The program is "binary" — granular operations are rejected for binary encoding.
• You’re rewriting most of the document anyway.
• You need cross-field invariants (multiple fields must change atomically as one logical unit; granular ops are one-op-per-tx).

​

READ — fetch program data over RPC

const result = await demos.storagePrograms.read(storageAddress)

if (result.success) {
    console.log(result.data)         // the stored JSON object or base64 string
    console.log(result.metadata)     // optional metadata
    console.log(result.sizeBytes)
} else {
    console.error(result.error, result.errorCode)
}

​

UPDATE ACCESS CONTROL — owner-only ACL changes

const aclPayload = StorageProgram.updateAccessControl(
    storageAddress,
    {
        mode: "restricted",
        allowed: ["demos1user1...", "demos1user2..."],
        blacklisted: ["demos1spam..."],
        groups: {
            editors: { members: ["demos1ed1..."], permissions: ["read", "write"] },
            viewers: { members: ["demos1view..."], permissions: ["read"] },
        },
    },
)
const tx = await demos.storagePrograms.sign(aclPayload)
await demos.broadcast(await demos.confirm(tx))

​

Pre-flight checks

• Owner-only. Anyone else gets denied at the ACL check before the transaction lands. There is no “deputy” or co-owner concept.
• Mode is required. Valid values are "owner" (default — only the owner can read or write), "public" (anyone reads, only the owner / allowed / writers in groups can write), and "restricted" (only allowed and matching group members get any access).
• Blacklist beats allowlist. An address that appears in both blacklisted and allowed (or in a group) is denied. Use this to revoke without rebuilding the allow set.
• Opening up data. Going from "owner" or "restricted" to "public" exposes everything currently stored — audit the data first if there’s any chance of secrets.

​

DELETE — irreversible teardown

const delPayload = StorageProgram.deleteStorageProgram(storageAddress)
const tx = await demos.storagePrograms.sign(delPayload)
await demos.broadcast(await demos.confirm(tx))

​

Pre-flight checks

• Permission. The owner can always delete. Other addresses can delete only if they are members of an ACL group with the "delete" permission.
• Irreversible. There is no undo, no soft delete, no archival snapshot. The address itself remains derivable from (deployer, programName, nonce, salt), but the data is gone.
• Downstream cleanup. Invalidate caches, notify collaborators, and remove references from indexes before submitting the delete — by the time the transaction lands the data is unrecoverable.

​

Resource limits at a glance

import { STORAGE_PROGRAM_CONSTANTS } from "@kynesyslabs/demosdk/storage"

​

Cross-references

• Getting Started — the four-step build / sign / confirm / broadcast flow with a worked example.
• Access Control — owner / public / restricted modes, allowlists, blacklists, and group permissions.
• RPC Queries — listings, by-owner lookups, name search, and granular field-level reads via StorageProgram.getFields, getValue, getItem, hasField, getFieldType, and getAll.
• API Reference — every StorageProgram static method, the full StorageProgramPayload schema, ACL types, and the StorageProgramResponse shape.
• Cookbook — Storage Programs — end-to-end recipes for public profiles, team workspaces, and binary attachments.