Guides
Custom signers (KMS and HSM)
Every SDK signing function takes a signer: any object with one method.
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:
- hashes the EIP-712 message;
- asks your KMS to sign the digest;
- folds
sinto the lower half, which the program requires; - finds the recovery byte by checking which one recovers your quote key.
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:
privateKey = keccak256(utf8("covr-maker-sdk-golden-vectors-v1"))
address = 0x7B99e6A7407Fe0058119F4f13494C0b9cec35738Each 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.
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:
registration match
bidIntent match
quote match
withdrawal matchTo 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.
The golden-vector key is public. Never fund it or register it.