Signer Backends

WALLET_SIGNER_BACKEND=encrypted-file|memory|kms|hsm|mpc

WALLET_SIGNER_BACKEND=encrypted-file
WALLET_KEY_ENCRYPTION_SECRET=your-secret-here  # Required
WALLET_ENGINE_DATA_DIR=/path/to/data           # Optional

// From services/wallet-engine/src/key-provider/encrypted-file-key-provider.ts

export class EncryptedFileKeyProvider implements KeyProvider {
  async save(walletId: string, keypair: Keypair): Promise<void> {
    const keyFile = path.join(this.keysDir, `${walletId}.json`);
    const secretBytes = JSON.stringify(Array.from(keypair.secretKey));
    const encrypted = encryptText(secretBytes, this.encryptionSecret);
    await fs.writeFile(keyFile, encrypted, 'utf8');
  }

  async load(walletId: string): Promise<Keypair> {
    const keyFile = path.join(this.keysDir, `${walletId}.json`);
    const encrypted = await fs.readFile(keyFile, 'utf8');
    const secretBytes = JSON.parse(decryptText(encrypted, this.encryptionSecret));
    return Keypair.fromSecretKey(Uint8Array.from(secretBytes));
  }
}

{
  "iv": "base64-encoded-iv",
  "encrypted": "base64-encoded-ciphertext",
  "authTag": "base64-encoded-auth-tag"
}

$WALLET_ENGINE_DATA_DIR/keys/{walletId}.json

services/wallet-engine/data/keys/
├── f47ac10b-58cc-4372-a567-0e02b2c3d479.json
├── 9d2c8f6e-4b1a-4c3d-8e5f-6a7b8c9d0e1f.json
└── ...

WALLET_SIGNER_BACKEND=memory
# No additional configuration required

// From services/wallet-engine/src/key-provider/memory-key-provider.ts

export class MemoryKeyProvider implements KeyProvider {
  private readonly keys = new Map<string, Keypair>();

  async save(walletId: string, keypair: Keypair): Promise<void> {
    this.keys.set(walletId, keypair);
  }

  async load(walletId: string): Promise<Keypair> {
    const keypair = this.keys.get(walletId);
    if (!keypair) {
      throw new Error(`Memory key provider: wallet ${walletId} not found`);
    }
    return keypair;
  }
}

WALLET_SIGNER_BACKEND=kms
WALLET_KMS_MASTER_SECRET=your-master-secret  # Required
WALLET_KMS_KEY_ID=wallet-engine-kms-key      # Optional (default shown)

// From services/wallet-engine/src/key-provider/kms-key-provider.ts

async save(walletId: string, keypair: Keypair): Promise<void> {
  const dataKey = randomBytes(32).toString('base64');
  const wrappedDataKey = encryptText(dataKey, this.secretForWrap());
  const encryptedSecret = encryptText(
    Buffer.from(keypair.secretKey).toString('base64'),
    dataKey
  );
  
  const payload: KmsEnvelope = {
    v: 1,
    keyId: this.keyId,
    wrappedDataKey,
    encryptedSecret,
    createdAt: new Date().toISOString(),
  };
  
  await fs.writeFile(this.keyFile(walletId), JSON.stringify(payload), 'utf8');
}

{
  "v": 1,
  "keyId": "wallet-engine-kms-key",
  "wrappedDataKey": "encrypted-data-key",
  "encryptedSecret": "encrypted-private-key",
  "createdAt": "2026-03-08T10:00:00.000Z"
}

import { KMSClient, DecryptCommand, GenerateDataKeyCommand } from '@aws-sdk/client-kms';

const kms = new KMSClient({ region: 'us-east-1' });

// Generate data key using KMS
const { Plaintext, CiphertextBlob } = await kms.send(
  new GenerateDataKeyCommand({
    KeyId: process.env.WALLET_KMS_KEY_ID,
    KeySpec: 'AES_256',
  })
);

// Use Plaintext as data key, store CiphertextBlob as wrappedDataKey

WALLET_SIGNER_BACKEND=hsm
WALLET_HSM_PIN=your-hsm-pin                # Required
WALLET_HSM_MODULE_SECRET=your-module-secret  # Required
WALLET_HSM_SLOT=slot-0                       # Optional (default shown)

// From services/wallet-engine/src/key-provider/hsm-key-provider.ts

export class HsmKeyProvider implements KeyProvider {
  private unwrapSecret(): string {
    return `${this.moduleSecret}:${this.slotId}:${this.pin}`;
  }

  async save(walletId: string, keypair: Keypair): Promise<void> {
    const payload: HsmEnvelope = {
      v: 1,
      slotId: this.slotId,
      wrappedSecret: encryptText(
        Buffer.from(keypair.secretKey).toString('base64'),
        this.unwrapSecret()
      ),
      createdAt: new Date().toISOString(),
    };
    
    await fs.writeFile(this.keyFile(walletId), JSON.stringify(payload), 'utf8');
  }
}

{
  "v": 1,
  "slotId": "slot-0",
  "wrappedSecret": "encrypted-with-hsm-secret",
  "createdAt": "2026-03-08T10:00:00.000Z"
}

import { CloudHSMv2Client } from '@aws-sdk/client-cloudhsmv2';
import * as pkcs11 from 'pkcs11js';

// Initialize PKCS#11 module
const pkcs11Module = new pkcs11.PKCS11();
pkcs11Module.load('/opt/cloudhsm/lib/libcloudhsm_pkcs11.so');

// Open session and login
const session = pkcs11Module.C_OpenSession(slotId, flags);
pkcs11Module.C_Login(session, userType, pin);

// Generate key in HSM
const keyHandle = pkcs11Module.C_GenerateKeyPair(
  session,
  mechanism,
  publicKeyTemplate,
  privateKeyTemplate
);

WALLET_SIGNER_BACKEND=mpc

# Option 1: CSV format
WALLET_MPC_NODE_SECRETS=secret1,secret2,secret3

# Option 2: Individual environment variables
WALLET_MPC_NODE1_SECRET=secret1
WALLET_MPC_NODE2_SECRET=secret2
WALLET_MPC_NODE3_SECRET=secret3

// From services/wallet-engine/src/key-provider/mpc-key-provider.ts

const splitSecret = (secret: Uint8Array): Array<{ id: number; bytes: Uint8Array }> => {
  const coefficient = randomBytes(secret.length);
  const s1 = new Uint8Array(secret.length);
  const s2 = new Uint8Array(secret.length);
  const s3 = new Uint8Array(secret.length);
  
  for (let i = 0; i < secret.length; i += 1) {
    const secretByte = secret[i] ?? 0;
    const a = coefficient[i] ?? 0;
    s1[i] = (secretByte ^ gfMul(a, 1)) & 0xff;
    s2[i] = (secretByte ^ gfMul(a, 2)) & 0xff;
    s3[i] = (secretByte ^ gfMul(a, 3)) & 0xff;
  }
  
  return [
    { id: 1, bytes: s1 },
    { id: 2, bytes: s2 },
    { id: 3, bytes: s3 },
  ];
};

{
  "v": 1,
  "threshold": 2,
  "shares": [
    {"id": 1, "wrapped": "encrypted-with-node1-secret"},
    {"id": 2, "wrapped": "encrypted-with-node2-secret"},
    {"id": 3, "wrapped": "encrypted-with-node3-secret"}
  ],
  "createdAt": "2026-03-08T10:00:00.000Z"
}

// From services/wallet-engine/src/key-provider/mpc-key-provider.ts

const reconstructFromTwoShares = (
  first: { id: number; bytes: Uint8Array },
  second: { id: number; bytes: Uint8Array }
): Uint8Array => {
  const denominator = (first.id ^ second.id) & 0xff;
  const l1 = gfDiv(second.id & 0xff, denominator);
  const l2 = gfDiv(first.id & 0xff, denominator);
  
  const secret = new Uint8Array(first.bytes.length);
  for (let i = 0; i < secret.length; i += 1) {
    const y1 = first.bytes[i] ?? 0;
    const y2 = second.bytes[i] ?? 0;
    secret[i] = (gfMul(y1, l1) ^ gfMul(y2, l2)) & 0xff;
  }
  
  return secret;
};

WALLET_SIGNER_BACKEND=encrypted-file
WALLET_KEY_ENCRYPTION_SECRET=$(openssl rand -base64 32)

WALLET_SIGNER_BACKEND=memory

WALLET_SIGNER_BACKEND=kms
WALLET_KMS_MASTER_SECRET=arn:aws:kms:region:account:key/key-id

WALLET_SIGNER_BACKEND=hsm
WALLET_HSM_PIN=***
WALLET_HSM_MODULE_SECRET=***
WALLET_HSM_SLOT=slot-production

WALLET_SIGNER_BACKEND=mpc
WALLET_MPC_NODE1_SECRET=$(aws secretsmanager get-secret-value --region us-east-1 ...)
WALLET_MPC_NODE2_SECRET=$(gcloud secrets versions access latest --secret=...)
WALLET_MPC_NODE3_SECRET=$(vault kv get -field=value secret/mpc/node3)