Skip to content

Cloud Storage

View page in Markdown Download page in Markdown Open in ChatGPT Open in Claude

Introduction

Section titled “Introduction”

@parity/product-sdk-cloud-storage stores content-addressed data on the Bulletin Chain. You upload bytes and get back a CID; you fetch by CID from anywhere inside a Host. It handles chunking, DAG-PB manifests, and CID calculation for you, and adds network presets, container-only read helpers, and an authorization pre-flight.

Reach for it when your Product needs content that outlives a session and is addressable by anyone who has the CID: profile photos, published posts, file uploads, or full snapshots of app state.

When to Use It

Section titled “When to Use It”
  • To store bytes or files on chain and receive a CID plus a block receipt (store(data).send()).
  • To fetch content by CID inside a Host, with automatic reassembly of chunked uploads (fetchBytes, fetchJson).
  • To check an account's storage quota before uploading, so a missing allowance becomes an actionable error rather than a bare on-chain rejection (checkAuthorization).
  • Reads are Host-only; there is no public gateway fallback. To confirm a CID landed on chain without fetching the bytes, use verifyStored.

Core Concepts

Section titled “Core Concepts”
  • CloudStorageClient: The main class. Create it with CloudStorageClient.create({ environment, signer }), then call store, fetchBytes, and fetchJson.
  • Content addressing: Uploads are identified by a CID (CIDv1) derived from their content, not by a path or key. The same bytes always produce the same CID.
  • store(data) builder: A fluent builder ending in .send(), which resolves with a StoreResult. Only size is always present; cid, blockNumber, and extrinsicIndex are optional. Large payloads are chunked automatically.
  • Read helpers return a Result: fetchBytes and fetchJson return a Result (check .ok); DAG-PB chunked content is reassembled for you unless you opt out.
  • Authorization pre-flight: checkAuthorization returns a Result wrapping an AuthorizationStatus with the remaining transactions, bytes, and expiration, and never throws. Uploading requires an authorization on the account.
  • createLazySigner(getSigner): A signer wrapper that resolves the underlying signer on each call, so you can build the client before an account is selected.

Store and Fetch by CID

Section titled “Store and Fetch by CID”

Create a client with a lazy signer, upload bytes, and fetch them back by CID:

import {
  CloudStorageClient,
  createLazySigner,
} from '@parity/product-sdk-cloud-storage';


const client = await CloudStorageClient.create({
  environment: 'paseo',
  signer: createLazySigner(() => manager.getSigner()),
});


const stored = await client.store(bytes).send();
if (!stored.cid) throw new Error('The store returned no CID.');
const cid = stored.cid.toString();
console.log(cid, stored.blockNumber, stored.size);


const fetched = await client.fetchBytes(cid);
if (fetched.ok) {
  console.log(new TextDecoder().decode(fetched.value));
}

Check the Quota Before Uploading

Section titled “Check the Quota Before Uploading”

Confirm the account is authorized and has room before you submit an upload:

import { checkAuthorization } from '@parity/product-sdk-cloud-storage';


const status = await checkAuthorization(api, address);
if (!status.ok) {
  console.error(status.error.message);
} else if (!status.value.authorized) {
  // The account has no storage authorization yet.
} else if (status.value.remainingBytes < BigInt(bytes.length)) {
  // The upload exceeds the remaining quota.
}

Limitations

Section titled “Limitations”
  • Reads run inside a Host only; outside a container, fetchBytes returns a CloudStorageHostUnavailableError.
  • Uploading requires a signer and an on-chain storage authorization for the account.
  • authorizeAccount is additive and is deliberately not retried; verify the result with checkAuthorization before retrying yourself.
  • verifyStored needs a known block; it does not scan the whole chain.
  • A chunked upload (large files) returns no blockNumber or extrinsicIndex, so it cannot be renewed by position. Renew it by content hash instead: the manifest CID and every chunk CID, which you can read from StoreResult.chunks.chunkCids or from the manifest's links.

Where to Go Next

Section titled “Where to Go Next”

  • Store Data on Chain

    The task-focused recipe: upload to the Bulletin Chain and fetch by CID, with chunking and authorization.

    → Store Data on Chain

  • Statement Store

    Pair durable storage with real-time signaling: announce a fresh CID to other users as it changes.

    → Statement Store

  • API Reference

    The complete cloud-storage surface: CloudStorageClient, CID helpers, and authorization.

    → Visit Site

Last updated: