Skip to main content

Delegate Key Management

Delegate keys are lightweight Ed25519 keys used for SDK authentication. They are registered onchain in a MemWalAccount and verified by the relayer on every request.

Why use delegate keys?​

  • Apps need a usable key for API calls without exposing the owner wallet
  • Users should not hand over the owner wallet for day-to-day memory access
  • Different apps or devices can each have their own delegate key with a descriptive label

How to manage a delegate key​

Follow these steps to generate, register, use, and revoke a delegate key:

1. Generate a delegate keypair​

Use the SDK's generateDelegateKey() helper to create a new Ed25519 keypair:

Source: contract/delegate-key-management.md 
import { generateDelegateKey } from "@mysten-incubation/memwal/account";

const delegate = await generateDelegateKey();
// delegate.privateKey — hex string, store securely
// delegate.publicKey — 32-byte Uint8Array
// delegate.suiAddress — derived Sui address (0x...)

2. Register the public key onchain​

Only the account owner can add delegate keys:

Source: contract/delegate-key-management.md 
import { addDelegateKey } from "@mysten-incubation/memwal/account";

await addDelegateKey({
  packageId: "0x...",
  registryId: "0x...",
  accountId: "0x...",
  publicKey: delegate.publicKey,
  label: "MacBook Pro",
  suiPrivateKey: "suiprivkey1...", // or walletSigner
});

3. Use the private key in the SDK​

Source: contract/delegate-key-management.md 
import { MemWal } from "@mysten-incubation/memwal";

const memwal = MemWal.create({
  key: delegate.privateKey,
  accountId: "0x...",
});

4. Revoke the delegate key​

Removing a delegate key prevents future relayer access from that key:

Source: contract/delegate-key-management.md 
import { removeDelegateKey } from "@mysten-incubation/memwal/account";

await removeDelegateKey({
  packageId: "0x...",
  registryId: "0x...",
  accountId: "0x...",
  publicKey: delegate.publicKey,
  suiPrivateKey: "suiprivkey1...", // or walletSigner
});

What are the delegate key limits?​

  • Each account supports up to 20 delegate keys
  • Each delegate key must be a valid 32-byte Ed25519 public key
  • Duplicate keys are rejected (error code 0)
  • Only the account owner can add or remove delegate keys

What happens when you deactivate an account?​

An account owner can deactivate (freeze) their account. When deactivated:

  • Seal decryption access is denied for all keys (owner and delegates)
  • New delegate keys cannot be added; the owner might still remove compromised keys
  • The owner can reactivate the account unless an AdminCap quarantine is active

This is useful as an emergency kill switch if a key is compromised.

How quickly does delegate key removal take effect?​

The relayer caches each successful delegate key verification for up to 30 seconds, keyed by account and public key. After you remove a key onchain, that key can keep authenticating at the relayer for at most 30 seconds, until its cached verification expires. Removal also does not take back plaintext the delegate already read or decryption keys it already obtained.