@meddleware/docs 0.0.1

package/docs/sealed-storage/reference.md

@@ -0,0 +1,79 @@
+# Sealed Storage — reference
+
+Shapes and identifiers behind Sealed Storage. The **exhaustive, always-current API** is auto-generated
+from the `@meddleware/seal-client` SDK — see [SDK API](#sdk-api).
+
+## Deployed identifiers (testnet)
+
+| Thing | ID |
+| --- | --- |
+| `seal_policies` package | `0x9f0563bfe42fbd29932cd280cc47efe17f5339b4dc569eb110114665eecc231e` |
+
+Mainnet is pending; the app is enabled by configuration once the package and key-server committee are
+available.
+
+## The manifest
+
+The portable pointer produced when you seal a file. It contains **no secrets**:
+
+```json
+{
+  "policyType": "nft-gate",     // which policy sealed this content
+  "id": "…",                     // Seal identity (hex) — required to decrypt; cannot be recomputed
+  "blobId": "…",                 // Walrus blob id of the ciphertext
+  "network": "testnet",
+  "params": { "gateId": "0x…" }, // non-secret policy params (e.g. which gate)
+  "label": "optional human label"
+}
+```
+
+Keep the manifest safe — its `id` (the encryption identity) is needed to locate and decrypt the
+ciphertext.
+
+## Policy identities
+
+Each policy encodes its access condition into the encryption **identity**. Conceptually:
+
+| Policy | Identity layout | On-chain check |
+| --- | --- | --- |
+| `nft-gate` | `[32-byte gate id][random nonce]` | Holder of a valid pass for that gate |
+| `time-lock` | `[8-byte unlock time][random nonce]` | On-chain clock ≥ unlock time |
+
+The gate id in the identity namespaces the content: a pass for gate A cannot decrypt gate B.
+
+## Threshold committee
+
+Decryption uses a **t-of-n** committee of key servers (e.g. 2 of 3). Encryption targets all
+configured servers; decryption needs a threshold of them to release shares. A short-lived **session
+key** (signed once per session) authorises the release.
+
+## Discoverable content pointer (optional)
+
+Publishing a pointer for gate-unlockable content emits an on-chain event so pass-holders can discover
+it:
+
+```json
+{
+  "contentId": "0x…",
+  "gateId": "0x…",
+  "blobId": "…",
+  "sealId": "…",
+  "label": "…",
+  "publisher": "0x…"
+}
+```
+
+The pointer is public and grants nothing on its own — confidentiality stays enforced by Seal + the
+gate.
+
+## SDK API
+
+The full `@meddleware/seal-client` API — the `SealController`, the policy registry, both built-in
+providers, and the manifest/byte helpers — is generated here:
+
+- [Seal client API](./api/)
+
+::: tip Writing your own policy?
+That's `dev.meddleware.co.uk` material (a `seal_policies` Move module + a matching client provider),
+planned in the package docs.
+:::

package/docs/sealed-storage/using.md

@@ -0,0 +1,55 @@
+# Sealed Storage — using it
+
+A walkthrough of the [Sealed Storage app](https://sui-seal.meddleware.co.uk). You'll need a
+[Sui wallet](/getting-started); browsing policies needs nothing, but decrypting requires a signature.
+
+## Encrypt and store
+
+1. Open the **Encrypt** tab.
+2. **Choose a file.**
+3. **Pick a policy** (see [Policies](/sealed-storage/policies)). The form adapts to the policy — for
+   an Access Gate policy you select the gate; for a time-lock you pick an unlock time.
+4. Encrypt. The file is sealed **in your browser** and the ciphertext is uploaded to Walrus.
+5. You receive a **manifest** — save or share it. It's the pointer needed to decrypt later, and it
+   holds no secrets.
+
+::: tip Choose the policy deliberately
+The policy is baked into the encryption — you can't change who's allowed after the fact without
+re-encrypting. Pick the right gate or unlock time up front.
+:::
+
+## Share
+
+Send the **manifest** to whoever should be able to decrypt. Because access is enforced on-chain, you
+can share it openly: only those who satisfy the policy (e.g. hold a valid pass, or wait until the
+unlock time) can actually decrypt.
+
+## Decrypt / unlock
+
+1. Open the **Decrypt** (or **Unlock**) tab and provide the **manifest**.
+2. For a gate policy, provide the **pass NFT** you hold; for a time-lock, just proceed once the time
+   has passed.
+3. **Sign one wallet message.** This mints a short-lived **session key** — you won't be prompted again
+   until it expires.
+4. If the on-chain check passes, a threshold of key servers releases their shares and the file is
+   decrypted locally. If not (no valid pass, too early), decryption is refused.
+
+## Publishing discoverable content (optional)
+
+For Access Gate content, you can optionally **publish a pointer on-chain** so a gate's pass-holders
+can *discover* your sealed content without you sending each of them a manifest. The pointer is public
+and grants nothing on its own — confidentiality is still enforced by the encryption and the gate.
+
+## Common questions
+
+**Can Meddleware read my file?** No. Encryption happens in your browser and the keys are split across
+independent key servers. Meddleware never holds key material.
+
+**What if a key server is down?** The committee is threshold-based (e.g. 2 of 3), so it tolerates some
+servers being unavailable.
+
+**I lost the manifest — can I recover the file?** The manifest holds no secret, but you need it (its
+**identity** value in particular) to locate and decrypt the ciphertext. Keep it safe.
+
+**Why did decryption fail?** The on-chain policy said no — commonly: you don't hold a valid pass for
+the gate, or a time-lock hasn't elapsed yet.

package/docs/walrus-storage/api/classes/RetryableWalrusClientError.md

@@ -0,0 +1,101 @@
+# Class: RetryableWalrusClientError
+
+Defined in: @meddleware/walrus-client/node\_modules/@mysten/walrus/dist/error.d.mts:3
+
+## Extends
+
+- `WalrusClientError`
+
+## Constructors
+
+### Constructor
+
+> **new RetryableWalrusClientError**(`message?`): `RetryableWalrusClientError`
+
+Defined in: typescript/lib/lib.es5.d.ts:1080
+
+#### Parameters
+
+##### message?
+
+`string`
+
+#### Returns
+
+`RetryableWalrusClientError`
+
+#### Inherited from
+
+`WalrusClientError.constructor`
+
+### Constructor
+
+> **new RetryableWalrusClientError**(`message?`, `options?`): `RetryableWalrusClientError`
+
+Defined in: typescript/lib/lib.es5.d.ts:1080
+
+#### Parameters
+
+##### message?
+
+`string`
+
+##### options?
+
+`ErrorOptions`
+
+#### Returns
+
+`RetryableWalrusClientError`
+
+#### Inherited from
+
+`WalrusClientError.constructor`
+
+## Properties
+
+### cause?
+
+> `optional` **cause?**: `unknown`
+
+Defined in: typescript/lib/lib.es2022.error.d.ts:24
+
+#### Inherited from
+
+`WalrusClientError.cause`
+
+***
+
+### message
+
+> **message**: `string`
+
+Defined in: typescript/lib/lib.es5.d.ts:1075
+
+#### Inherited from
+
+`WalrusClientError.message`
+
+***
+
+### name
+
+> **name**: `string`
+
+Defined in: typescript/lib/lib.es5.d.ts:1074
+
+#### Inherited from
+
+`WalrusClientError.name`
+
+***
+
+### stack?
+
+> `optional` **stack?**: `string`
+
+Defined in: typescript/lib/lib.es5.d.ts:1076
+
+#### Inherited from
+
+`WalrusClientError.stack`

package/docs/walrus-storage/api/classes/WalrusFile.md

@@ -0,0 +1,111 @@
+# Class: WalrusFile
+
+Defined in: @meddleware/walrus-client/node\_modules/@mysten/walrus/dist/files/file.d.mts:7
+
+## Constructors
+
+### Constructor
+
+> **new WalrusFile**(`__namedParameters`): `WalrusFile`
+
+Defined in: @meddleware/walrus-client/node\_modules/@mysten/walrus/dist/files/file.d.mts:14
+
+#### Parameters
+
+##### \_\_namedParameters
+
+###### reader
+
+`FileReader`
+
+#### Returns
+
+`WalrusFile`
+
+## Methods
+
+### bytes()
+
+> **bytes**(): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+Defined in: @meddleware/walrus-client/node\_modules/@mysten/walrus/dist/files/file.d.mts:21
+
+#### Returns
+
+`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+***
+
+### getIdentifier()
+
+> **getIdentifier**(): `Promise`\<`string`\>
+
+Defined in: @meddleware/walrus-client/node\_modules/@mysten/walrus/dist/files/file.d.mts:19
+
+#### Returns
+
+`Promise`\<`string`\>
+
+***
+
+### getTags()
+
+> **getTags**(): `Promise`\<`Record`\<`string`, `string`\>\>
+
+Defined in: @meddleware/walrus-client/node\_modules/@mysten/walrus/dist/files/file.d.mts:20
+
+#### Returns
+
+`Promise`\<`Record`\<`string`, `string`\>\>
+
+***
+
+### json()
+
+> **json**(): `Promise`\<`any`\>
+
+Defined in: @meddleware/walrus-client/node\_modules/@mysten/walrus/dist/files/file.d.mts:23
+
+#### Returns
+
+`Promise`\<`any`\>
+
+***
+
+### text()
+
+> **text**(): `Promise`\<`string`\>
+
+Defined in: @meddleware/walrus-client/node\_modules/@mysten/walrus/dist/files/file.d.mts:22
+
+#### Returns
+
+`Promise`\<`string`\>
+
+***
+
+### from()
+
+> `static` **from**(`options`): `WalrusFile`
+
+Defined in: @meddleware/walrus-client/node\_modules/@mysten/walrus/dist/files/file.d.mts:9
+
+#### Parameters
+
+##### options
+
+###### contents
+
+`Uint8Array`\<`ArrayBufferLike`\> \| `Blob`
+
+###### identifier
+
+`string`
+
+###### tags?
+
+`Record`\<`string`, `string`\>
+
+#### Returns
+
+`WalrusFile`

package/docs/walrus-storage/api/functions/buildAccessProofToken.md

@@ -0,0 +1,21 @@
+# Function: buildAccessProofToken()
+
+> **buildAccessProofToken**(`proof`): `string`
+
+Defined in: @meddleware/walrus-client/src/access.ts:43
+
+Encode a proof as the base64(JSON) Bearer token the relay auth header carries.
+
+## Parameters
+
+### proof
+
+`AccessProof`
+
+## Returns
+
+`string`
+
+## Throws
+
+if `JSON.stringify` or `btoa` is unavailable in the environment.

package/docs/walrus-storage/api/functions/certifyBlobTransaction.md

@@ -0,0 +1,30 @@
+# Function: certifyBlobTransaction()
+
+> **certifyBlobTransaction**(`client`, `options`): `Transaction`
+
+Defined in: @meddleware/walrus-client/src/manage.ts:95
+
+Build (but do not sign) a transaction that certifies an already-uploaded blob, for a browser
+wallet to sign. Lets an upload that was registered + uploaded (and paid for) but not certified —
+e.g. the user dismissed the certify prompt — be completed later without re-uploading: certify is a
+plain owner transaction that submits the stored availability certificate, validated on-chain.
+
+## Parameters
+
+### client
+
+`ClientWithExtensions`
+
+A Walrus-extended client.
+
+### options
+
+[`CertifyOptions`](../interfaces/CertifyOptions.md)
+
+The blob ids + the base64 certificate captured at upload time.
+
+## Returns
+
+`Transaction`
+
+An unsigned `Transaction`.

package/docs/walrus-storage/api/functions/createBlobUploadFlow.md

@@ -0,0 +1,30 @@
+# Function: createBlobUploadFlow()
+
+> **createBlobUploadFlow**(`client`, `contents`): `WriteBlobFlow`
+
+Defined in: @meddleware/walrus-client/src/upload.ts:141
+
+Begin a multi-step raw-blob upload flow suitable for browser wallet signing.
+
+Drive the returned flow:
+```ts
+await flow.encode()
+const regTx = flow.register({ owner, epochs, deletable }) // wallet signs + executes
+await flow.upload({ digest })                              // digest of regTx
+const certTx = flow.certify()                              // wallet signs + executes
+const { blobId } = await flow.getBlob()                   // use walrusBlobUrl(network, blobId)
+```
+
+## Parameters
+
+### client
+
+`ClientWithExtensions`
+
+### contents
+
+`Uint8Array`
+
+## Returns
+
+`WriteBlobFlow`

package/docs/walrus-storage/api/functions/createRelayAccessToken.md

@@ -0,0 +1,45 @@
+# Function: createRelayAccessToken()
+
+> **createRelayAccessToken**(`opts`): `Promise`\<`string`\>
+
+Defined in: @meddleware/walrus-client/src/access.ts:69
+
+One-shot: fetch a challenge, sign it with the wallet, and return the encoded proof token
+to pass as `createWalrusClient({ uploadRelayAuthToken })`. For single-use gates, supply
+the `consumeDigest` of the on-chain consume transaction.
+
+## Parameters
+
+### opts
+
+#### address
+
+`string`
+
+#### consumeDigest?
+
+`string`
+
+#### relayHost
+
+`string`
+
+#### sign
+
+[`PersonalMessageSigner`](../type-aliases/PersonalMessageSigner.md)
+
+#### signal?
+
+`AbortSignal`
+
+## Returns
+
+`Promise`\<`string`\>
+
+## Throws
+
+if the challenge fetch fails.
+
+## Throws
+
+if the wallet signer rejects the message.

package/docs/walrus-storage/api/functions/createUploadFlow.md

@@ -0,0 +1,30 @@
+# Function: createUploadFlow()
+
+> **createUploadFlow**(`client`, `contents`, `identifier`, `options?`): `WriteFilesFlow`
+
+Defined in: @meddleware/walrus-client/src/upload.ts:90
+
+Begin a multi-step quilt upload flow suitable for browser wallet signing.
+The caller drives the flow: encode → register (wallet signs) → upload → certify (wallet signs).
+
+## Parameters
+
+### client
+
+`ClientWithExtensions`
+
+### contents
+
+`Uint8Array`
+
+### identifier
+
+`string`
+
+### options?
+
+[`UploadOptions`](../type-aliases/UploadOptions.md) = `{}`
+
+## Returns
+
+`WriteFilesFlow`

package/docs/walrus-storage/api/functions/createWalrusClient.md

@@ -0,0 +1,23 @@
+# Function: createWalrusClient()
+
+> **createWalrusClient**(`__namedParameters?`): `ClientWithExtensions`\<\{ `walrus`: `WalrusClient`; \}, `SuiGrpcClient`\>
+
+Defined in: @meddleware/walrus-client/src/client.ts:116
+
+Create a Walrus client pre-configured for the given network and relay options.
+
+## Parameters
+
+### \_\_namedParameters?
+
+[`CreateWalrusClientOptions`](../type-aliases/CreateWalrusClientOptions.md) = `{}`
+
+## Returns
+
+`ClientWithExtensions`\<\{ `walrus`: `WalrusClient`; \}, `SuiGrpcClient`\>
+
+## Example
+
+```ts
+const client = createWalrusClient({ network: 'testnet' })
+```

package/docs/walrus-storage/api/functions/estimateStorageCost.md

@@ -0,0 +1,35 @@
+# Function: estimateStorageCost()
+
+> **estimateStorageCost**(`client`, `size`, `epochs`): `Promise`\<[`StorageCost`](../interfaces/StorageCost.md)\>
+
+Defined in: @meddleware/walrus-client/src/manage.ts:124
+
+Estimate the on-chain storage cost of a blob, so the UI can price a chosen reservation or extension
+duration. Thin wrapper over the SDK's `walrus.storageCost(size, epochs)` — kept here so Vue layers
+(which must not import `@mysten/walrus`) can price durations through the injected client.
+
+## Parameters
+
+### client
+
+`ClientWithExtensions`
+
+A Walrus-extended client.
+
+### size
+
+`number`
+
+Unencoded blob size in bytes.
+
+### epochs
+
+`number`
+
+Number of epochs to price (reservation length, or epochs added on extend).
+
+## Returns
+
+`Promise`\<[`StorageCost`](../interfaces/StorageCost.md)\>
+
+Storage/write/total cost in MIST.

package/docs/walrus-storage/api/functions/extendBlobLifetime.md

@@ -0,0 +1,40 @@
+# Function: extendBlobLifetime()
+
+> **extendBlobLifetime**(`client`, `blobObjectId`, `signer`, `options`): `Promise`\<\{ `digest`: `string`; \}\>
+
+Defined in: @meddleware/walrus-client/src/manage.ts:39
+
+Extend a blob's storage lifetime on-chain (Node.js — signs and executes).
+Since Walrus blobs expire, call this before expiry to prevent data loss.
+
+## Parameters
+
+### client
+
+`ClientWithExtensions`
+
+A Walrus-extended client.
+
+### blobObjectId
+
+`string`
+
+The on-chain Blob object id (not the blob id).
+
+### signer
+
+`Signer`
+
+The keypair paying for and authorising the extension.
+
+### options
+
+[`ExtendOptions`](../type-aliases/ExtendOptions.md)
+
+Add `epochs` more, or extend to an absolute `endEpoch`.
+
+## Returns
+
+`Promise`\<\{ `digest`: `string`; \}\>
+
+The executed transaction digest.

package/docs/walrus-storage/api/functions/extendBlobLifetimeTransaction.md

@@ -0,0 +1,34 @@
+# Function: extendBlobLifetimeTransaction()
+
+> **extendBlobLifetimeTransaction**(`client`, `blobObjectId`, `options`): `Promise`\<`Transaction`\>
+
+Defined in: @meddleware/walrus-client/src/manage.ts:62
+
+Build (but do not sign) a blob-lifetime-extension transaction for a browser
+wallet to sign. Browser counterpart of [extendBlobLifetime](extendBlobLifetime.md).
+
+## Parameters
+
+### client
+
+`ClientWithExtensions`
+
+A Walrus-extended client.
+
+### blobObjectId
+
+`string`
+
+The on-chain Blob object id.
+
+### options
+
+[`ExtendOptions`](../type-aliases/ExtendOptions.md)
+
+Add `epochs` more, or extend to an absolute `endEpoch`.
+
+## Returns
+
+`Promise`\<`Transaction`\>
+
+An unsigned `Transaction`.

package/docs/walrus-storage/api/functions/fetchOwnedWalrusBlobs.md

@@ -0,0 +1,34 @@
+# Function: fetchOwnedWalrusBlobs()
+
+> **fetchOwnedWalrusBlobs**(`suiClient`, `walrusClient`, `owner`): `Promise`\<[`OwnedBlob`](../type-aliases/OwnedBlob.md)[]\>
+
+Defined in: @meddleware/walrus-client/src/query.ts:41
+
+Return all Walrus blobs owned by `owner`. Resolves the on-chain Blob struct
+type dynamically via `getBlobType()`, so no package addresses are hardcoded.
+
+## Parameters
+
+### suiClient
+
+`ClientWithCoreApi`
+
+A Sui client exposing the unified core API (`SuiGrpcClient`).
+
+### walrusClient
+
+`ClientWithExtensions`
+
+A Walrus-extended client (see [createWalrusClient](createWalrusClient.md)).
+
+### owner
+
+`string`
+
+The address whose owned blobs to enumerate.
+
+## Returns
+
+`Promise`\<[`OwnedBlob`](../type-aliases/OwnedBlob.md)[]\>
+
+The owner's blobs; entries whose fields cannot be parsed are skipped.