SDK reference
Signing
Your quote key is a secp256k1 key with an Ethereum-style 0x… address. It signs four kinds of EIP-712 typed data: the one-time registration grant, sealed bid intents, executable quotes, and quote withdrawals (a route not served to desks). This page covers the signer shape the SDK accepts, the signature rule the program enforces, how covr builds its domains, and how to prove your signer against the golden vectors before you sign anything real.
| Message | Signed with | Domain | Verified by |
|---|---|---|---|
Registration grant Register | signRegistrationGrant | registrationGrantDomain | the program, in register_maker_v3 |
Bid intent BidIntent | signIntent | quoteDomain of the RFQ's market | the gateway |
Quote QuoteV2 | signQuote | quoteDomain of the RFQ's market | the gateway, then the program at fill |
Withdrawal WithdrawBid | signWithdrawal | quoteDomain | a gateway route not served to desks |
TypedDataSigner
The signer interface every signing function takes. An ethers Wallet satisfies it as is. For a KMS, HSM or remote signing service, write a small adapter.
export interface TypedDataSigner {
signTypedData(domain: TypedDataDomain, types: Record<string, TypedDataField[]>, value: Record<string, unknown>): Promise<string>;
}TypedDataDomain and TypedDataField are the ethers v6 types.
| Name | Type | Description |
|---|---|---|
domain | TypedDataDomain | { name, version, chainId, verifyingContract }. Always name: 'SOL Covered Calls', version: '1', chainId: 2000000001. |
types | Record<string, TypedDataField[]> | One primary type (Register, BidIntent, QuoteV2 or WithdrawBid). It never includes EIP712Domain. |
value | Record<string, unknown> | The encoded message, not the wire object. Solana keys arrive as 32-byte bytes32 hex, the RFQ id as keccak256(utf8(id)). See What your signer receives. |
Returns: Promise<string>. The 65-byte signature r || s || v as 0x plus 130 hex characters, with v in {27, 28} and s in the low half of the curve order.
Every SDK signing function checks the result with assertCanonicalSignature, then recovers the signer with ethers.verifyTypedData and refuses a signature that does not recover to the expected key. It returns the signature lowercased.
Writing a KMS or HSM adapter
Most KMS and HSM services sign a 32-byte digest and return a DER signature without v. Your adapter must:
- Compute the EIP-712 digest:
TypedDataEncoder.hash(domain, types, value)fromethers. - Ask the KMS to sign that digest.
- Decode the DER
rands. Ifs > n/2, replace it withn - s(n is the secp256k1 order). - Find
vin{27, 28}: the one for which recovery gives your key's address. - Return
0x+r(32 bytes) +s(32 bytes) +v(1 byte), all hex.
import { Signature, TypedDataEncoder, recoverAddress, type TypedDataDomain, type TypedDataField } from 'ethers';
import { assertCanonicalSignature, type TypedDataSigner } from '@covrfun/maker-sdk';
// Your KMS call: signs a 32-byte digest, returns r and s as 0x-hex (32 bytes each).
declare function kmsSignDigest(digest: string): Promise<{ r: string; s: string }>;
declare const quoteKeyAddress: string; // your quote key's 0x address
const N = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;
export const kmsSigner: TypedDataSigner & { address: string } = {
address: quoteKeyAddress,
async signTypedData(
domain: TypedDataDomain,
types: Record<string, TypedDataField[]>,
value: Record<string, unknown>,
): Promise<string> {
const digest = TypedDataEncoder.hash(domain, types, value);
const { r, s } = await kmsSignDigest(digest);
const sValue = BigInt(s);
const low = sValue > N / 2n ? N - sValue : sValue;
const lowS = '0x' + low.toString(16).padStart(64, '0');
for (const v of [27, 28] as const) {
const signature = Signature.from({ r, s: lowS, v }).serialized;
if (recoverAddress(digest, signature).toLowerCase() === quoteKeyAddress.toLowerCase()) {
assertCanonicalSignature(signature);
return signature;
}
}
throw new Error('KMS signature does not recover to the quote key');
},
};Run your adapter against the golden vectors before it signs anything real.
What your signer receives
The SDK converts each wire object to its EIP-712 value before it calls your signer. Fields not listed pass through unchanged.
| Field | Wire form | Value your signer receives |
|---|---|---|
auctionId (intent, quote) | RFQ id, a lowercase UUID v4 | keccak256(utf8(id)), as bytes32 hex (auctionKey) |
kind (intent) | 'open' | 0 (position_sale is 1, early_close is 2) |
market, wallet (intent), writer (quote) | base58 Solana key | the key's 32 bytes as bytes32 hex |
position (intent) | null for an opening RFQ | 32 zero bytes |
authority (registration) | base58 Solana key | the key's 32 bytes as bytes32 hex |
rfqId (withdrawal) | RFQ id | the same string (string type) |
quoteHash (withdrawal) | the quote's signature | keccak256(signature bytes) |
The golden vectors show both forms side by side: wire (or rpc.params) and typedData.message.
assertCanonicalSignature
Throws unless a signature is in the exact form the program accepts. Call it on any signature your own code produces before you send or submit it.
export declare function assertCanonicalSignature(signature: string): void;| Name | Type | Description |
|---|---|---|
signature | string | 0x plus 130 hex characters: r (32 bytes), s (32 bytes), v (1 byte). Upper- or lowercase hex. |
Returns: void.
Throws:
| Condition | Message |
|---|---|
Not a string, or not exactly 0x + 130 hex characters | maker-sdk: signature must be 65 bytes of 0x-hex |
v is not 27 or 28, s is zero, or s > n/2 (high-s) | maker-sdk: non-canonical signature (need v in {27,28} and low s) |
n/2 is 0x7fffffffffffffffffffffffffffffff5d576e7357a4501ddfe92f46681b20a0. The Solana secp256k1 recovery syscall alone would accept the high-s twin of a valid signature. The program refuses it, and so does this check.
import { assertCanonicalSignature } from '@covrfun/maker-sdk';
declare const signature: string; // from your own signing path
assertCanonicalSignature(signature); // throws on high-s, v not in {27,28}, or bad lengthHow covr domains are built
Every covr domain has the same name, version and chainId (EIP712_DOMAIN_BASE) and its own verifyingContract:
verifyingContract = last 20 bytes of keccak256(
"deployment-v2" || deploymentId (32 bytes) || programId (32 bytes) || scope
)The scope depends on what is signed:
| Domain | Scope bytes |
|---|---|
| Registration grant | UTF-8 registration-v3 (REGISTRATION_SCOPE) |
| Ordinary market | UTF-8 market-v3:ordinary-atomic, then the market's terms (below) |
| Restricted market | UTF-8 market-v3:restricted-pending, then the market's terms (below) |
The market terms follow the literal in this order: market address (32 bytes); version, settlementMode, collateralDecimals, paymentDecimals (1 byte each); creator, collateral, collateralProgram, payment, paymentProgram, feeOwner, genesisHash (32 bytes each); deploymentId, termsId, profileHash (32 bytes each); salt (u64 LE), expiry (i64 LE), window (u64 LE), strikeE8 (u64 LE), maxQuantityAtoms (u64 LE), feeBps (u16 LE).
So a market's domain commits to every term. A signature for one market never verifies for another market. The paused flag and the PDA bump are not part of the scope, so pausing a market does not change its domain.
Golden vectors
The package ships vectors/golden-vectors.json, importable as @covrfun/maker-sdk/vectors/golden-vectors.json. It holds fixed inputs and the exact bytes covr's own code produces for them. Use it to prove that your EIP-712 encoder and your signer produce what the gateway and the program verify.
All signatures in the file come from a throwaway key that is public by construction:
privateKey = keccak256(utf8("covr-maker-sdk-golden-vectors-v1"))
address = 0x7B99e6A7407Fe0058119F4f13494C0b9cec35738Never fund, register or quote with the throwaway key. Anyone can derive it.
| Key | What it holds |
|---|---|
key | seed, derivation and address of the throwaway key |
program, deploymentId, genesisHash, eip712DomainBase | The mainnet pins the vectors use |
registration | A registration grant for a synthetic authority: typedData (types, domain, message), digest, verifyingContract, signature, recoveredAddress |
ordinaryMarketDomain | A synthetic ordinary JitoSOL market (not on chain): raw accountDataBase64, decoded terms, scopeHex, domain |
restrictedMarketDomain | A real mainnet restricted market captured at a finalized slot: the same fields |
bidIntent | A bid intent on the synthetic market: context (auction, terms, request), typedData, digest, signature, wire object and the full JSON-RPC frame in rpc |
quote | The quote answering that intent: context, typedData, digest, signature, wire, rpc, and the expected amounts (gross 1200000, fee 120000, writer 1080000, strike 85000000 USDC atoms) |
withdrawal | A WithdrawBid over that quote: typedData, digest, signature, body |
cancellationRequest | A restricted cancellation request and its 288-byte Borsh encoding encodedHex |
How to verify your signer
Check three things for each typed-data vector (registration, bidIntent, quote, withdrawal):
- Digest. Your EIP-712 encoder gives
digestfortypedData(dropEIP712Domainfromtypesif your library adds it itself). This proves your types, domain and value encoding. - Signature format. Sign
typedDatawith your own key. The result passesassertCanonicalSignatureand recovers to your quote key's address. - Signature bytes (deterministic signers only). If your stack can load the throwaway key and signs with RFC 6979 (ethers does), the signature equals
signaturebyte for byte. Many KMS and HSM services use a random nonce. Their signatures differ from the vector and are still valid: rely on checks 1 and 2.
Then check the domains and the encoding the SDK computes for you:
marketDomain(market, bytes of accountDataBase64)equalsdomainfor both market vectors.encodeCancellationRequestV1(request)equalsencodedHex.
Example: verify with ethers
This script runs as is under Node 24, which strips TypeScript types itself: node verify-vectors.ts. With the tsx dev tool (npm install -D tsx) you can also run npx tsx verify-vectors.ts. Replace mySigner with your adapter.
import { readFileSync } from 'node:fs';
import { createRequire } from 'node:module';
import { TypedDataEncoder, Wallet, keccak256, toUtf8Bytes, verifyTypedData } from 'ethers';
import {
assertCanonicalSignature,
encodeCancellationRequestV1,
marketDomain,
type TypedDataSigner,
} from '@covrfun/maker-sdk';
const require = createRequire(import.meta.url);
const vectors = JSON.parse(
readFileSync(require.resolve('@covrfun/maker-sdk/vectors/golden-vectors.json'), 'utf8'),
);
// The public throwaway key. Never use it for anything else.
const throwaway = new Wallet(keccak256(toUtf8Bytes(vectors.key.seed)));
if (throwaway.address !== vectors.key.address) throw new Error('key derivation differs');
// Replace with your KMS/HSM adapter and its address.
const mySigner: TypedDataSigner & { address: string } = throwaway;
for (const name of ['registration', 'bidIntent', 'quote', 'withdrawal']) {
const { types: allTypes, domain, message } = vectors[name].typedData;
const { EIP712Domain: _ignored, ...types } = allTypes;
// 1. Digest: proves your types, domain and value encoding.
if (TypedDataEncoder.hash(domain, types, message) !== vectors[name].digest)
throw new Error(`${name}: digest differs`);
// 2. Format: canonical, and recovers to your key.
const signature = await mySigner.signTypedData(domain, types, message);
assertCanonicalSignature(signature);
if (verifyTypedData(domain, types, message, signature) !== mySigner.address)
throw new Error(`${name}: signature does not recover to your key`);
// 3. Bytes: only for a deterministic (RFC 6979) signer holding the throwaway key.
const reference = await throwaway.signTypedData(domain, types, message);
if (reference !== vectors[name].signature) throw new Error(`${name}: signature bytes differ`);
}
// 4. Market domains from raw account bytes.
for (const name of ['ordinaryMarketDomain', 'restrictedMarketDomain']) {
const raw = new Uint8Array(Buffer.from(vectors[name].accountDataBase64, 'base64'));
const domain = await marketDomain(vectors[name].market, raw);
if (domain.verifyingContract !== vectors[name].verifyingContract)
throw new Error(`${name}: domain differs`);
}
// 5. Cancellation request encoding.
const r = vectors.cancellationRequest.request;
const encoded = encodeCancellationRequestV1({
...r,
intentGeneration: BigInt(r.intentGeneration),
refundStrikeUsdc: BigInt(r.refundStrikeUsdc),
returnCollateralAtoms: BigInt(r.returnCollateralAtoms),
validUntil: BigInt(r.validUntil),
});
if ('0x' + Buffer.from(encoded).toString('hex') !== vectors.cancellationRequest.encodedHex)
throw new Error('cancellation encoding differs');
console.log('all golden vectors verified');