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— theDemosclass with thestorageProgramsaccessor (signing + reading).@kynesyslabs/demosdk/storage— theStorageProgramclass (payload builders, validators, ACL helpers), all type aliases, theSTORAGE_PROGRAM_CONSTANTSobject, and the type guards.
Imports
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
| Parameter | Type | Description |
|---|---|---|
payload | StorageProgramPayload | A payload produced by one of the StorageProgram.* builders. Must include storageAddress. |
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 theDemosinstance. - Throws
"Storage address Not found in payload"ifpayload.storageAddressis missing. - Sets
tx.content.totopayload.storageAddressbefore 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
| Parameter | Type | Description |
|---|---|---|
address | string | The storage program address (stor-{40 hex chars}). |
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
| Parameter | Type | Required | Description |
|---|---|---|---|
deployerAddress | string | yes | The address that will own the program. |
programName | string | yes | Human-readable name of the program. |
nonce | number | yes | Sender’s account nonce — guarantees a unique address per transaction even when programName collides. |
salt | string | no | Optional extra entropy. Defaults to "". |
Returns
string — stor- 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
| Parameter | Type | Required | Description |
|---|---|---|---|
deployerAddress | string | yes | The creator’s address; becomes the program owner. |
programName | string | yes | Unique-per-deployer-per-nonce program name. |
data | Record<string, any> | string | yes | Initial payload — JSON object for "json" encoding, base64 string for "binary". |
encoding | StorageEncoding | no | "json" (default) or "binary". |
acl | Partial<StorageProgramACL> | no | Access control. Missing fields default to { mode: "owner" }. |
options | { nonce; salt?; metadata?; storageLocation? } | yes | nonce is required. |
Returns
StorageProgramPayload with operation: "CREATE_STORAGE_PROGRAM" and storageLocation defaulting to "onchain" when omitted.
Throws
"nonce is required for storage program creation"ifoptions.nonceisundefined.
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
| Parameter | Type | Required | Description |
|---|---|---|---|
storageAddress | string | yes | The stor-{hash} address. |
data | Record<string, any> | string | yes | New payload (must match the program’s encoding). |
encoding | StorageEncoding | no | "json" (default) or "binary". |
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
| Parameter | Type | Required | Description |
|---|---|---|---|
storageAddress | string | yes | The program address. |
acl | Partial<StorageProgramACL> | yes | New ACL configuration. The full ACL is replaced — to keep existing fields, include them. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
data | any | — | Object to inspect. |
maxDepth | number | STORAGE_PROGRAM_CONSTANTS.MAX_JSON_NESTING_DEPTH (64) | Maximum allowed nesting depth. |
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
- Owner — full access, always.
- Blacklisted — denied, regardless of allowed/groups.
allowed— full permissions granted.groups— per-group permission check.modefallback —"owner"and"restricted"deny;"public"allows read.
StorageGroupPermissions
StorageACLMode
| Mode | Default behavior (no other rule matched) |
|---|---|
"owner" | Owner only. Most restrictive. |
"public" | Anyone reads, only the owner writes. |
"restricted" | Only addresses in allowed / groups may access. |
StorageEncoding
"json"—dataisRecord<string, any>."binary"—datais 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
| Constant | Value | Meaning |
|---|---|---|
MAX_SIZE_BYTES | 1_048_576 (1 MB) | Hard cap on payload size for both JSON and binary encodings. |
PRICING_CHUNK_BYTES | 10_240 (10 KB) | Granularity for fee calculation. |
FEE_PER_CHUNK | OS_PER_DEM (10⁹ OS = 1 DEM) | Fee per chunk, expressed as a bigint in OS. |
MAX_JSON_NESTING_DEPTH | 64 | Maximum nesting depth for JSON encoding. |
as const, so its fields are read-only.
Type guards
Runtime narrowing helpers exported from@kynesyslabs/demosdk/storage.
isStorageProgramPayload
true when payload is a non-null object with a string storageAddress and a string operation matching one of the values in StorageProgramOperation.
isValidEncoding
true only for "json" or "binary".
isValidStorageLocation
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.| Deprecated | Replacement |
|---|---|
StorageProgram.createStorageProgramLegacy(...) | StorageProgram.createStorageProgram(..., acl, options) |
StorageProgram.updateAccessControlLegacy(...) | StorageProgram.updateAccessControl(address, acl) |
StorageProgramAccessControl ("private" | "public" | "restricted" | "deployer-only") | StorageACLMode ("owner" | "public" | "restricted") inside StorageProgramACL |
StorageProgramPayload.accessControl | StorageProgramPayload.acl.mode |
StorageProgramPayload.allowedAddresses | StorageProgramPayload.acl.allowed |
"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 Control —
owner/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.