covr.Docs

Guides

Custom signers (KMS and HSM)

Every SDK signing function takes a signer: any object with one method.

ts
interface TypedDataSigner {
  signTypedData(
    domain: TypedDataDomain,
    types: Record<string, TypedDataField[]>,
    value: Record<string, unknown>,
  ): Promise<string>; // 65-byte signature, 0x-hex
}

An ethers Wallet fits as is. For production, keep the quote key in a KMS or HSM and wrap it.

Wrap a KMS

Most KMS products sign a 32-byte digest and return r and s with no recovery byte. This adapter:

  1. hashes the EIP-712 message;
  2. asks your KMS to sign the digest;
  3. folds s into the lower half, which the program requires;
  4. finds the recovery byte by checking which one recovers your quote key.
ts
import { Signature, TypedDataEncoder, recoverAddress, toBeHex, zeroPadValue } from 'ethers';
import { assertCanonicalSignature, type TypedDataSigner } from '@covrfun/maker-sdk';

const N = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n; // secp256k1 order

/** Wrap any KMS or HSM that signs a 32-byte digest and returns r and s (no v). */
export function kmsSigner(
  quoteKeyAddress: string,
  signDigest: (digest: string) => Promise<{ r: bigint; s: bigint }>,
): TypedDataSigner {
  return {
    async signTypedData(domain, types, value) {
      const digest = TypedDataEncoder.hash(domain, types, value);
      let { r, s } = await signDigest(digest);
      if (s > N / 2n) s = N - s; // the program accepts low-s only
      const rHex = zeroPadValue(toBeHex(r), 32), sHex = zeroPadValue(toBeHex(s), 32);
      for (const v of [27, 28] as const) {
        const signature = Signature.from({ r: rHex, s: sHex, v }).serialized;
        if (recoverAddress(digest, signature).toLowerCase() === quoteKeyAddress.toLowerCase()) {
          assertCanonicalSignature(signature);
          return signature;
        }
      }
      throw Error('KMS signature does not recover to the quote key');
    },
  };
}

signIntent and signQuote check the result again. They refuse a signature that does not recover to the maker named in the message, or one with a high s.

Prove it with the golden vectors

The package ships vectors/golden-vectors.json. It holds every message type a desk signs, already signed with a public throwaway key:

text
privateKey = keccak256(utf8("covr-maker-sdk-golden-vectors-v1"))
address    = 0x7B99e6A7407Fe0058119F4f13494C0b9cec35738

Each entry carries standard eth_signTypedData_v4 JSON (domain, types, primaryType, message), the expected digest and the expected signature. Feed the typed data to your stack and compare:

  • Digests must match exactly. A different digest means your encoding differs from covr's.
  • Signatures match exactly only for deterministic signers (RFC 6979), such as ethers. Many KMS and HSM services pick a random nonce. Their signatures differ from the vectors and are still valid. For those, check that each signature recovers to the vector address and passes assertCanonicalSignature.
ts
import { readFile } from 'node:fs/promises';
import { createRequire } from 'node:module';
import { Wallet, TypedDataEncoder, keccak256, recoverAddress, toUtf8Bytes } from 'ethers';
import { assertCanonicalSignature } from '@covrfun/maker-sdk';

const require = createRequire(import.meta.url);
const file = require.resolve('@covrfun/maker-sdk/vectors/golden-vectors.json');
const v = JSON.parse(await readFile(file, 'utf8'));

// The vectors' throwaway key. Replace this signer with your KMS or HSM adapter.
const signer = new Wallet(keccak256(toUtf8Bytes(v.key.seed)));

for (const name of ['registration', 'bidIntent', 'quote', 'withdrawal']) {
  const { domain, types, message } = v[name].typedData;
  const { EIP712Domain, ...signedTypes } = types; // ethers derives the domain type itself
  void EIP712Domain;
  const digest = TypedDataEncoder.hash(domain, signedTypes, message);
  const signature = await signer.signTypedData(domain, signedTypes, message);
  if (digest !== v[name].digest) { console.log(name.padEnd(12), 'DIGEST MISMATCH', digest); continue; }
  assertCanonicalSignature(signature); // throws on a high-s signature
  const recovers = recoverAddress(digest, signature) === v.key.address;
  // Deterministic signers (RFC 6979, like ethers) reproduce the vector exactly.
  // A random-nonce KMS gives a different, equally valid signature: it must still recover.
  console.log(name.padEnd(12), signature === v[name].signature ? 'match' : recovers ? 'valid (recovers)' : 'SIGNATURE MISMATCH');
}

Expected output:

text
registration match
bidIntent    match
quote        match
withdrawal   match

To test your KMS adapter itself, import the throwaway key into a test KMS key and wrap it with kmsSigner. Then run the same loop, checking the digest exactly and the signature by recovery.

Caution

The golden-vector key is public. Never fund it or register it.