covr.Docs

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.

MessageSigned withDomainVerified by
Registration grant RegistersignRegistrationGrantregistrationGrantDomainthe program, in register_maker_v3
Bid intent BidIntentsignIntentquoteDomain of the RFQ's marketthe gateway
Quote QuoteV2signQuotequoteDomain of the RFQ's marketthe gateway, then the program at fill
Withdrawal WithdrawBidsignWithdrawalquoteDomaina 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.

ts
export interface TypedDataSigner {
    signTypedData(domain: TypedDataDomain, types: Record<string, TypedDataField[]>, value: Record<string, unknown>): Promise<string>;
}

TypedDataDomain and TypedDataField are the ethers v6 types.

NameTypeDescription
domainTypedDataDomain{ name, version, chainId, verifyingContract }. Always name: 'SOL Covered Calls', version: '1', chainId: 2000000001.
typesRecord<string, TypedDataField[]>One primary type (Register, BidIntent, QuoteV2 or WithdrawBid). It never includes EIP712Domain.
valueRecord<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:

  1. Compute the EIP-712 digest: TypedDataEncoder.hash(domain, types, value) from ethers.
  2. Ask the KMS to sign that digest.
  3. Decode the DER r and s. If s > n/2, replace it with n - s (n is the secp256k1 order).
  4. Find v in {27, 28}: the one for which recovery gives your key's address.
  5. Return 0x + r (32 bytes) + s (32 bytes) + v (1 byte), all hex.
ts
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');
  },
};
Tip

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.

FieldWire formValue your signer receives
auctionId (intent, quote)RFQ id, a lowercase UUID v4keccak256(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 keythe key's 32 bytes as bytes32 hex
position (intent)null for an opening RFQ32 zero bytes
authority (registration)base58 Solana keythe key's 32 bytes as bytes32 hex
rfqId (withdrawal)RFQ idthe same string (string type)
quoteHash (withdrawal)the quote's signaturekeccak256(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.

ts
export declare function assertCanonicalSignature(signature: string): void;
NameTypeDescription
signaturestring0x plus 130 hex characters: r (32 bytes), s (32 bytes), v (1 byte). Upper- or lowercase hex.

Returns: void.

Throws:

ConditionMessage
Not a string, or not exactly 0x + 130 hex charactersmaker-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.

ts
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 length

How covr domains are built

Every covr domain has the same name, version and chainId (EIP712_DOMAIN_BASE) and its own verifyingContract:

text
verifyingContract = last 20 bytes of keccak256(
  "deployment-v2" || deploymentId (32 bytes) || programId (32 bytes) || scope
)

The scope depends on what is signed:

DomainScope bytes
Registration grantUTF-8 registration-v3 (REGISTRATION_SCOPE)
Ordinary marketUTF-8 market-v3:ordinary-atomic, then the market's terms (below)
Restricted marketUTF-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:

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

Never fund, register or quote with the throwaway key. Anyone can derive it.

KeyWhat it holds
keyseed, derivation and address of the throwaway key
program, deploymentId, genesisHash, eip712DomainBaseThe mainnet pins the vectors use
registrationA registration grant for a synthetic authority: typedData (types, domain, message), digest, verifyingContract, signature, recoveredAddress
ordinaryMarketDomainA synthetic ordinary JitoSOL market (not on chain): raw accountDataBase64, decoded terms, scopeHex, domain
restrictedMarketDomainA real mainnet restricted market captured at a finalized slot: the same fields
bidIntentA bid intent on the synthetic market: context (auction, terms, request), typedData, digest, signature, wire object and the full JSON-RPC frame in rpc
quoteThe quote answering that intent: context, typedData, digest, signature, wire, rpc, and the expected amounts (gross 1200000, fee 120000, writer 1080000, strike 85000000 USDC atoms)
withdrawalA WithdrawBid over that quote: typedData, digest, signature, body
cancellationRequestA 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):

  1. Digest. Your EIP-712 encoder gives digest for typedData (drop EIP712Domain from types if your library adds it itself). This proves your types, domain and value encoding.
  2. Signature format. Sign typedData with your own key. The result passes assertCanonicalSignature and recovers to your quote key's address.
  3. Signature bytes (deterministic signers only). If your stack can load the throwaway key and signs with RFC 6979 (ethers does), the signature equals signature byte 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:

  1. marketDomain(market, bytes of accountDataBase64) equals domain for both market vectors.
  2. encodeCancellationRequestV1(request) equals encodedHex.

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.

ts
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');