Skip to main content

Ownership and Delegates

Walrus Memory puts you in full control of your memory. Programmable permissions and explicit ownership define how memory is shared, accessed, and updated, with delegate access for agents and workflows.

Ownership​

Memory content is stored on Walrus under the owner address recorded in a MemWalAccount. The account registry permits one account per owner address. The SDK's accountId is the account object ID, not the wallet address.

For the relayer-backed client, key is a registered delegate private key used to authenticate requests. Its derived wallet address identifies the delegate, not the account owner. The relayer resolves the owner from the selected account.

Source: fundamentals/concepts/ownership-and-access.md 
const memwal = MemWal.create({
  key: process.env.MEMWAL_PRIVATE_KEY!, // delegate private key
  accountId: process.env.MEMWAL_ACCOUNT_ID!, // MemWalAccount object ID
  serverUrl: process.env.MEMWAL_SERVER_URL,
  namespace: "personal",
});

In a multi-tenant server app, the operator owns the account and the memories stored through it. An end user signs in with a wallet to prove identity to that application. Signing in does not create an account for the user or give the user ownership of those memories.

Ownership is separate from payment; see Managed relayer costs.

Delegates​

A delegate is a keypair registered on the account by its owner. The delegate signs requests, and its authority comes from that registration. The owner can add and remove delegates without giving them the owner wallet key.

This enables 2 use cases:

  • Agent access: give each agent a separate key so you can label and revoke it individually.
  • Service access: authorize a backend to read and write memory under the owner's account without handing over account-management credentials.
warning

Delegate keys are not scoped to a namespace or a read-only subset of memory. An authorized delegate can access memories across every namespace in the account. Namespaces organize data and scope queries; a multi-tenant application must authenticate users and choose the allowed namespace on its server.

Source: fundamentals/concepts/ownership-and-access.md

Access control enforcement​

Account authorization and application-user authorization operate at different levels:

  • The owner's wallet address controls the account and delegate registrations onchain.
  • The relayer verifies that the signing delegate is authorized for the selected account before serving memory requests.
  • The Seal contract policy checks the owner or registered delegate before releasing decryption keys.
  • An application using one account for many users enforces each user's namespace access in its own server. The account contract does not distinguish those application users.

Removing a delegate increments the account's rotation counter, which produces a new encryption identity used by writes after the removal; it does not re-encrypt existing memories. It does not take back plaintext the delegate already read, or decryption keys it already obtained. Keep the owner key secure so you can manage and replace delegate keys. See Delegate key management for revocation steps.

What happens to encryption when you remove a delegate?​

The encryption identity is the Seal key ID. Every key ID ends with BCS(owner_address) ‖ BCS(access_counter_version). access_counter_version is a rotation counter on the MemWalAccount. Removing a delegate or freezing the account increments the counter. The new counter produces a different identity, and therefore a different key that the removed delegate cannot fetch. Writes after the removal use the new identity. Encrypt under a counter that you read fresh from chain, and never under a cached value. seal_approve rejects any counter above the account's current one, so an authorized delegate cannot pre-fetch keys for future identities.

Rotation is forward-only. Memories written under an older counter stay readable with the older key. To retract them, you must re-encrypt them.

Register and remove delegates​

Create the account and a delegate key on the Walrus Memory dashboard. To register a delegate programmatically, the owner calls addDelegateKey with the delegate public key. To remove a delegate, use the dashboard or call removeDelegateKey from @mysten-incubation/memwal/account with the owner credentials. Keep the owner key offline, not on your application server.

The relayer rejects a delegate key that exists locally but is not registered on the selected account, or that is registered on a different account or network. For the full lifecycle, see Delegate key management.