Signers

The gate never holds a key. It hands your signer one request at a time, each built with the hash the gate computed, and it reads the answer back to complete the payment. This page is the contract between the two.

The contractCopy Anchor Link

import type { Signature, SigningRequest } from "@integraledger/terms";

interface Signer {
  /** The payer, CAIP-10: `eip155:84532:0xf39F…2266`. */
  readonly account: string;
  /** Signs exactly `request`. */
  sign(request: SigningRequest): Promise<Signature>;
}

In Python, any object with an account string and an async def sign(self, request) method is a signer.

• account is CAIP-10: the chain namespace, the network reference and the address. It chooses the option the gate pays, and for most pairings it is the payer.
• sign(request) signs exactly what it is handed. It changes nothing: not a field, not an amount, not a deadline. If it cannot sign a request, it throws (TypeScript) or raises (Python), and the gate declines with signer-failed.

The gate calls sign only after the comparison matched, at most twice for one payment (a funding and then a voucher), and never for the payment of a pairing whose build gives the buyer nothing to sign (it may sign that pairing's agreement payment).

Requests and answersCopy Anchor Link

Each request has a kind. The kind says what is signed and what the answer is. The TypeScript type SigningRequest is the union of every kind.

Byte strings. In TypeScript, the request is exactly as the binding built it: byte strings are Uint8Array, and a few integers are bigint. In Python, every byte string in the request is 0x and lower-case hex. In both languages, an answer's byte strings are 0x hex, except where the row names another form: base58, base64, or hex digits without 0x.

EVM and TempoCopy Anchor Link

Other chainsCopy Anchor Link

Protocols without a chain signatureCopy Anchor Link

Signers that move the paymentCopy Anchor Link

For some requests your signer's action moves the payment itself: a Lightning node paying an invoice, a signer that broadcasts an evm-call, tempo-call or hedera-body marked broadcast: true, a session opening the signer sends. If the gate declines after that (for example because the pairing does not read H from what came back), the decline carries moved: the payment as signed, the ATR's bytes and their hash. Keep it, and present it again rather than signing a new payment.

A signer for several kindsCopy Anchor Link

A real signer dispatches on kind and refuses what it does not handle:

import type { Signature, Signer, SigningRequest } from "@integraledger/terms";
import { privateKeyToAccount } from "viem/accounts";

// The published Anvil development key. Never use it for real funds.
const wallet = privateKeyToAccount("0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80");

const signer: Signer = {
  account: `eip155:84532:${wallet.address}`,
  async sign(request: SigningRequest): Promise<Signature> {
    switch (request.kind) {
      case "eip712":
        return wallet.signTypedData(request.typedData as Parameters<typeof wallet.signTypedData>[0]);
      case "batch": {
        const answers: Signature[] = [];
        for (const each of request.requests) answers.push(await this.sign(each as SigningRequest));
        return answers;
      }
      default:
        throw new Error(`this signer does not sign ${request.kind}`);
    }
  },
};

console.log(signer.account);

eip155:84532:0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266

The rails guide lists, for each pairing, the kind its request has and the inputs its build reads.