thunder-bridge 1.4.2 → 2.1.1

package/dist/types-DYZ9EkmJ.d.cts

@@ -0,0 +1,261 @@
+/**
+ * How many minor units of `currency` one bitcoin costs at one venue, so 134883815
+ * is 1,348,838.15 CZK. Throws when that venue does not quote that currency, which
+ * is a normal answer rather than a fault: Kraken and Bitstamp have no CZK pair
+ *
+ * This is the plugin seam for prices. Another venue is another function of this
+ * shape
+ */
+type Ticker = (currency: string) => Promise<number>;
+/** How many venues have to agree, how far apart they may be, and how long an answer is held */
+interface MedianOptions {
+    /**
+     * How many venues have to answer before a price is usable. Two is the floor
+     * worth having, because one venue is a number nobody checked
+     */
+    minVenues?: number;
+    /**
+     * Refuse the lot when the cheapest and dearest answers are further apart than
+     * this many basis points. Venues normally sit inside 50, so a wider spread means
+     * one of them is broken or stale rather than that the market moved
+     */
+    maxSpreadBps?: number;
+    /** Hold the last answer this long per currency, so an order page is not four requests */
+    holdForSecs?: number;
+}
+/** Coinbase, CASP authorised in Luxembourg. Quotes CZK, EUR and most fiat */
+declare function coinbase(baseUrl?: string): Ticker;
+/** Kraken, CASP authorised by the Central Bank of Ireland. Quotes EUR and USD, no CZK */
+declare function kraken(baseUrl?: string): Ticker;
+/**
+ * Bitstamp, CASP authorised by the CSSF in Luxembourg. Quotes EUR and USD, no CZK.
+ *
+ * An unknown pair is answered with a `200` and the whole ticker list, whose first
+ * entry is BTC/USD, so asking it for CZK and reading the number would quote a
+ * bitcoin at 64,000 crowns. Anything but a single object is therefore refused
+ */
+declare function bitstamp(baseUrl?: string): Ticker;
+/** Coinmate, on the ESMA CASP register, Czech and the one with a real BTC/CZK book */
+declare function coinmate(baseUrl?: string): Ticker;
+/**
+ * Ask several venues and take the middle answer, refusing the lot when they
+ * disagree too much.
+ *
+ * The default is the four MiCA authorised venues below, and every one of them is
+ * replaceable: pass your own list, or one venue, or a function that reads a price
+ * you already have. A venue that does not quote the currency is skipped rather
+ * than fatal, which for CZK leaves Coinbase and Coinmate.
+ *
+ * The middle is taken rather than the mean so one stuck venue moves the answer by
+ * nothing instead of by half its error, and the spread check is what catches the
+ * stuck venue that stays inside the pack.
+ */
+declare function medianOf(tickers?: Ticker[], options?: MedianOptions): Ticker;
+/**
+ * What to ask for over Lightning for a price named in fiat, in millisatoshi.
+ *
+ * `priceMinorPerBtc` is what a `Ticker` returns. The arithmetic is exact, in
+ * BigInt, because a million crown order times a hundred billion millisatoshi
+ * leaves what a double can count, and it rounds up, because the extra
+ * millisatoshi is worth nothing and belongs to the recipient rather than to a
+ * rounding rule.
+ *
+ * `spreadBps` is yours to set, in basis points, and defaults to none. A Lightning
+ * invoice lives an hour and a bank transfer takes days, so a shop pricing in fiat is
+ * carrying that volatility whether or not it charges for it
+ */
+declare function msatFor(amountMinor: number, priceMinorPerBtc: number, options?: {
+    spreadBps?: number;
+}): number;
+
+declare const brand: unique symbol;
+/**
+ * A whole number of millisatoshi that came from `sats`, `msat` or `fiat`, and
+ * could not have come from anywhere else.
+ *
+ * The brand is why: a bare number is not one of these, so `21` cannot be passed
+ * where a price is wanted and quietly mean twenty-one thousandths of a satoshi.
+ * It costs nothing at runtime, where the value is an ordinary number
+ */
+type Msat = number & {
+    readonly [brand]: "Msat";
+};
+/**
+ * What a payment is worth. A `Msat` is a price known now, and a function is one
+ * worked out when the invoice is minted, which is what a fiat price has to be.
+ *
+ * Build one with `sats`, `msat` or `fiat`
+ */
+type Amount = Msat | (() => Msat | Promise<Msat>);
+/** How a fiat price is turned into millisatoshi at the moment of minting */
+interface FiatOptions {
+    /**
+     * Where the rate comes from, the median of the four MiCA authorised venues by
+     * default. Pass your own to price off one venue, off your own book, or off a
+     * number you already hold
+     */
+    rate?: Ticker;
+    /**
+     * What you add over the rate, in basis points, none by default. A Lightning
+     * invoice lives an hour and a bank transfer takes days, so a shop pricing in
+     * fiat carries that volatility whether or not it charges for it
+     */
+    spreadBps?: number;
+}
+/** A whole number of satoshi, so `sats(21)` is 21000 millisatoshi */
+declare function sats(whole: number): Msat;
+/** An exact number of millisatoshi, for a price already in the smallest unit */
+declare function msat(exact: number): Msat;
+/**
+ * A price named in fiat, converted when the invoice is minted rather than now.
+ *
+ * Name it as a string and it is read digit by digit, exactly. Name it as a
+ * number and it is rounded to the currency's ISO 4217 minor unit, because
+ * binary floating point cannot hold 4.99 and a payment library that pretends
+ * otherwise moves the wrong amount.
+ *
+ * Every conversion asks the rate afresh, so two calls a second apart can
+ * differ. That is the honest behaviour for a fiat price, and the reason an
+ * amount is a function rather than a number.
+ *
+ * The answer is rounded up to a whole satoshi, because a wallet issues an
+ * invoice in satoshi and refuses a fraction of one. Up rather than down, so the
+ * rounding is never the shop's loss. `msatFor` is the raw conversion, for a rail
+ * that has no invoice to round for
+ */
+declare function fiat(major: number | string, currency: string, options?: FiatOptions): () => Promise<Msat>;
+
+/** Where a payment stands, `paid` is the only status that carries a preimage */
+type PaymentStatus = "pending" | "paid" | "expired";
+interface Reported {
+    id: string;
+    status: PaymentStatus;
+    paymentHash: string;
+    verifyUrl: string;
+    preimage: string | null;
+    expiresAt: number;
+    createdAt: number;
+    /** What the watcher needs and the gateway cannot read, `unseal` opens it */
+    sealed: string | null;
+}
+/**
+ * A payment the gateway minted. It resolved the address itself, so it knows who
+ * is paid, how much, and which invoice says so, and none of the three can be
+ * null here
+ */
+interface MintedPayment extends Reported {
+    kind: "minted";
+    lnAddress: string;
+    amountMsat: number;
+    bolt11: string;
+}
+/**
+ * A payment the gateway was handed rather than asked to mint. It was told a hash,
+ * a URL and an expiry and nothing else, which is the point of `watch`, so the
+ * address, the amount and the invoice are all absent rather than merely unknown
+ */
+interface WatchedPayment extends Reported {
+    kind: "watched";
+    lnAddress: null;
+    amountMsat: null;
+    bolt11: null;
+}
+/**
+ * A payment as the gateway reports it, of either sort. Check `kind` and the
+ * three fields a watched payment does not carry stop being null, so nothing here
+ * needs an assertion to read
+ */
+type Payment = MintedPayment | WatchedPayment;
+/**
+ * A payment as the caller already knows it: what the gateway calls it and the
+ * hash it settles against. Every `Payment` is one, and a caller reading back
+ * after a restart builds one from the two fields it stored
+ */
+interface Held {
+    id: string;
+    paymentHash: string;
+}
+/**
+ * Who is paid and how much. `to` is a priority list when it is an array: the
+ * gateway takes the first address that can issue a provable invoice for the
+ * amount and the rest are the fallback
+ */
+interface Charge {
+    paidTo: string | string[];
+    amount: Amount;
+    /** Where the gateway posts the settlement, signed with the key it publishes */
+    webhookUrl?: string;
+}
+/**
+ * A charge with its price settled, which is what a proof compares the gateway's
+ * answer against. Asking a fiat price twice gives two numbers, so the proof is
+ * handed the one that was actually asked for
+ */
+interface Priced {
+    paidTo: string[];
+    amountMsat: number;
+}
+/**
+ * An invoice you obtained yourself, handed over to be watched. The gateway is
+ * given no address and no amount, so it cannot refuse one recipient rather than
+ * all of them
+ */
+interface Handover {
+    paymentHash: string;
+    verifyUrl: string;
+    expiresAt: number;
+    /** Groups this payment with every other one carrying the same secret */
+    trigger?: string;
+    /**
+     * How many of this trigger's settlements the gateway keeps replayable past the
+     * hour it would otherwise forget them in, up to the ceiling its operator set.
+     * Needs `trigger`, defaults to none
+     */
+    replay?: number;
+    /** Sealed with `seal` for this payment hash, so the gateway stores what it cannot read or move */
+    sealed?: string;
+    webhookUrl?: string;
+}
+/**
+ * Which address would serve an amount, and what the ones ahead of it refused.
+ * `feeMsat` is always zero, the payer pays the recipient's own invoice and the
+ * gateway is never in the money's path
+ */
+interface Quote {
+    lnAddress: string;
+    amountMsat: number;
+    feeMsat: number;
+    minMsat: number;
+    maxMsat: number;
+    metadata: string;
+    refusals: WalletFailure[];
+}
+/**
+ * A one minute pass onto one trigger's stream. It opens that trigger and nothing
+ * else, which is what makes it the thing to hand a browser when the trigger
+ * secret is not. `expiresAt` is unix seconds, like every other time here
+ */
+interface SocketTicket {
+    ticket: string;
+    expiresAt: number;
+}
+/** Why one wallet in the list could not be used */
+type WalletReason = "address-unusable" | "unreachable" | "amount-not-accepted" | "cannot-prove-delivery" | "invoice-refused";
+/** One wallet on the list that could not be used, and the reason it could not */
+interface WalletFailure {
+    address: string;
+    reason: WalletReason;
+}
+/**
+ * What a delivery carries. Everything needed to act on a settlement and to check
+ * it, and nothing else, so a retry is the same size every time
+ */
+interface Settlement {
+    id: string;
+    status: PaymentStatus;
+    paymentHash: string;
+    preimage: string | null;
+    settledAt: number;
+}
+
+export { type Amount as A, type Charge as C, type FiatOptions as F, type Handover as H, type MedianOptions as M, type Payment as P, type Quote as Q, type Settlement as S, type Ticker as T, type WalletFailure as W, coinmate as a, bitstamp as b, coinbase as c, msatFor as d, type Held as e, type MintedPayment as f, type Msat as g, type PaymentStatus as h, type Priced as i, type SocketTicket as j, kraken as k, type WalletReason as l, medianOf as m, type WatchedPayment as n, fiat as o, msat as p, sats as s };

package/dist/types-DYZ9EkmJ.d.ts

@@ -0,0 +1,261 @@
+/**
+ * How many minor units of `currency` one bitcoin costs at one venue, so 134883815
+ * is 1,348,838.15 CZK. Throws when that venue does not quote that currency, which
+ * is a normal answer rather than a fault: Kraken and Bitstamp have no CZK pair
+ *
+ * This is the plugin seam for prices. Another venue is another function of this
+ * shape
+ */
+type Ticker = (currency: string) => Promise<number>;
+/** How many venues have to agree, how far apart they may be, and how long an answer is held */
+interface MedianOptions {
+    /**
+     * How many venues have to answer before a price is usable. Two is the floor
+     * worth having, because one venue is a number nobody checked
+     */
+    minVenues?: number;
+    /**
+     * Refuse the lot when the cheapest and dearest answers are further apart than
+     * this many basis points. Venues normally sit inside 50, so a wider spread means
+     * one of them is broken or stale rather than that the market moved
+     */
+    maxSpreadBps?: number;
+    /** Hold the last answer this long per currency, so an order page is not four requests */
+    holdForSecs?: number;
+}
+/** Coinbase, CASP authorised in Luxembourg. Quotes CZK, EUR and most fiat */
+declare function coinbase(baseUrl?: string): Ticker;
+/** Kraken, CASP authorised by the Central Bank of Ireland. Quotes EUR and USD, no CZK */
+declare function kraken(baseUrl?: string): Ticker;
+/**
+ * Bitstamp, CASP authorised by the CSSF in Luxembourg. Quotes EUR and USD, no CZK.
+ *
+ * An unknown pair is answered with a `200` and the whole ticker list, whose first
+ * entry is BTC/USD, so asking it for CZK and reading the number would quote a
+ * bitcoin at 64,000 crowns. Anything but a single object is therefore refused
+ */
+declare function bitstamp(baseUrl?: string): Ticker;
+/** Coinmate, on the ESMA CASP register, Czech and the one with a real BTC/CZK book */
+declare function coinmate(baseUrl?: string): Ticker;
+/**
+ * Ask several venues and take the middle answer, refusing the lot when they
+ * disagree too much.
+ *
+ * The default is the four MiCA authorised venues below, and every one of them is
+ * replaceable: pass your own list, or one venue, or a function that reads a price
+ * you already have. A venue that does not quote the currency is skipped rather
+ * than fatal, which for CZK leaves Coinbase and Coinmate.
+ *
+ * The middle is taken rather than the mean so one stuck venue moves the answer by
+ * nothing instead of by half its error, and the spread check is what catches the
+ * stuck venue that stays inside the pack.
+ */
+declare function medianOf(tickers?: Ticker[], options?: MedianOptions): Ticker;
+/**
+ * What to ask for over Lightning for a price named in fiat, in millisatoshi.
+ *
+ * `priceMinorPerBtc` is what a `Ticker` returns. The arithmetic is exact, in
+ * BigInt, because a million crown order times a hundred billion millisatoshi
+ * leaves what a double can count, and it rounds up, because the extra
+ * millisatoshi is worth nothing and belongs to the recipient rather than to a
+ * rounding rule.
+ *
+ * `spreadBps` is yours to set, in basis points, and defaults to none. A Lightning
+ * invoice lives an hour and a bank transfer takes days, so a shop pricing in fiat is
+ * carrying that volatility whether or not it charges for it
+ */
+declare function msatFor(amountMinor: number, priceMinorPerBtc: number, options?: {
+    spreadBps?: number;
+}): number;
+
+declare const brand: unique symbol;
+/**
+ * A whole number of millisatoshi that came from `sats`, `msat` or `fiat`, and
+ * could not have come from anywhere else.
+ *
+ * The brand is why: a bare number is not one of these, so `21` cannot be passed
+ * where a price is wanted and quietly mean twenty-one thousandths of a satoshi.
+ * It costs nothing at runtime, where the value is an ordinary number
+ */
+type Msat = number & {
+    readonly [brand]: "Msat";
+};
+/**
+ * What a payment is worth. A `Msat` is a price known now, and a function is one
+ * worked out when the invoice is minted, which is what a fiat price has to be.
+ *
+ * Build one with `sats`, `msat` or `fiat`
+ */
+type Amount = Msat | (() => Msat | Promise<Msat>);
+/** How a fiat price is turned into millisatoshi at the moment of minting */
+interface FiatOptions {
+    /**
+     * Where the rate comes from, the median of the four MiCA authorised venues by
+     * default. Pass your own to price off one venue, off your own book, or off a
+     * number you already hold
+     */
+    rate?: Ticker;
+    /**
+     * What you add over the rate, in basis points, none by default. A Lightning
+     * invoice lives an hour and a bank transfer takes days, so a shop pricing in
+     * fiat carries that volatility whether or not it charges for it
+     */
+    spreadBps?: number;
+}
+/** A whole number of satoshi, so `sats(21)` is 21000 millisatoshi */
+declare function sats(whole: number): Msat;
+/** An exact number of millisatoshi, for a price already in the smallest unit */
+declare function msat(exact: number): Msat;
+/**
+ * A price named in fiat, converted when the invoice is minted rather than now.
+ *
+ * Name it as a string and it is read digit by digit, exactly. Name it as a
+ * number and it is rounded to the currency's ISO 4217 minor unit, because
+ * binary floating point cannot hold 4.99 and a payment library that pretends
+ * otherwise moves the wrong amount.
+ *
+ * Every conversion asks the rate afresh, so two calls a second apart can
+ * differ. That is the honest behaviour for a fiat price, and the reason an
+ * amount is a function rather than a number.
+ *
+ * The answer is rounded up to a whole satoshi, because a wallet issues an
+ * invoice in satoshi and refuses a fraction of one. Up rather than down, so the
+ * rounding is never the shop's loss. `msatFor` is the raw conversion, for a rail
+ * that has no invoice to round for
+ */
+declare function fiat(major: number | string, currency: string, options?: FiatOptions): () => Promise<Msat>;
+
+/** Where a payment stands, `paid` is the only status that carries a preimage */
+type PaymentStatus = "pending" | "paid" | "expired";
+interface Reported {
+    id: string;
+    status: PaymentStatus;
+    paymentHash: string;
+    verifyUrl: string;
+    preimage: string | null;
+    expiresAt: number;
+    createdAt: number;
+    /** What the watcher needs and the gateway cannot read, `unseal` opens it */
+    sealed: string | null;
+}
+/**
+ * A payment the gateway minted. It resolved the address itself, so it knows who
+ * is paid, how much, and which invoice says so, and none of the three can be
+ * null here
+ */
+interface MintedPayment extends Reported {
+    kind: "minted";
+    lnAddress: string;
+    amountMsat: number;
+    bolt11: string;
+}
+/**
+ * A payment the gateway was handed rather than asked to mint. It was told a hash,
+ * a URL and an expiry and nothing else, which is the point of `watch`, so the
+ * address, the amount and the invoice are all absent rather than merely unknown
+ */
+interface WatchedPayment extends Reported {
+    kind: "watched";
+    lnAddress: null;
+    amountMsat: null;
+    bolt11: null;
+}
+/**
+ * A payment as the gateway reports it, of either sort. Check `kind` and the
+ * three fields a watched payment does not carry stop being null, so nothing here
+ * needs an assertion to read
+ */
+type Payment = MintedPayment | WatchedPayment;
+/**
+ * A payment as the caller already knows it: what the gateway calls it and the
+ * hash it settles against. Every `Payment` is one, and a caller reading back
+ * after a restart builds one from the two fields it stored
+ */
+interface Held {
+    id: string;
+    paymentHash: string;
+}
+/**
+ * Who is paid and how much. `to` is a priority list when it is an array: the
+ * gateway takes the first address that can issue a provable invoice for the
+ * amount and the rest are the fallback
+ */
+interface Charge {
+    paidTo: string | string[];
+    amount: Amount;
+    /** Where the gateway posts the settlement, signed with the key it publishes */
+    webhookUrl?: string;
+}
+/**
+ * A charge with its price settled, which is what a proof compares the gateway's
+ * answer against. Asking a fiat price twice gives two numbers, so the proof is
+ * handed the one that was actually asked for
+ */
+interface Priced {
+    paidTo: string[];
+    amountMsat: number;
+}
+/**
+ * An invoice you obtained yourself, handed over to be watched. The gateway is
+ * given no address and no amount, so it cannot refuse one recipient rather than
+ * all of them
+ */
+interface Handover {
+    paymentHash: string;
+    verifyUrl: string;
+    expiresAt: number;
+    /** Groups this payment with every other one carrying the same secret */
+    trigger?: string;
+    /**
+     * How many of this trigger's settlements the gateway keeps replayable past the
+     * hour it would otherwise forget them in, up to the ceiling its operator set.
+     * Needs `trigger`, defaults to none
+     */
+    replay?: number;
+    /** Sealed with `seal` for this payment hash, so the gateway stores what it cannot read or move */
+    sealed?: string;
+    webhookUrl?: string;
+}
+/**
+ * Which address would serve an amount, and what the ones ahead of it refused.
+ * `feeMsat` is always zero, the payer pays the recipient's own invoice and the
+ * gateway is never in the money's path
+ */
+interface Quote {
+    lnAddress: string;
+    amountMsat: number;
+    feeMsat: number;
+    minMsat: number;
+    maxMsat: number;
+    metadata: string;
+    refusals: WalletFailure[];
+}
+/**
+ * A one minute pass onto one trigger's stream. It opens that trigger and nothing
+ * else, which is what makes it the thing to hand a browser when the trigger
+ * secret is not. `expiresAt` is unix seconds, like every other time here
+ */
+interface SocketTicket {
+    ticket: string;
+    expiresAt: number;
+}
+/** Why one wallet in the list could not be used */
+type WalletReason = "address-unusable" | "unreachable" | "amount-not-accepted" | "cannot-prove-delivery" | "invoice-refused";
+/** One wallet on the list that could not be used, and the reason it could not */
+interface WalletFailure {
+    address: string;
+    reason: WalletReason;
+}
+/**
+ * What a delivery carries. Everything needed to act on a settlement and to check
+ * it, and nothing else, so a retry is the same size every time
+ */
+interface Settlement {
+    id: string;
+    status: PaymentStatus;
+    paymentHash: string;
+    preimage: string | null;
+    settledAt: number;
+}
+
+export { type Amount as A, type Charge as C, type FiatOptions as F, type Handover as H, type MedianOptions as M, type Payment as P, type Quote as Q, type Settlement as S, type Ticker as T, type WalletFailure as W, coinmate as a, bitstamp as b, coinbase as c, msatFor as d, type Held as e, type MintedPayment as f, type Msat as g, type PaymentStatus as h, type Priced as i, type SocketTicket as j, kraken as k, type WalletReason as l, medianOf as m, type WatchedPayment as n, fiat as o, msat as p, sats as s };

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
   title: thunder-bridge, the endpoint your own service serves
-  version: 1.4.2
+  version: 2.1.1
   license:
     name: MIT
     identifier: MIT
@@ -71,14 +71,17 @@ paths:
       summary: Quote the price, or mint the invoice for a quote already given
       description: |
         Without `to` this answers the payRequest. It calls your `amountMsat()` once, quotes
-        your address list through the gateway, and returns the first address that answers and
-        accepts the amount, along with that wallet's own LUD-06 metadata string byte for byte.
+        your address list, through the gateway or by itself when the trigger is blind, and
+        returns the first address that answers and accepts the amount, along with that
+        wallet's own LUD-06 metadata string byte for byte. A quote naming an address you did
+        not list is refused, so a gateway cannot put its own address in front of your payers.
         `minSendable` and `maxSendable` are both the price, so the payer's wallet offers no
         amount field and the payment is exactly what you asked for.
 
         With `to` this is the callback. The signature is checked first, and a request that was
         not signed by this service is refused before anything is minted, which is what stops a
-        stranger making your endpoint mint invoices on wallets of their choosing. The invoice
+        stranger making your endpoint mint invoices on wallets of their choosing. An address
+        you have since taken off the list is refused too, signed or not. The invoice
         then comes from the recipient's own wallet, never from this service and never from the
         gateway, and `verify` on the answer points at that recipient's LUD-21 endpoint.
 
@@ -200,48 +203,35 @@ paths:
       operationId: verifyBankTransfer
       summary: Say whether the transfer landed, and release the preimage when it did
       description: |
-        Mounted wherever you passed `verifyUrl` to `bankTransfer`, which puts what to look for
-        in the query and signs it. The gateway polls this exactly as it polls a wallet's LUD-21
-        endpoint, and it cannot tell the difference, which is the whole point.
+        Mounted wherever you passed `verifyUrl` to `bankTransfer`, which seals what to look for
+        into the query. The gateway polls this exactly as it polls a wallet's LUD-21 endpoint,
+        and it cannot tell the difference, which is the whole point.
 
-        A query this service did not sign is refused. Without that check the endpoint would
-        answer "did anyone send you this amount with this note" to whoever asked, which is a
-        bank statement handed out one question at a time.
+        A query this service did not seal is refused, and so is one sealed for another
+        account. Without that check the endpoint would answer "did anyone send you this amount
+        with this note" to whoever asked, which is a bank statement handed out one question at
+        a time.
 
-        The preimage is an HMAC of the reference, the amount and the currency under a secret
-        only this service holds, so the gateway can check it hashes to what it was given and
-        still cannot produce it. Nothing is stored between calls.
+        A credit pays when its amount and currency match exactly and the reference stands as a
+        whole word in what the payer wrote, across every field the bank puts a note in, so
+        noise around it is fine. A credit that also names another reference shaped like it, a
+        second order number of the same kind, pays neither.
+
+        The preimage is an HMAC of the account, the amount, the currency, the expiry and the
+        reference under a secret only this service holds, so the gateway can check it hashes to
+        what it was given and still cannot produce it, and a second order under the same
+        reference is another payment. Nothing is stored between calls.
       parameters:
-        - name: ref
+        - name: q
           in: query
           required: true
           description: |
-            What the payer had to leave on the transfer. Matched as a substring against every
-            field the bank puts a note in, so noise around it is fine.
-          schema:
-            type: string
-        - name: minor
-          in: query
-          required: true
-          description: The price in the smallest unit of the currency, so 48055 is 480.55 CZK.
-          schema:
-            type: integer
-            minimum: 1
-        - name: cc
-          in: query
-          required: true
-          description: The three letter currency code the credit has to be in.
+            One blob sealed by `bankTransfer` under the rail secret, naming the account, the
+            amount in minor units, the currency, the expiry and the reference. Padded to one
+            size class, so its length says nothing about what it carries.
           schema:
             type: string
-            minLength: 3
-            maxLength: 3
-        - name: sig
-          in: query
-          required: true
-          description: Hex HMAC-SHA256 over `<ref>|<minor>|<cc>`, minted by `bankTransfer`.
-          schema:
-            type: string
-            pattern: "^[0-9a-f]{64}$"
+            pattern: "^v2\\."
       responses:
         "200":
           description: |
@@ -258,7 +248,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/unsettled"
         "403":
-          description: The signature does not hold, so this service never minted the question.
+          description: The blob does not open under this service's secret, or was sealed for another account, so it never asked the question.
           content:
             application/json:
               schema: