Prisms & the Cloud Standard

A prism is a namespace on the public registry, dedicated to the index of your files (the reconstruction "routes"), not to the files themselves. The heavy data lives at your storage providers; the prism only holds a lightweight, encrypted index whose alteration is detectable.

Identity

A DataPrism identity is an account address. Two entry points:

• Existing account: connect a compatible account extension (MetaMask, Coinbase Wallet, and others) through your application; the SDK builds on viem, so any viem WalletClient works.
• Prism Key: for users without one, a key can be generated for them. The user never has to understand the underlying network.

That address serves as identity (prism ownership, request signatures) and as the destination for purchased credits. For dashboard-created prisms, an account signature supplies the input for deriving the Prism opening key; the public address alone does not (see dataprism.key below).

Identifiers: protocolId & cloudId

Each prism has a 32-byte identifier, the protocolId, derived deterministically from the platform address and a caller-chosen salt. At the application layer a shortened cloudId (16 bytes, the first half of the protocolId) is used to keep records small.

Because the derivation is deterministic, the SDK can compute the cloudId offline with computeCloudId(address, salt). This is what lets a prism created through the delegated (fee-free) path know its ID immediately, without waiting for the relayer's confirmation.

Creating a prism

Creation goes through the SDK. Two paths, depending on whether the user holds the network's fee currency:

            ┌────── can the user pay network fees? ─────┐
            │ YES                                   NO  │
            ▼                                           ▼
   direct network call                    request to the DataPrism API,
   the user pays the fees                 signed by the user (typed signature)
            │                                           │
            │                             a relayer executes the operation
            │                             and fronts the fees
            ▼                                           ▼
      prism created on the network ◄────────────────────┘

The SDK's execution layer makes both paths transparent: the calling code is identical. At creation, a prism is provisioned with a set of standardized data slots.

When a prism is created with an initial balance (fundAmount > 0), funding and creation happen in a single operation: the SDK has the user sign a token permit (a free, offline signature) instead of a separate approval step, and the platform applies both at once. Creation can also write an initial batch of data in the same atomic operation, so a prism is created and populated in one signature. In the SDK this is the default behaviour of PrismManager.create(): it provisions the prism and writes the standard slots (key, encryption, metadata, providers) in one operation.

The Cloud Standard

The Cloud Standard is a naming convention for the reserved slots of a prism. Each slot is identified by a dataId, the hash of its name. The stored value is always JSON serialized to bytes, and it is encrypted unless noted otherwise.

dataprism.key

{ "public": "", "private": "" }

• public: the prism's public key. Readable by anyone (it is used to encrypt for the prism), so this slot is stored in clear.
• private: the private key. Empty by default and never written to the network.

For dashboard-created prisms, the Prism opening key is derived client-side from an account signature. DataPrismKey.fromSignature hashes the signature with Keccak-256, then normalizes that secret for the configured curve; the signature is not itself the opening key.

Use an organisation-controlled wallet for organisation data, not an employee's personal wallet. The signer must reproduce the same signature bytes. DataPrism cannot recover the opening key or a lost password, and V1 has no prism transfer or opening-key migration. See key custody and fixed ownership.

   connected account
        │  the user signs a deterministic message:
        │     • dataprism:key:${cloudId}              (default)
        │     • dataprism:key:${cloudId}:${password}  (with a password)
        ▼
   signature (deterministic)
        ▼
   Keccak-256 → curve normalization → Prism opening key
        ▼
   public key derived → written into dataprism.key.public

The public cloudId identifies the prism; it cannot reproduce the opening key by itself. Reopening through this path requires the same account signature over dataprism:key:${cloudId}, or dataprism:key:${cloudId}:${password} when a password was used, and the same encryption configuration. The password is an additional secret in the signed message. Without it, someone who obtains the account's signing authority could reproduce the signature and opening key.

SDK callers can instead provide a secret through DataPrismKey.fromSecret and retain it themselves. The Prism opening key seals metadata, provider settings and file indexes. It is separate from the customer-held tenant scope keys used for file encryption and the stable key used for scoped filename addressing; see Tenant scope keys.

dataprism.encryption

{ "curve": "secp256k1", "algorithm": "aes-256-gcm" }

• curve: "secp256k1" | "x25519" | "ed25519"
• algorithm: "aes-256-gcm" | "xchacha20"

These parameters define how the Prism opening key seals metadata, provider settings and file indexes. They are stored in clear so a reader knows how to open those slots; they do not supply the tenant scope keys for file content.

dataprism.metadata

{
  "name": "",
  "description": "",
  "addresses": { "0x...": "human-readable name" }
}

• name, description: prism information.
• addresses: the authorized owner and writer addresses, each mapped to a readable name.
• fileDataIdProfile: optional scoped filename-addressing profile. CloudStandard configured with fileDataIdScopeKey emits dataprism.file-data-id.hmac-sha256.v1 automatically. Constructors without that option retain legacy filename IDs. Unknown profiles are rejected.

This JSON is sealed with the parameters from dataprism.encryption.

dataprism.providers

A sealed JSON keyed by provider ID. It records the non-secret location of each customer-owned store and the customer-controlled endpoint that issues short-lived, object-scoped URLs.

{
  "aws_s3": {
    "service": "signed_url",
    "signerUrl": "https://storage.example.com/aws/sign",
    "region": "eu-west-1",
    "bucket": "acme-dataprism"
  },
  "cloudflare_r2": {
    "service": "signed_url",
    "signerUrl": "https://storage.example.com/r2/sign",
    "endpoint": "https://account-id.r2.cloudflarestorage.com",
    "bucket": "acme-dataprism-r2",
    "region": "auto"
  }
}

File index slots

In addition to the reserved slots above, each uploaded file creates a slot addressed by standard.fileId(filename). Without an addressing key this is the legacy keccak256(UTF8(filename)). With fileDataIdScopeKey, it is a domain-separated HMAC-SHA-256 over the canonical JSON of the NFC-normalized filename. The customer retains that stable addressing key independently of rotating file-encryption keys; see Scoped file identifiers.

The sealed index describes the reconstruction root, provider locations and coding parameters for the chunks and manifests stored at the providers. Legacy/V2 indexes remain supported. V3 adds versioned public-format descriptors and a randomized content commitment, but the index slot is still sealed: a V3 upload requires an explicit publicIndex option and scoped addressing. See V3 uploads for its requirements and File storage & resilience for the reconstruction layout.

Working with prisms in code

The SDK turns these concepts into a typed API: CloudStandard encodes and seals each slot, CloudReader reads and decrypts in one step, and PrismManager handles single-operation creation plus dedicated slot editors with a guard against overwriting reserved slots. See Cloud Standard slots.