Confidential transfer for agents

SolKnife's browser UI keeps the ElGamal and AES keys inside a Web Worker so they never reach the main page's JavaScript context, let alone the network. An agent that replicates the cryptography in Node has its process memory holding those keys for the duration of the operation. That is a real custody extension. Treat the agent runtime accordingly: isolated, ephemeral, not shared with other tenants.

This is the same trade-off any non-custodial wallet faces when it stops being a hardware device. We document it; we don't hide it.

1. Build a deterministic seed message (per token account) and sign it with the wallet's Ed25519 key. Derive the ElGamal keypair and the AES AeKeyfrom that signature, using the SPL Token CLI standard.
2. Fetch the current confidential-transfer state via /api/confidential-transfer/state (also exposed as the ct.state MCP tool). Feed the keys plus the live ciphertexts into @solana/zk-sdk to generate the proofs.
3. Call the matching MCP build tool with the proof bytes (base64). Sign the returned transaction with your wallet. POST the signed bytes to ct.submit.

The seed messages match @solana/zk-sdk's built-in ElGamalKeypair.signerMessage and AeKey.signerMessage: a confidential balance configured through SolKnife stays decryptable in the SPL Token CLI, and any tool using the same scheme stays interoperable.

The exact messages, per token account address:

// ElGamal seed
"ElGamalSecretKey" || <token_account_pubkey_bytes>

// AES (AeKey) seed
"AeKey" || <token_account_pubkey_bytes>

Determinism is safety. A wallet whose signMessage is non-deterministic produces different keys across sessions and permanently locks the user out of their own confidential balance. Sign each seed twice during onboarding; if the signatures differ, refuse to continue. The browser UI enforces this; an agent must too.

Five proof types appear across the build endpoints. All byte lengths are post-encoding raw bytes; the wire format is base64 on the JSON envelope. Lengths here are taken from the on-chain ZK ElGamal Proof Program (Solana mainnet) at the time of writing.

Some build endpoints also expect ElGamal ciphertexts or AES decryptables alongside the proofs. Lengths:

What every CT MCP build tool wants on top of the obvious params:

The three context-state accounts on Withdraw and Transfer are short-lived: each proof verification consumes one, the on-chain instruction marks them closeable, and ct.orphans.build sweeps them if a saga aborts mid-flight.

Install the canonical Solana SDK:

npm install @solana/zk-sdk @solana/web3.js

Derive the ElGamal + AES keys from a wallet keypair (full custody case: the agent has the secret key, not a remote-signing wallet):

import { Keypair, PublicKey } from "@solana/web3.js";
import { sign } from "@noble/curves/ed25519";
import { ElGamalKeypair, AeKey } from "@solana/zk-sdk";

const ELGAMAL_SEED = new TextEncoder().encode("ElGamalSecretKey");
const AES_SEED     = new TextEncoder().encode("AeKey");

function seed(label: Uint8Array, tokenAccount: PublicKey): Uint8Array {
  const ta = tokenAccount.toBytes();
  const out = new Uint8Array(label.length + ta.length);
  out.set(label, 0);
  out.set(ta, label.length);
  return out;
}

async function deriveKeys(
  wallet: Keypair,
  tokenAccount: PublicKey,
): Promise<{ elgamal: ElGamalKeypair; aes: AeKey }> {
  const elgamalSig = sign(seed(ELGAMAL_SEED, tokenAccount), wallet.secretKey.subarray(0, 32));
  const aesSig     = sign(seed(AES_SEED,     tokenAccount), wallet.secretKey.subarray(0, 32));
  return {
    elgamal: ElGamalKeypair.fromSignature(elgamalSig),
    aes:     AeKey.fromSignature(aesSig),
  };
}

For a Transfer, fetch state, generate the three proofs + ciphertexts, then call the build endpoint:

import {
  ProofGeneration, // module from @solana/zk-sdk that builds transfer proofs
} from "@solana/zk-sdk";

const stateRes = await fetch(
  `https://solknife.xyz/api/confidential-transfer/state?owner=${owner}&mint=${mint}`,
);
const state = (await stateRes.json()).data;

const transferAmount = 1_000_000n; // u64, in token base units
const { elgamal, aes } = await deriveKeys(wallet, new PublicKey(state.tokenAccount));

const proofs = ProofGeneration.transfer({
  sourceElgamalKeypair: elgamal,
  destinationElgamalPubkey: state.destination.elgamalPubkey,
  auditorElgamalPubkey:    state.mint.auditorElgamalPubkey, // may be null
  sourceAesKey: aes,
  currentAvailableCiphertext: state.sourceAvailableCiphertext,
  currentAvailable: state.sourceAvailable,
  transferAmount,
});

// Three transient context-state keypairs (rent funded; closed after verify)
const equalityCtx = Keypair.generate();
const validityCtx = Keypair.generate();
const rangeCtx    = Keypair.generate();

const buildRes = await fetch(
  "https://solknife.xyz/api/confidential-transfer/transfer/build",
  {
    method: "POST",
    headers: { "content-type": "application/json", cookie: sessionCookie },
    body: JSON.stringify({
      owner,
      mint,
      destinationTokenAccount: state.destination.tokenAccount,
      equalityProof:                 b64(proofs.equality),
      validityProof:                 b64(proofs.validity3Handles),
      rangeProof:                    b64(proofs.rangeU128),
      newSourceDecryptableAvailable: b64(proofs.newAesCiphertext),
      auditorCiphertextLo:           b64(proofs.auditorCiphertextLo),
      auditorCiphertextHi:           b64(proofs.auditorCiphertextHi),
      equalityContextAccount: equalityCtx.publicKey.toBase58(),
      validityContextAccount: validityCtx.publicKey.toBase58(),
      rangeContextAccount:    rangeCtx.publicKey.toBase58(),
    }),
  },
);
const { signedTransactions, lastValidBlockHeight } = (await buildRes.json()).data;
// ... sign each tx with [wallet, equalityCtx, validityCtx, rangeCtx]
// ... POST to /api/confidential-transfer/submit

The above is canonical, not copy-paste-ready: the exact field names on @solana/zk-sdk ProofGeneration.transfer may differ slightly across SDK versions. Pin the SDK version, read its TypeScript declarations, and confirm the field name to byte-length mapping before shipping.

Before configuring an account for the first time, the agent MUST verify the wallet's signMessageis deterministic. SolKnife's browser UI does this; an agent must too. The check:

function isWellShapedSignature(sig: Uint8Array): boolean {
  return sig instanceof Uint8Array && sig.length === 64;
}

async function checkDeterminism(
  wallet: Keypair,
  tokenAccount: PublicKey,
): Promise<boolean> {
  const m = seed(ELGAMAL_SEED, tokenAccount);
  const a = sign(m, wallet.secretKey.subarray(0, 32));
  const b = sign(m, wallet.secretKey.subarray(0, 32));
  if (!isWellShapedSignature(a) || !isWellShapedSignature(b)) return false;
  return Buffer.compare(a, b) === 0;
}

A non-deterministic signer locks the user out of their own confidential balance forever. If the check fails, refuse to configure.

A Token-2022 mint configured with an auditorElGamalPubkey requires every transfer to additionally encrypt the amount to the auditor. The auditor can then decrypt all confidential transfers using its own ElGamal secret. The ct.state read tool tells you whether the mint has one and what its pubkey is. If present, your transfer proof must produce auditorCiphertextLo and Hi; if absent, the field is still sent but encrypts under a zeroed pubkey.

• How confidential transfer works on Solana — the protocol explainer the browser UI links to
• solana-program-library / zk-token-sdk — the upstream Rust + WASM proof generator
• @solana/zk-sdk on npm — Node + browser-compatible wrapper
• /api/manifest — the machine-readable tool inventory (every CT build tool listed)