@percayso-community/cayso-contracts 0.23.0

package/dist/citizen-market.d.ts

@@ -0,0 +1,468 @@
+/**
+ * `citizen-market` — the requests, the answers and the closed refusal unions for
+ * the three acts a Citizen performs against the citizen market (CAY-0080):
+ * placing a quote, withdrawing one, and asking the Treasury to buy back.
+ *
+ * This file is the Piper-facing half of CAY-0080's slices 3 and 4, and slice 8
+ * (#289) serves the book: placing a quote at `ROUTES.placeQuote`, withdrawing one at
+ * `ROUTES.withdrawQuote`, and reading the book at `ROUTES.citizenMarket`. Slice 10
+ * (#291) serves the buy-back at `ROUTES.requestBuyBack`. The market stays shut until
+ * every figure it needs is set in the canon: a deployment missing one answers `503`
+ * `citizen_market_not_configured`, and a buy-back missing one of its own answers
+ * `503 buy_back_not_configured`. Neither is a member of these unions.
+ *
+ * ## The holder is the verified subject, so no request names a wallet
+ *
+ * A quote acts for one Citizen Wallet (CAY-0080 §1.1), and that wallet is the
+ * verified subject's own, resolved inside `apps/api` from the holders mapping
+ * (§7). The caller does not say which wallet it is. A request that named one would
+ * be a claim about who the caller is, which Cayso never trusts (CAY-0021), and a
+ * field an Organisation Wallet's or the Treasury's id could be written into. With
+ * no such field, a request cannot express a quote for somebody else's wallet or
+ * for an organisation's. The service records the resolved wallet id on the quote,
+ * and the book never shows it.
+ *
+ * No request and no answer here carries a Percayso identity, a binding, or the
+ * wallet id of the other side of a match.
+ *
+ * ## Integer pence per quote unit, whole quote units
+ *
+ * A price is an integer number of pence per quote unit, in whole price ticks, and
+ * a size is a whole number of quote units (CAY-0080 §1.2, Open decision C). Every
+ * fill's cents and sterling are exact by construction, and nothing on the path
+ * divides. The quote unit and the price tick are canon figures and are never
+ * restated here. A deployment that has not been given one refuses the request as
+ * an unconfigured seam, never as a member of these unions, and never reads the
+ * absence as "no limit".
+ *
+ * ## Refusal at entry is §1.6's set, and it is fixed
+ *
+ * {@link QuoteEntryRefusal} is exactly the set CAY-0080 §1.6 fixed when the record
+ * was accepted, spelled as the record proposed. A refused quote writes nothing.
+ *
+ * Placing a quote also carries an idempotency key, because a bid placed twice by a
+ * retried request can fill twice. Reusing a key for a different quote is refused
+ * with `idempotency_key_reused_for_a_different_quote`. That refusal is about the
+ * request, not about the quote on its merits, so it sits beside §1.6's set in
+ * {@link QuotePlacementRefusal} rather than inside it, and the record's set stays
+ * the record's.
+ *
+ * ## What a placed quote does not say
+ *
+ * A quote is matched on arrival, and whatever does not fill rests (§1.3). Each
+ * fill is a match of its own, with its own key and its own record, which moves
+ * through statuses of its own as it settles cents before sterling (§3.2). None of
+ * that is on {@link QuotePlaced}: the match record is settlement's (slice 9), and
+ * how the sterling leg reaches the seller is Open decision M, which is Simon
+ * James's and not yet answered. The answer to a placement says the quote was
+ * accepted into the book, under which id and until when, and nothing about fills.
+ *
+ * ## Eligibility, and B7's exit window
+ *
+ * All three operations are money-grade in `ASSURANCE_POLICY` (Open decision Q).
+ * Withdrawal is gated at the same bar as placement, so a lower-assurance credential
+ * cannot interfere with a holder's quotes. A holder who no longer meets the profile
+ * has their quotes withdrawn by the market rather than left stranded.
+ *
+ * During B7's exit window an excluded holder places no new quote, and the market
+ * withdraws their resting quotes: Simon named transfer and the buy-back as the exit
+ * routes, and entering the market is not an exit. The buy-back stays open to them.
+ * No exclusion signal reaches Cayso yet, so nothing here names an excluded holder.
+ * A refusal nothing can raise would be a dormant code path, and the case joins in
+ * the slice that delivers the signal, as `payee_excluded` does for the commercial
+ * payment (CAY-0079, Open decision F).
+ *
+ * ## What this file must not decide
+ *
+ *   - **No figures.** Quote unit, price tick, floor, rounding, lifetime, resting
+ *     time and every limit live in the canon PRD. None is restated here.
+ *   - **No match shape.** See above.
+ *   - **No rationing.** A buy-back that eligible sterling cannot meet is refused
+ *     whole, with `eligible_sterling_insufficient` (§2.3). Whether to ration instead
+ *     — pay part, queue, or pay some holders first — is Open decision I, Simon
+ *     James's, and nothing that rations is here. Refusing whole is the answer that
+ *     pays nobody more than the Treasury can meet while he decides.
+ *   - **No per-holder buy-back limit.** Figure 11 goes to Simon with I and M. Until
+ *     he answers it is unset, and the buy-back is shut by configuration rather than
+ *     refused by a reason here, so no limit reason is named.
+ *   - **No Treasury quote.** The Treasury rests no quote in the book (Open decision
+ *     G). Its buying side is {@link BuyBackRequest}, and its selling side is the
+ *     purchase.
+ *   - **No free text.** A quote has a side, a limit price and a size. A field in
+ *     which two people could arrange a price elsewhere, or send a message, would
+ *     bring the book inside the Online Safety Act gate (CAY-0080, Consequences).
+ */
+import type { Cents, Millis } from './wallet.js';
+/** A **bid** is a quote to buy, and an **ask** a quote to sell. */
+export type QuoteSide = 'bid' | 'ask';
+/**
+ * A Citizen placing a limit quote in the citizen market (CAY-0080 §1.1). There is
+ * no quote that fills at whatever the book offers, no stop quote, no hidden quote
+ * and no quote on behalf of somebody else, so there is no field for any of them.
+ */
+export interface QuoteRequest {
+    readonly side: QuoteSide;
+    /**
+     * Integer pence per quote unit, a positive whole number of price ticks, no lower
+     * than the floor reference and no higher than the published value now.
+     */
+    readonly limitPricePence: number;
+    /** A positive whole number of quote units. */
+    readonly sizeQuoteUnits: number;
+    /** Caller-generated, unique per holder. The same key never places two quotes; a repeat REPLAYS. */
+    readonly idempotencyKey: string;
+}
+/**
+ * A quote the book accepted. It rests until it is matched, withdrawn by its holder
+ * after the minimum resting time, withdrawn by the market, or expires.
+ *
+ * It carries no wallet id. The holder knows their own wallet, and the book shows
+ * price and size only.
+ */
+export interface Quote {
+    /** A handle to withdraw it by. */
+    readonly quoteId: string;
+    readonly side: QuoteSide;
+    readonly limitPricePence: number;
+    readonly sizeQuoteUnits: number;
+    readonly placedAt: Millis;
+    /** When the quote lifetime ends, if it is still resting then. */
+    readonly expiresAt: Millis;
+}
+/**
+ * The quote was accepted into the book. Answered for the request that placed it and
+ * for every replay of its key, in the same shape and with the same `quoteId`.
+ */
+export interface QuotePlaced {
+    readonly outcome: 'placed';
+    readonly quote: Quote;
+}
+/** The quote was refused, with one reason. Nothing was written and nothing was reserved. */
+export interface QuoteRefused {
+    readonly outcome: 'refused';
+    readonly error: QuotePlacementRefusal;
+}
+/** The ONE declared answer to placing a quote, discriminated by `outcome`. */
+export type QuoteResponse = QuotePlaced | QuoteRefused;
+/**
+ * Why a quote was refused at entry: CAY-0080 §1.6's set, closed, spelled here.
+ *
+ * The record fixed the SET when it was accepted, and this contract fixes the
+ * spelling. A new reason is a new member and a contract version, never a
+ * free-text field.
+ */
+export type QuoteEntryRefusal = 
+/**
+ * The verification method is outside the money-grade profile
+ * (`ASSURANCE_POLICY['place-quote']`). `dev-bypass` is never inside it.
+ */
+'assurance_not_money_grade'
+/** The wallet the verified subject resolves to is an Organisation Wallet or the Treasury (§6). */
+ | 'wallet_not_a_citizens'
+/** No wallet is bound to the verified subject now, for example after erasure. */
+ | 'wallet_has_no_live_binding'
+/** The size is zero, negative or not a whole number of quote units. */
+ | 'size_not_whole_quote_units'
+/** The price is not a positive whole number of price ticks. */
+ | 'price_not_whole_ticks'
+/** The limit sits below the floor reference now (Open decision E). */
+ | 'price_below_floor_reference'
+/** The limit sits above the published value now (Open decision D). */
+ | 'price_above_published_value'
+/**
+ * An ask: the wallet's unrestricted cents that are neither frozen nor already
+ * reserved do not cover it. Restricted cents are never counted (§4.1).
+ */
+ | 'unrestricted_cents_insufficient'
+/**
+ * The holder has a resting quote on the other side that this one would match.
+ * "The holder" is decided by the binding, not by wallet id (§5.3).
+ */
+ | 'quote_would_cross_own_quote'
+/** The quote passes the per-quote size limit. */
+ | 'quote_size_above_limit'
+/** The holder already has the permitted number of resting quotes. */
+ | 'resting_quotes_at_limit'
+/** The holder has entered the permitted number of quotes in the period. */
+ | 'quote_rate_limit_reached'
+/** The quote would take the holder past the permitted volume in the period. */
+ | 'holder_volume_limit_reached'
+/** The published value cannot be read, so neither bound can be checked. */
+ | 'published_value_unavailable';
+/**
+ * Everything a placement can be refused with: §1.6's set, and the key discipline
+ * every value-moving request on this surface keeps.
+ */
+export type QuotePlacementRefusal = QuoteEntryRefusal
+/** The key was already used by this holder for a different side, price or size. */
+ | 'idempotency_key_reused_for_a_different_quote'
+/**
+ * The quote met the book and the sterling leg could not be reached to authorise the
+ * match (CAY-0080 §3.2). Nothing was written — not the quote, not a match — so the
+ * placement may be retried unchanged under the same key.
+ */
+ | 'sterling_leg_unavailable';
+/** A holder withdrawing one of their own resting quotes. */
+export interface QuoteWithdrawalRequest {
+    readonly quoteId: string;
+}
+/**
+ * A withdrawal. What had not filled leaves the book, and the reservation an ask held
+ * on it is released, exactly once. Fills already matched are unaffected.
+ */
+export interface QuoteWithdrawal {
+    readonly quoteId: string;
+    /** The part of the size that had not filled and left the book with the withdrawal. */
+    readonly withdrawnQuoteUnits: number;
+    readonly withdrawnAt: Millis;
+}
+/**
+ * The quote was withdrawn. Answered for the request that withdrew it and for every
+ * repeat of that request, in the same shape: withdrawing twice is one withdrawal.
+ */
+export interface QuoteWithdrawn {
+    readonly outcome: 'withdrawn';
+    readonly withdrawal: QuoteWithdrawal;
+}
+/** The withdrawal was refused, with one reason. The quote rests as it was. */
+export interface QuoteWithdrawalRefused {
+    readonly outcome: 'refused';
+    readonly error: QuoteWithdrawalRefusal;
+}
+/** The ONE declared answer to withdrawing a quote, discriminated by `outcome`. */
+export type QuoteWithdrawalResponse = QuoteWithdrawn | QuoteWithdrawalRefused;
+/**
+ * Why a withdrawal was refused. Closed. Refused withdrawals are counted rather than
+ * hidden, so a holder can see why a withdrawal waited (CAY-0080 §5.2).
+ */
+export type QuoteWithdrawalRefusal = 
+/** The method is outside `ASSURANCE_POLICY['withdraw-quote']`, the same bar as placing one (Q). */
+'assurance_not_money_grade'
+/** No wallet is bound to the verified subject now. */
+ | 'wallet_has_no_live_binding'
+/**
+ * No quote has this id under the caller's wallet. Somebody else's quote answers
+ * the same, so the answer is never a way to learn whose a quote is.
+ */
+ | 'quote_not_found'
+/** The quote already left the book: filled in full, expired, or withdrawn by the market. */
+ | 'quote_not_resting'
+/** The quote has not yet rested for the minimum resting time (§5.2). */
+ | 'quote_minimum_resting_time_not_reached';
+/**
+ * A Citizen asking the Treasury's standing buy-back to buy unrestricted cents, at
+ * the floor reference, in whole quote units (CAY-0080 §2.2). It is not matched and
+ * it is not in the book. The cents bought are cancelled (Open decision H).
+ */
+export interface BuyBackRequest {
+    /** A positive whole number of quote units. */
+    readonly sizeQuoteUnits: number;
+    /** Caller-generated, unique per holder. The same key never buys back twice; a repeat REPLAYS. */
+    readonly idempotencyKey: string;
+}
+/**
+ * A buy-back the Treasury made. The cents have left the holder's wallet and been
+ * cancelled: no holding arrived anywhere, and they re-enter circulation only by a
+ * purchase at the published value.
+ *
+ * It is priced at the floor reference and published value recorded at authorisation,
+ * so a quickening in flight does not change what the holder receives. The payout
+ * stays behind the fake gateway until #119 and the FCA outcome, and its own status
+ * is not on this shape (CAY-0080 §3.4).
+ */
+export interface BuyBack {
+    readonly buyBackId: string;
+    readonly sizeQuoteUnits: number;
+    /** The cents that left the wallet and were cancelled. */
+    readonly cents: Cents;
+    /** The published value at authorisation, in pence per ₡1. */
+    readonly publishedValuePence: number;
+    /** The floor reference at authorisation, in pence per quote unit. */
+    readonly floorReferencePence: number;
+    /** What the Treasury pays for it: the floor reference times the size. */
+    readonly sterlingPence: number;
+    readonly boughtBackAt: Millis;
+}
+/**
+ * The buy-back was made. Answered for the request that made it and for every replay
+ * of its key, in the same shape.
+ */
+export interface BuyBackMade {
+    readonly outcome: 'bought-back';
+    readonly buyBack: BuyBack;
+}
+/** The buy-back was refused whole, with one reason. Nothing moved and nothing is paid. */
+export interface BuyBackRefused {
+    readonly outcome: 'refused';
+    readonly error: BuyBackRefusal;
+}
+/** The ONE declared answer to a buy-back, discriminated by `outcome`. */
+export type BuyBackResponse = BuyBackMade | BuyBackRefused;
+/**
+ * Why a buy-back was refused. Closed, and refused before anything is paid (§2.2).
+ *
+ * A shortfall of eligible sterling is refused whole, never rationed (§2.3); whether
+ * to ration is Open decision I, Simon James's. There is no member for a per-holder
+ * limit (figure 11), which is his too and joins when he answers. See the file's
+ * docblock.
+ */
+export type BuyBackRefusal = 
+/** The method is outside `ASSURANCE_POLICY['request-buy-back']`. */
+'assurance_not_money_grade'
+/**
+ * The wallet the verified subject resolves to is an Organisation Wallet or the
+ * Treasury. An organisation is paid only by commercial payment (§6).
+ */
+ | 'wallet_not_a_citizens'
+/** No wallet is bound to the verified subject now. */
+ | 'wallet_has_no_live_binding'
+/** The size is zero, negative or not a whole number of quote units. */
+ | 'size_not_whole_quote_units'
+/**
+ * The wallet's unrestricted cents that are neither frozen nor reserved do not
+ * cover it. Restricted cents are never counted: cash-out through the Treasury is
+ * refused for every restricted kind.
+ */
+ | 'unrestricted_cents_insufficient'
+/** The published value cannot be read, so the floor reference cannot be priced. */
+ | 'published_value_unavailable'
+/**
+ * The Treasury's eligible sterling — never its bank balance — cannot meet the
+ * sterling this buy-back would pay, after what earlier buy-backs have reserved
+ * (§2.3). Refused whole: nothing is partly paid, queued or rationed, and the
+ * Treasury operator is alarmed. A later request may be met once eligible sterling
+ * is. Pending Simon James's answer to Open decision I.
+ */
+ | 'eligible_sterling_insufficient'
+/** The key was already used by this holder for a different size. */
+ | 'idempotency_key_reused_for_a_different_buy_back'
+/**
+ * Too many concurrent draws on the wallet, and the retries ran out. Nothing moved,
+ * and the caller may try again under the same key.
+ */
+ | 'carve_contended';
+/**
+ * One side of the book at its best price: the price, and the size resting at it
+ * across every quote at that price. It names no quote, no wallet and no holder, and
+ * it says nothing about how many quotes make up the size (CAY-0080 §1.4).
+ */
+export interface BookLevel {
+    /** Integer pence per quote unit. */
+    readonly limitPricePence: number;
+    /** Whole quote units resting at this price, net of what has already matched. */
+    readonly sizeQuoteUnits: number;
+}
+/** Where a quote stands. A quote leaves the book once, and does not come back. */
+export type QuoteStatus = 'resting' | 'filled' | 'withdrawn' | 'expired';
+/**
+ * Why a quote was withdrawn. A closed union, so a consumer renders it rather than
+ * reading prose, and a new reason is a new member and a contract version.
+ *
+ *   - `holder_withdrew` — the holder withdrew it, after the minimum resting time.
+ *   - `below_floor_reference` — a quickening raised the floor reference above its
+ *     limit, and the market withdrew it before the first match under the new band
+ *     (CAY-0080 §1.5). This is how the holder is told.
+ *   - `no_live_binding` — its wallet was bound to nobody when the book reached it,
+ *     for example after erasure (§7).
+ *   - `authorisation_refused` — a BID only: it met an ask, and the holder's sterling
+ *     could not be authorised for the match (CAY-0080 §3.2, step 2). No cents moved
+ *     and the ask rests as it was; the bid leaves the book rather than meeting the
+ *     next ask with sterling that was just refused.
+ *
+ * There is no member for B7's exit window: nothing in this version can raise it, and
+ * a reason nothing can raise would be a dormant code path.
+ */
+export type QuoteWithdrawalReason = 'holder_withdrew' | 'below_floor_reference' | 'no_live_binding' | 'authorisation_refused';
+/**
+ * One of the caller's own quotes that was not withdrawn: resting, filled, or
+ * expired. It carries no reason, because only a withdrawal has one.
+ */
+export interface OwnQuoteNotWithdrawn {
+    readonly quoteId: string;
+    readonly side: QuoteSide;
+    readonly limitPricePence: number;
+    readonly sizeQuoteUnits: number;
+    readonly placedAt: Millis;
+    readonly expiresAt: Millis;
+    /** The part of the size that has matched. What is left is the size less this. */
+    readonly filledQuoteUnits: number;
+    /** The earliest moment the holder may withdraw it: the minimum resting time after placing. */
+    readonly withdrawableFrom: Millis;
+    readonly status: 'resting' | 'filled' | 'expired';
+}
+/** One of the caller's own quotes that was withdrawn, and why. */
+export interface OwnQuoteWithdrawn {
+    readonly quoteId: string;
+    readonly side: QuoteSide;
+    readonly limitPricePence: number;
+    readonly sizeQuoteUnits: number;
+    readonly placedAt: Millis;
+    readonly expiresAt: Millis;
+    readonly filledQuoteUnits: number;
+    readonly withdrawableFrom: Millis;
+    readonly status: 'withdrawn';
+    readonly withdrawalReason: QuoteWithdrawalReason;
+}
+/**
+ * One of the caller's own quotes, as the book stands. Discriminated by `status`,
+ * and only a withdrawn quote carries a reason, so a reason cannot be attached to a
+ * quote that was not withdrawn. The schema holds the same pair (migration 0050).
+ */
+export type OwnQuote = OwnQuoteNotWithdrawn | OwnQuoteWithdrawn;
+/**
+ * What each side sees (CAY-0080 §1.4, Open decision F): the published value with its
+ * band, the floor reference, and the best bid and the best ask with the size resting
+ * at each. The caller's own quotes are beside them, which is how a holder is told
+ * that the market withdrew one.
+ *
+ * It carries no match price, no feed, no history, no chart, no change since
+ * anything, and nothing about the next quickening. Each of those invites reading
+ * Cayso as something held to see what it does, and the last is a forecast.
+ *
+ * The caller's own quotes are those still resting and those that left the book no
+ * longer ago than a quote may rest. That is the holder's own record, not the book's
+ * history, and it names nobody else.
+ */
+export interface CitizenMarketView {
+    /** What ₡1 is worth in sterling now, in pence. Never a price. */
+    readonly publishedValuePence: number;
+    /** The band the published value is set by. */
+    readonly band: number;
+    /**
+     * The upper bound: the published value converted to pence per quote unit,
+     * rounded down so the band narrows.
+     */
+    readonly publishedValuePerQuoteUnitPence: number;
+    /**
+     * The lower bound: what the Treasury's standing buy-back pays per quote unit now,
+     * rounded up so the band narrows.
+     */
+    readonly floorReferencePence: number;
+    /** The whole number of cents one quote unit is, as this deployment is configured. */
+    readonly quoteUnitCents: Cents;
+    /** The whole number of pence a price moves by, as this deployment is configured. */
+    readonly priceTickPence: number;
+    /** The best resting bid, or null when none rests. */
+    readonly bestBid: BookLevel | null;
+    /** The best resting ask, or null when none rests. */
+    readonly bestAsk: BookLevel | null;
+    readonly ownQuotes: readonly OwnQuote[];
+}
+/** The book, as it stood when it was read. */
+export interface CitizenMarketViewed {
+    readonly outcome: 'viewed';
+    readonly market: CitizenMarketView;
+}
+/**
+ * Why the book was not shown. Closed, and each member means what it means at entry:
+ * the book is read by a Citizen with a live binding, because the view carries their
+ * own quotes, and it is priced from the published value, which has to be readable.
+ */
+export type CitizenMarketViewRefusal = 'wallet_not_a_citizens' | 'wallet_has_no_live_binding' | 'published_value_unavailable';
+/** The book was not shown, with one reason. Nothing was written. */
+export interface CitizenMarketViewRefused {
+    readonly outcome: 'refused';
+    readonly error: CitizenMarketViewRefusal;
+}
+/** The ONE declared answer to reading the book, discriminated by `outcome`. */
+export type CitizenMarketResponse = CitizenMarketViewed | CitizenMarketViewRefused;

package/dist/citizen-market.js

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2026 Percayso Community
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};