feat(sdk)/docs: first-class trustless verification of a memory (verify() + guide)

[DrVelvetFog]

Summary

Walrus Memory's headline promise is verifiable, non-custodial memory — "verifiable integrity without centralized trust", "fully controlled by you" (SKILL.md / README). I went looking to confirm that property holds, and it genuinely does — I reconstructed a memory's full provenance from on-chain data + public Walrus with zero relayer trust. But there is no documented procedure and no SDK helper to actually do it. For a product whose core differentiator is trustless verifiability, that's a gap worth closing — and I'd be glad to contribute the fix.

What I verified (staging/testnet)

For a memory written via the SDK — blob_id = GybhBuKN6GY3C5Ct1oOR3bpDK4VqJd58bbhsk6V-orw, account 0x9c6caf5d…ad935:

1. Relayer-independent fetch. The blob downloads straight from the public Walrus aggregator —
   GET https://aggregator.walrus-testnet.walrus.space/v1/blobs/GybhBuKN…-orw → 200, 435 bytes — with no relayer in the path.
2. Encrypted at rest. The raw bytes contain no plaintext marker or secret (SEAL). ✅
3. On-chain provenance. The memory exists as a Walrus …::blob::Blob object whose on-chain Metadata (VecMap<String,String>) carries:
   • memwal_namespace, memwal_owner, memwal_package_id, and memwal_agent_id.
   • memwal_agent_id exactly equals the public_key of a DelegateKey registered on the MemWalAccount — cryptographically binding the blob to a key the account authorized.

So the whole chain — account → authorized delegate key → blob written by that key → namespace/owner → content-addressed encrypted bytes on Walrus — is independently checkable. The relayer is an index/availability convenience exactly as the docs imply; the gap is that nothing helps a user demonstrate it.

Proposal

1. memwal.verify(blobId) (or verifyMemory) that:
   • resolves the on-chain Blob + Metadata,
   • checks memwal_agent_id against the account's registered delegate keys,
   • confirms the blob is retrievable + content-addressed on Walrus,
   • returns a structured report, e.g. { ownerOk, agentKeyOk, namespace, onChain, walrusReachable }.
2. A short "Independently verify a memory" guide documenting the memwal_* Metadata schema and the chain → Walrus procedure, so the verifiability claim is demonstrable rather than asserted.

I'm happy to open a PR for (1) and/or (2) — glad to align on the API shape first.

Related finding: metadata privacy

While content is encrypted, memwal_namespace, memwal_owner, and memwal_agent_id are stored as public plaintext on-chain. Namespace names and per-agent write patterns are therefore world-readable. Apps that name namespaces after end-users/tenants (e.g. patient-12345, org-acme) would leak that. Worth a docs warning, and/or an option to store an opaque (hashed) namespace in the on-chain metadata for privacy-sensitive integrations.

[ducnmm]

Thanks — and it's great that you were able to reconstruct full provenance from on-chain data plus the public Walrus aggregator with zero relayer trust. That's exactly the property we want this to have.

To point you at the right thing: do you mean running your own relayer on your side (we have docs for that)? Or are you specifically after a lightweight, local way to verify a blob — i.e. a verify() SDK helper plus a short guide — without standing up any infrastructure?

If it's the latter, we'd be happy to take the PR — let us know which one you're after and we'll align on the shape.

[DrVelvetFog]

Definitely the latter — a lightweight, local verify() helper plus a short guide, no infra to stand up. That's the property I care about: a third party should be able to confirm a memory's provenance from public inputs only.

Worth calling out as the key design constraint: verify() should need no private key and no relayer — only the blobId, the accountId, and public endpoints (a Sui fullnode + the Walrus aggregator). That's what makes it a real trust-minimized check rather than a relayer round-trip. I already have this working end-to-end on testnet (the reconstruction in the issue above), so the PR is mostly packaging it into the SDK and writing it up.

Proposed shape (open to whatever fits your conventions):

// static — no credentials, no relayer
const report = await MemWal.verify(blobId, {
  accountId,                  // to check the delegate-key binding
  network: "testnet",         // or pass explicit URLs below
  suiRpcUrl,                   // optional override
  walrusAggregatorUrl,        // optional override
});

report = {
  ok: boolean,                // all hard checks passed
  onChain: boolean,           // Blob object resolved on Sui with memwal_* metadata
  agentKeyOk: boolean,        // memwal_agent_id is one of the account's registered DelegateKey pubkeys
  ownerOk: boolean,           // memwal_owner matches (when an expected owner is supplied)
  walrusReachable: boolean,   // blob retrievable from the public aggregator
  contentAddressed?: boolean, // recomputed Walrus id matches blobId (see Q3)
  namespace: string,
  metadata: Record<string, string>, // raw memwal_* map
}

Three things to align on before I open it:

1. Resolution path — from a Walrus blobId, how do you prefer to locate the on-chain Blob object? Scan the account/delegate's owned Blobs and match blob_id (what my proof-of-concept does), or have verify() also accept the Sui object id directly?
2. Placement — static MemWal.verify(), a standalone verifyMemory() export, or both?
3. Content-addressing depth — the trustless checks (on-chain binding + retrievability + metadata) need only your existing @mysten/sui RPC dep. A true content-address recompute (hashing the bytes back to the Walrus id) likely pulls in a Walrus encoding dependency — happy to include it, but I'd suggest landing the no-new-dep version first and adding contentAddressed as a follow-up unless you'd rather have it from the start.

I'll also fold in the "Independently verify a memory" guide (documenting the memwal_* metadata schema and the chain → Walrus procedure), plus a short note on the metadata-privacy point from the issue. I'll follow your contribution conventions (conventional commits, AI-usage disclosure) — just point me at any CONTRIBUTING specifics.

[DrVelvetFog]

Opened the PR as #335 (draft, based on dev). It's the local, public-inputs-only verification we landed on — verifyMemory() plus a thin MemWal.verify() static, a "verify a memory" guide, and a changeset; typecheck + build both pass. @mysten/sui is loaded dynamically (mirroring account.ts) so it stays out of the dependency-light default entry.

I left the three things we hadn't pinned down as inline questions on the PR, with the on-chain reads marked ALIGN-Q1 / ALIGN-Q3 so they're easy to tighten once you point me at the canonical schema:

1. blobId → Sui Blob object resolution (account-owned vs delegate-owned vs dynamic field) — I implemented both an objectId short-circuit and an owned-Blob scan.
2. Where DelegateKey pubkeys canonically live on MemWalAccount (content vector vs dynamic field) — I read both.
3. Content-address recompute (report.contentAddressed) now vs as a follow-up.