# 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`](https://docs.covr.markets/reference/sdk/setup.md#signregistrationgrant) | [`registrationGrantDomain`](https://docs.covr.markets/reference/sdk/setup.md#registrationgrantdomain) | the program, in `register_maker_v3` |
| Bid intent `BidIntent` | [`signIntent`](https://docs.covr.markets/reference/sdk/quoting.md#signintent) | [`quoteDomain`](https://docs.covr.markets/reference/sdk/markets.md#quotedomain) of the RFQ's market | the gateway |
| Quote `QuoteV2` | [`signQuote`](https://docs.covr.markets/reference/sdk/quoting.md#signquote) | [`quoteDomain`](https://docs.covr.markets/reference/sdk/markets.md#quotedomain) of the RFQ's market | the gateway, then the program at fill |
| Withdrawal `WithdrawBid` | [`signWithdrawal`](https://docs.covr.markets/reference/sdk/quoting.md#signwithdrawal) | [`quoteDomain`](https://docs.covr.markets/reference/sdk/markets.md#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.

```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.

| 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](#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`](#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](#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`](https://docs.covr.markets/reference/sdk/quoting.md#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.

```ts
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.


```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`](https://docs.covr.markets/reference/sdk/constants.md#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:

| Domain | Scope bytes |
| --- | --- |
| Registration grant | UTF-8 `registration-v3` ([`REGISTRATION_SCOPE`](https://docs.covr.markets/reference/sdk/constants.md#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:

```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.

| 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`):

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`](#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:

4. [`marketDomain`](https://docs.covr.markets/reference/sdk/markets.md#marketdomain)`(market, bytes of accountDataBase64)` equals `domain` for both market vectors.
5. [`encodeCancellationRequestV1`](https://docs.covr.markets/reference/sdk/settlement.md#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');
```

---

Source: https://docs.covr.markets/reference/sdk/signing · Part of covr Docs, https://docs.covr.markets/llms.txt
