Walrus & Seal Integration

Encryption Model

Before upload, the content is encrypted client-side with a freshly generated 256-bit AES-GCM data encryption key (DEK). The DEK is then threshold-encrypted by the Seal key server network. Only the parties that Seal approves on-chain can reconstruct the DEK to decrypt the blob.

1. Generate a random DEK + IV client-side.
2. Encrypt the content blob with AES-GCM-256.
3. Upload the ciphertext to Walrus → receive a blobId and a registered Blob object on Sui.
4. The DEK + a SHA-256 content hash binding is encrypted by Seal under the Soul (or Memory / Skills) document ID.
5. The resulting Seal ciphertext, IV, file metadata, and content hash are stored in the DB as a sidecar.

Document ID Schemes

Seal ciphertext is bound to a deterministic document ID. The Move module verifies the document ID prefix matches the on-chain object IDs before approving decryption.

"soul-seal:" + version_byte(1) + soul_id_bytes(32) + nonce(16)

"soul-memory:" + version_byte(1) + memory_id_bytes(32) + timestamp_key_be(8) + nonce(16)

"soul-skill:" + version_byte(1) + skills_id_bytes(32) + skill_name_bytes + NUL + version_index_be(8) + nonce(16)

Sidecar Structure

The sidecar is a JSON object stored in the DB alongside each artifact. It contains everything the client needs to decrypt, excluding the DEK itself (which lives inside the Seal ciphertext).

{
  encryptedDek: string,   // base64 — Seal ciphertext of DEK + contentHash
  iv: string,             // base64 — 12-byte AES-GCM IV
  cipher: "AES-GCM-256",
  fileName: string,
  mimeType: string,
  contentHash: string,    // hex — SHA-256 of plaintext; bound inside encryptedDek
}

The contentHash is bound inside the Seal-encrypted DEK payload (DEK_BYTES || CONTENT_HASH_BYTES). After decryption the client verifies the decrypted hash matches the sidecar hash and then verifies the decrypted plaintext hashes to the same value — preventing substitution attacks.

Client-Side Sidecar Build

Upload flows encrypt in the browser, ask the wallet to pay Walrus storage through the upload relay, then build Seal sidecar objects after the on-chain TX exposes the final Soul/Memory/Skills/Assets object IDs. Mirror APIs only verify and store those sidecars; they do not receive raw DEK envelopes.

• The DEK and IV stay in browser memory plus short-lived recovery state until mirror sync succeeds.
• The browser Seal client encrypts the DEK with the document ID bound to the newly minted object.
• The mirror API rejects private artifacts without a sidecar object bound to the expected document ID.
• Wallet signing does not start until the shared Walrus cost review is confirmed.

Client Decryption Flow

1. Call the access API endpoint — it returns the sidecar, Walrus blob URL, Seal server config, and an approval policy (module + function + required object IDs).
2. Create a SessionKey with SessionKey.create, sign the personal message with the viewer wallet.
3. Build the approval transaction bytes matching the policy (owner, granted-agent, or allowlisted path).
4. Fetch the encrypted blob from Walrus.
5. Call SealClient.decrypt with the sidecar encryptedDek — the Seal key servers verify the approval TX before releasing key shares.
6. AES-GCM decrypt the blob with the recovered DEK + IV.
7. Verify the plaintext SHA-256 matches the bound contentHash.