Skip to main content

Storage Programs API Reference

This page is the deep-link reference for the Storage Programs surface of @kynesyslabs/demosdk@v4.0.3. Every signature, return type, and parameter shape on this page is lifted directly from the SDK source. For the narrative walkthrough, start at Getting Started. The Storage Programs surface lives in two modules:
  • @kynesyslabs/demosdk/websdk — the Demos class with the storagePrograms accessor (signing + reading).
  • @kynesyslabs/demosdk/storage — the StorageProgram class (payload builders, validators, ACL helpers), all type aliases, the STORAGE_PROGRAM_CONSTANTS object, and the type guards.

Imports

There is no DemosClient and no demos.storageProgram (singular). The class is Demos and the accessor is demos.storagePrograms (plural). The static helpers on StorageProgram (e.g. deriveStorageAddress, getDataSize) are not exported as standalone functions — call them on the class.

Demos storage accessor

The storagePrograms property on a connected Demos instance exposes two methods:

demos.storagePrograms.sign

Signs a Storage Program payload as a transaction. The returned Transaction is ready for demos.confirm followed by demos.broadcast (or demos.broadcastAndWait).

Signature

Parameters

Returns

Promise<Transaction> — a fully signed transaction with content.type = "storageProgram" and content.data = ["storageProgram", payload].

Behavior

  • Throws "Wallet not connected" if no keypair is attached to the Demos instance.
  • Throws "Storage address Not found in payload" if payload.storageAddress is missing.
  • Sets tx.content.to to payload.storageAddress before signing.

Example

demos.storagePrograms.read

Fetches a Storage Program by address over HTTP. Issues GET <rpc_url>/storage-program/<address>. If a wallet is connected, the request is annotated with identity and signature headers (ed25519 signature over the connected address) so ACL-protected programs can resolve permissions.

Signature

Parameters

Returns

Promise<StorageProgramResponse> — see StorageProgramResponse. The success field indicates whether the lookup resolved; on failure, error and errorCode are populated.

Example

Reads do not produce a transaction and incur no fee. The response shape is flat — fields like data, metadata, owner, sizeBytes, createdAt, updatedAt live at the top level of the response object, not nested under data.variables / data.metadata.

StorageProgram static helpers

All payload builders and validators are static methods on the StorageProgram class. They are pure (with the exception of the async query helpers documented under RPC Queries) — they build typed payloads, they do not broadcast.

Address derivation

StorageProgram.deriveStorageAddress

Computes the deterministic storage address for a (deployer, programName, nonce, salt) tuple.
Signature
Parameters
Returns
stringstor- followed by the first 40 characters of sha256("<deployer>:<programName>:<nonce>:<salt>").
Example

Program operations

StorageProgram.createStorageProgram

Builds a CREATE_STORAGE_PROGRAM payload. The storage address is derived inside the helper from (deployerAddress, programName, options.nonce, options.salt).
Signature
Parameters
Returns
StorageProgramPayload with operation: "CREATE_STORAGE_PROGRAM" and storageLocation defaulting to "onchain" when omitted.
Throws
  • "nonce is required for storage program creation" if options.nonce is undefined.
Example

StorageProgram.writeStorage

Builds a WRITE_STORAGE payload that replaces the entire data field of an existing program. For surgical updates, use the granular helpers below.
Signature
Parameters
Returns
StorageProgramPayload with operation: "WRITE_STORAGE".
Example

StorageProgram.readStorage

Builds a READ_STORAGE payload for transaction validation only. This does not perform an actual read — use demos.storagePrograms.read (or one of the RPC query helpers) to fetch program data.
Signature
Returns
StorageProgramPayload with operation: "READ_STORAGE" — useful when you need to construct a payload object for validation pipelines or type-guards.
Example

StorageProgram.updateAccessControl

Builds an UPDATE_ACCESS_CONTROL payload. Owner-only at execution time.
Signature
Parameters
Returns
StorageProgramPayload with operation: "UPDATE_ACCESS_CONTROL".
Example

StorageProgram.deleteStorageProgram

Builds a DELETE_STORAGE_PROGRAM payload. Irreversible at execution time; the program and all stored data are removed.
Signature
Returns
StorageProgramPayload with operation: "DELETE_STORAGE_PROGRAM".
Example

Granular field operations

These helpers build payloads for in-place edits to JSON-encoded programs. Each is rejected by the chain when applied to a binary-encoded program.

StorageProgram.setField

Sets a single top-level field to a value.
Signature
Returns
StorageProgramPayload with operation: "SET_FIELD", plus field and value.
Example

StorageProgram.setItem

Replaces an item at index inside an array field. Negative indexing is supported (-1 = last element).
Signature
Returns
StorageProgramPayload with operation: "SET_ITEM", plus field, index, and value.
Example

StorageProgram.appendItem

Appends an item to an array field.
Signature
Returns
StorageProgramPayload with operation: "APPEND_ITEM", plus field and value.
Example

StorageProgram.deleteField

Removes a top-level field from the stored object entirely.
Signature
Returns
StorageProgramPayload with operation: "DELETE_FIELD", plus field.
Example

StorageProgram.deleteItem

Removes the item at index from an array field. Negative indexing is supported. The array is compacted after removal.
Signature
Returns
StorageProgramPayload with operation: "DELETE_ITEM", plus field and index.
Example

Validators

StorageProgram.validateSize

Returns true when the data fits within STORAGE_PROGRAM_CONSTANTS.MAX_SIZE_BYTES (1 MB).
Signature
Example

StorageProgram.getDataSize

Returns the size of the data in bytes. For "binary" encoding, the input is treated as base64 and the decoded byte length is returned. For "json" encoding, JSON.stringify is run and the UTF-8 byte length of the result is returned.
Signature
Example

StorageProgram.validateNestingDepth

Returns true when the JSON object’s nesting depth is <= maxDepth. JSON-only.
Signature
Example

StorageProgram.calculateStorageFee

Computes the storage fee for a payload. Pricing is 1 DEM per 10 KB chunk, minimum 1 DEM, returned as a bigint in OS (1 DEM = 10⁹ OS).
Signature
Returns
bigint — fee in OS. Use denomination.osToDem (from @kynesyslabs/demosdk) to convert to whole DEM for display.
Example

Type reference

StorageProgramPayload

The single payload shape produced by every StorageProgram.* builder. Different operations populate different subsets of fields.

StorageProgramACL

ACL resolution order (highest priority first):
  1. Owner — full access, always.
  2. Blacklisted — denied, regardless of allowed/groups.
  3. allowed — full permissions granted.
  4. groups — per-group permission check.
  5. mode fallback — "owner" and "restricted" deny; "public" allows read.

StorageGroupPermissions

StorageACLMode

StorageEncoding

  • "json"data is Record<string, any>.
  • "binary"data is a base64 string.

StorageLocation

"ipfs" is reserved for future hybrid storage and is not yet implemented — payloads with storageLocation: "ipfs" currently fall back to "onchain".

StorageProgramOperation

READ_STORAGE is a query operation — it is not submitted as a transaction in normal usage.

StorageProgramTransactionContent

StorageProgramTransaction

StorageProgramData

Returned by node-level RPC queries (e.g. StorageProgram.getByAddress).

StorageProgramListItem

StorageProgramResponse

The response shape returned by demos.storagePrograms.read. All payload fields are top-level — there is no nested data.variables / data.metadata envelope.

StorageFieldType

Returned by the getFieldType RPC helper.

StorageProgramFieldsResponse

Constants

STORAGE_PROGRAM_CONSTANTS

The object is declared as const, so its fields are read-only.

Type guards

Runtime narrowing helpers exported from @kynesyslabs/demosdk/storage.

isStorageProgramPayload

Returns true when payload is a non-null object with a string storageAddress and a string operation matching one of the values in StorageProgramOperation.

isValidEncoding

Returns true only for "json" or "binary".

isValidStorageLocation

Returns true only for "onchain" or "ipfs".

Deprecated members

These exist for backward compatibility with pre-v3 storage programs and should not be used in new code. The legacy "private" and "deployer-only" modes both map to the modern mode: "owner".

Cross-references

  • Getting Started — end-to-end walkthrough (connect, build, sign, broadcast, read).
  • Operations — when to use create vs. write vs. granular ops, and the full lifecycle.
  • Access Controlowner / public / restricted, allowlists, blacklists, groups, and resolution order.
  • RPC Queries — node-level queries such as StorageProgram.getByAddress, getByOwner, searchByName, getFields, getValue, getItem, hasField, getFieldType, getAll.
  • Cookbook: Storage Programs — recipes for public profiles, team workspaces, and binary attachments.