@peable.to/contracts 5.6.0 → 6.0.0

package/dist/cjs/resources/payments/social.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.socialRoutes = exports.enrichSchema = exports.enrichParams = exports.socialPaymentsSchema = exports.socialPaymentSchema = exports.socialPaymentsQuery = exports.socialReceiveCursorSchema = exports.socialReceiveCursorQuery = exports.socialNextAddressSchema = exports.socialNextAddressParams = exports.socialPaymentSourceParams = exports.enrichmentResultSchema = exports.socialPaymentSourceSchema = void 0;
+exports.socialRoutes = exports.enrichSchema = exports.enrichParams = exports.socialPaymentsSchema = exports.socialPaymentSchema = exports.socialPaymentsQuery = exports.socialReceiveAddressesSchema = exports.socialReceiveAddressSchema = exports.socialReceiveAddressesQuery = exports.socialReceiveCursorSchema = exports.socialReceiveCursorQuery = exports.socialNextAddressSchema = exports.socialNextAddressParams = exports.socialPaymentSourceParams = exports.enrichmentResultSchema = exports.socialPaymentSourceSchema = void 0;
 const zod_1 = require("zod");
 const objects_1 = require("../../common/objects");
+const params_1 = require("../../common/params");
+/** The highest BIP32 non-hardened child index, `int4`'s ceiling (`schema/valueSets.ts`). */
+const MAX_DERIVATION_INDEX = 2147483647;
 const primitives_1 = require("../../common/primitives");
 const route_1 = require("../../route");
 const payments_1 = require("../../vocabulary/payments");
@@ -86,10 +89,10 @@ exports.socialNextAddressSchema = (0, objects_1.defineComponent)('SocialNextAddr
 const networkQuery = zod_1.z.object({ network: primitives_1.network });
 exports.socialReceiveCursorQuery = networkQuery;
 /**
- * Lets the caller's device resync its watch window: every `next_address`
- * advances a monotonic index whether or not it is ever paid, so a burst of
- * reservations can outrun a device that widens only on payment. Watch
- * `0..reserved_through + gap`.
+ * The caller's cursor and keys. The addresses to watch are
+ * `GET /v1/social/me/receive_addresses` (ADR 0021 D9, amended 2026-11-06);
+ * `reserved_through` only says how far the cursor went, and the device
+ * compares its key with `account_identity_public_key`.
  */
 exports.socialReceiveCursorSchema = (0, objects_1.defineComponent)('SocialReceiveCursor', zod_1.z
     .object({
@@ -108,6 +111,58 @@ exports.socialReceiveCursorSchema = (0, objects_1.defineComponent)('SocialReceiv
         .describe("The caller's CURRENT identity public key: their DID's `#key-1`, read from Oxy at request time (never cached), as lowercase hex of the key exactly as the DID publishes it (`publicKeyHex`, the compressed secp256k1 key) — the same encoding as `identity_public_key`. Compare the device's key with THIS, not with `identity_public_key`, which only says what the last reservation used. `null` for a keyless (custodial) account."),
 })
     .strict());
+/**
+ * The caller's receive addresses after a sync cursor (ADR 0021 D9, amended
+ * 2026-11-06). `after` is the `sync_cursor` of the previous answer, `0` (the
+ * default) from the start.
+ */
+exports.socialReceiveAddressesQuery = zod_1.z
+    .object({
+    network: primitives_1.network,
+    after: (0, params_1.queryInteger)({ min: 0, max: MAX_DERIVATION_INDEX })
+        .optional()
+        .describe('The `sync_cursor` of the previous page or sync; absent (or `0`) lists from the first address.'),
+    limit: (0, params_1.queryInteger)({ min: 1, max: payments_1.SOCIAL_RECEIVE_ADDRESSES_PAGE_MAX })
+        .optional()
+        .describe(`At most this many addresses (default ${payments_1.SOCIAL_RECEIVE_ADDRESSES_PAGE_DEFAULT}); a page exceeds it only by addresses sharing its last index.`),
+})
+    .strict();
+/**
+ * One FairCoin address the gateway handed out in the caller's Peable wallet —
+ * for a payment (merchant, seller, invoice, raw intent, one output of a split
+ * payment) or an `@username` request — under ANY key the account has had.
+ * Addresses are never reused: each is a fresh index of the account's one
+ * cursor (ADR 0002, ADR 0021 D5, D9).
+ */
+exports.socialReceiveAddressSchema = (0, objects_1.defineComponent)('SocialReceiveAddress', zod_1.z
+    .object({
+    address: zod_1.z.string().describe('The FairCoin address.'),
+    derivation_index: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .describe("Its index in the account's social-receive tree (`deriveSocialReceiveAddress(key, index)`); index 0, the stable default address, is never handed out."),
+    identity_public_key: zod_1.z
+        .string()
+        .nullable()
+        .describe("The identity public key the address was derived from, in the encoding of the cursor's `identity_public_key` (lowercase hex of the DID `#key-1` bytes). It may be a key the account has since replaced. `null` only for an address handed out before keys were recorded."),
+    network: primitives_1.network,
+    created: primitives_1.unixSeconds.describe('When the address was handed out.'),
+})
+    .strict());
+exports.socialReceiveAddressesSchema = (0, objects_1.defineComponent)('SocialReceiveAddresses', zod_1.z
+    .object({
+    addresses: zod_1.z
+        .array(exports.socialReceiveAddressSchema)
+        .describe('In ascending `derivation_index`, each address once.'),
+    has_more: zod_1.z.boolean().describe('More addresses follow `sync_cursor`: ask again with it.'),
+    sync_cursor: zod_1.z
+        .number()
+        .int()
+        .nonnegative()
+        .describe('Pass as `after` to continue — the highest `derivation_index` in this page, or `after` when the page is empty. Monotonic: an address handed out later always has a higher index, so a wallet that stored it misses nothing by asking from it.'),
+})
+    .strict());
 exports.socialPaymentsQuery = networkQuery;
 /**
  * One social payment as the CALLER saw it — the address-free view, and the
@@ -148,7 +203,7 @@ exports.socialRoutes = [
         path: '/v1/social/{username}/next_address',
         tag: 'Social payments',
         summary: 'Reserve an address to pay a person',
-        description: "A fresh address of the recipient's, derived from their Oxy identity key. Limited per (sender, recipient) pair; a recipient without an identity answers 409 `keyless_recipient`, and one whose wallet watches no further address (every index below its watched bound is taken) 503 `faircoin_receive_tree_full`; paying yourself is refused.",
+        description: "A fresh address of the recipient's, derived from their Oxy identity key — or the one this sender already holds and has not paid. Limited per sender and per (sender, recipient) pair; a recipient without an identity answers 409 `keyless_recipient`, and one handed too many fresh `@username` addresses in the last day 503 `faircoin_capacity_reached`; paying yourself is refused.",
         auth: 'user',
         params: { username: 'The recipient’s Oxy username.' },
         body: exports.socialNextAddressParams,
@@ -165,6 +220,17 @@ exports.socialRoutes = [
         query: exports.socialReceiveCursorQuery,
         response: exports.socialReceiveCursorSchema,
     }),
+    (0, route_1.defineRoute)({
+        operationId: 'listSocialReceiveAddresses',
+        method: 'get',
+        path: '/v1/social/me/receive_addresses',
+        tag: 'Social payments',
+        summary: "List the caller's receive addresses",
+        description: "Every FairCoin address handed out in the caller's Peable wallet on `network` — payments and `@username` alike, under every key the account has had — after `after`, in ascending index, for whoever the session acts as (an organization's, when acting as it). The wallet watches exactly this set (ADR 0021 D9). Read-only.",
+        auth: 'user',
+        query: exports.socialReceiveAddressesQuery,
+        response: exports.socialReceiveAddressesSchema,
+    }),
     (0, route_1.defineRoute)({
         operationId: 'listSocialPayments',
         method: 'get',

package/dist/cjs/vocabulary/errors.js

@@ -134,8 +134,7 @@ exports.ERROR_CODE_DESCRIPTIONS = {
     faircoin_price_unavailable: 'No fresh FairCoin price exists right now, so this order cannot be quoted in FAIR. The other payment methods still work; try FairCoin again shortly.',
     faircoin_wallet_missing: "The Peable wallet that receives this payment (the merchant owner's, or the seller's) isn't set up yet, so it cannot be paid in FairCoin. The other payment methods still work.",
     faircoin_network_closed: 'FairCoin payments on this network are not open on this deployment yet. The other payment methods still work.',
-    faircoin_capacity_reached: 'Too many FairCoin payments to this recipient are waiting to be paid right now, so no new FairCoin address can be handed out. The other payment methods still work; try FairCoin again shortly.',
-    faircoin_receive_tree_full: "Every FairCoin address the recipient's Peable wallet watches has been handed out, so no new one can be derived for them. Nothing was reserved.",
+    faircoin_capacity_reached: 'Too many FairCoin addresses of this recipient were handed out in the last day without being paid, so no new one is handed out right now. Nothing was reserved. The other payment methods still work; try FairCoin again later.',
     faircoin_amount_too_small: "One seller's share of this order is below the smallest amount the FairCoin network relays, so it cannot be paid in FairCoin. The other payment methods still work.",
     credit_note_exceeds_invoice: "The credit note's amount exceeds what the invoice can still credit.",
     test_clock_unexpected_state: 'The test clock is advancing; wait until it is ready.',

package/dist/cjs/vocabulary/index.js

@@ -38,4 +38,3 @@ __exportStar(require("./identity"), exports);
 __exportStar(require("./merchants"), exports);
 __exportStar(require("./paymentMethodConfigurations"), exports);
 __exportStar(require("./realtime"), exports);
-__exportStar(require("./receiveTree"), exports);

package/dist/cjs/vocabulary/payments.js

@@ -4,7 +4,7 @@
 // contracts are built from. Zod-free, so the wallet and the shared types read
 // them without bundling a schema.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SIMULATED_FAIRCOIN_OUTCOMES = exports.ENRICH_MAX_ADDRESSES = exports.ENRICHMENT_KINDS = exports.SOCIAL_PAYMENT_DIRECTIONS = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.SETUP_INTENT_CANCELLATION_REASONS = exports.SETUP_INTENT_USAGES = exports.SETUP_INTENT_STATUSES = exports.DISPUTE_EVIDENCE_TEXT_MAX = exports.DISPUTE_FILE_EVIDENCE_FIELDS = exports.DISPUTE_TEXT_EVIDENCE_FIELDS = exports.DISPUTE_REASONS = exports.DISPUTE_STATUSES = exports.SETTLEMENT_STATUSES = exports.REFUND_ORIGINS = exports.REFUND_REASONS = exports.REFUND_STATUSES = exports.CLIENT_ACTION_KINDS = exports.PAYMENT_ERROR_TYPES = exports.PAYMENT_METHOD_TYPES = exports.CARD_RAIL_PAYMENT_METHOD_TYPES = exports.PAYMENT_INTENT_SETUP_FUTURE_USAGES = exports.PAYMENT_INTENT_CAPTURE_METHODS = exports.MERCHANT_CANCELLATION_REASONS = exports.PAYMENT_INTENT_CANCELLATION_REASONS = exports.PAYMENT_INTENT_STATUSES = exports.PAYMENT_INTENT_MAX_EXPIRES_IN_SECONDS = exports.PAYMENT_INTENT_RAILS = void 0;
+exports.SIMULATED_FAIRCOIN_OUTCOMES = exports.SOCIAL_RECEIVE_ADDRESSES_PAGE_MAX = exports.SOCIAL_RECEIVE_ADDRESSES_PAGE_DEFAULT = exports.ENRICH_MAX_ADDRESSES = exports.ENRICHMENT_KINDS = exports.SOCIAL_PAYMENT_DIRECTIONS = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.SETUP_INTENT_CANCELLATION_REASONS = exports.SETUP_INTENT_USAGES = exports.SETUP_INTENT_STATUSES = exports.DISPUTE_EVIDENCE_TEXT_MAX = exports.DISPUTE_FILE_EVIDENCE_FIELDS = exports.DISPUTE_TEXT_EVIDENCE_FIELDS = exports.DISPUTE_REASONS = exports.DISPUTE_STATUSES = exports.SETTLEMENT_STATUSES = exports.REFUND_ORIGINS = exports.REFUND_REASONS = exports.REFUND_STATUSES = exports.CLIENT_ACTION_KINDS = exports.PAYMENT_ERROR_TYPES = exports.PAYMENT_METHOD_TYPES = exports.CARD_RAIL_PAYMENT_METHOD_TYPES = exports.PAYMENT_INTENT_SETUP_FUTURE_USAGES = exports.PAYMENT_INTENT_CAPTURE_METHODS = exports.MERCHANT_CANCELLATION_REASONS = exports.PAYMENT_INTENT_CANCELLATION_REASONS = exports.PAYMENT_INTENT_STATUSES = exports.PAYMENT_INTENT_MAX_EXPIRES_IN_SECONDS = exports.PAYMENT_INTENT_RAILS = void 0;
 /**
  * Which rail moves the money (ADR 0001 D1). On the INTENT, not on the merchant:
  * one merchant takes both, and the rail decides which fields mean anything.
@@ -13,8 +13,8 @@ exports.PAYMENT_INTENT_RAILS = ['faircoin', 'card'];
 /**
  * The longest a PaymentIntent created through the API may stay payable before
  * it expires (`expires_in_seconds`): 24 hours. A FairCoin payment holds a
- * reserved address in the recipient's wallet for as long as it is payable, so
- * an unbounded expiry is an address nobody can ever recycle (ADR 0021 D9).
+ * reserved address in the recipient's wallet for as long as it is payable, and
+ * the recipient's bound on unpaid addresses looks back over a day (ADR 0021 D9).
  */
 exports.PAYMENT_INTENT_MAX_EXPIRES_IN_SECONDS = 24 * 60 * 60;
 /**
@@ -200,6 +200,12 @@ exports.SOCIAL_PAYMENT_DIRECTIONS = ['sent', 'received'];
 exports.ENRICHMENT_KINDS = ['merchant', 'user', 'unknown'];
 /** How many addresses one `POST /v1/enrich` resolves (and one social history lists). */
 exports.ENRICH_MAX_ADDRESSES = 50;
+/**
+ * One page of `GET /v1/social/me/receive_addresses` (ADR 0021 D9, amended
+ * 2026-11-06): the default and the most a wallet may ask for at once.
+ */
+exports.SOCIAL_RECEIVE_ADDRESSES_PAGE_DEFAULT = 500;
+exports.SOCIAL_RECEIVE_ADDRESSES_PAGE_MAX = 1000;
 // ---------------------------------------------------------------------------
 // Test helpers
 // ---------------------------------------------------------------------------

package/dist/esm/resources/payments/social.js

@@ -1,8 +1,11 @@
 import { z } from 'zod';
 import { defineComponent } from '../../common/objects.js';
+import { queryInteger } from '../../common/params.js';
+/** The highest BIP32 non-hardened child index, `int4`'s ceiling (`schema/valueSets.ts`). */
+const MAX_DERIVATION_INDEX = 2147483647;
 import { network, unixSeconds } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
-import { ENRICH_MAX_ADDRESSES, ENRICHMENT_KINDS, SOCIAL_PAYMENT_DIRECTIONS, SOCIAL_SOURCE_APP_MAX_LENGTH, SOCIAL_SOURCE_REF_MAX_LENGTH, } from '../../vocabulary/payments.js';
+import { ENRICH_MAX_ADDRESSES, ENRICHMENT_KINDS, SOCIAL_PAYMENT_DIRECTIONS, SOCIAL_RECEIVE_ADDRESSES_PAGE_DEFAULT, SOCIAL_RECEIVE_ADDRESSES_PAGE_MAX, SOCIAL_SOURCE_APP_MAX_LENGTH, SOCIAL_SOURCE_REF_MAX_LENGTH, } from '../../vocabulary/payments.js';
 /**
  * Social payments (pay a person by `@username`) and transaction enrichment —
  * the wallet's routes, called with the person's own Oxy session. Display-only
@@ -83,10 +86,10 @@ export const socialNextAddressSchema = defineComponent('SocialNextAddress', z
 const networkQuery = z.object({ network });
 export const socialReceiveCursorQuery = networkQuery;
 /**
- * Lets the caller's device resync its watch window: every `next_address`
- * advances a monotonic index whether or not it is ever paid, so a burst of
- * reservations can outrun a device that widens only on payment. Watch
- * `0..reserved_through + gap`.
+ * The caller's cursor and keys. The addresses to watch are
+ * `GET /v1/social/me/receive_addresses` (ADR 0021 D9, amended 2026-11-06);
+ * `reserved_through` only says how far the cursor went, and the device
+ * compares its key with `account_identity_public_key`.
  */
 export const socialReceiveCursorSchema = defineComponent('SocialReceiveCursor', z
     .object({
@@ -105,6 +108,58 @@ export const socialReceiveCursorSchema = defineComponent('SocialReceiveCursor',
         .describe("The caller's CURRENT identity public key: their DID's `#key-1`, read from Oxy at request time (never cached), as lowercase hex of the key exactly as the DID publishes it (`publicKeyHex`, the compressed secp256k1 key) — the same encoding as `identity_public_key`. Compare the device's key with THIS, not with `identity_public_key`, which only says what the last reservation used. `null` for a keyless (custodial) account."),
 })
     .strict());
+/**
+ * The caller's receive addresses after a sync cursor (ADR 0021 D9, amended
+ * 2026-11-06). `after` is the `sync_cursor` of the previous answer, `0` (the
+ * default) from the start.
+ */
+export const socialReceiveAddressesQuery = z
+    .object({
+    network,
+    after: queryInteger({ min: 0, max: MAX_DERIVATION_INDEX })
+        .optional()
+        .describe('The `sync_cursor` of the previous page or sync; absent (or `0`) lists from the first address.'),
+    limit: queryInteger({ min: 1, max: SOCIAL_RECEIVE_ADDRESSES_PAGE_MAX })
+        .optional()
+        .describe(`At most this many addresses (default ${SOCIAL_RECEIVE_ADDRESSES_PAGE_DEFAULT}); a page exceeds it only by addresses sharing its last index.`),
+})
+    .strict();
+/**
+ * One FairCoin address the gateway handed out in the caller's Peable wallet —
+ * for a payment (merchant, seller, invoice, raw intent, one output of a split
+ * payment) or an `@username` request — under ANY key the account has had.
+ * Addresses are never reused: each is a fresh index of the account's one
+ * cursor (ADR 0002, ADR 0021 D5, D9).
+ */
+export const socialReceiveAddressSchema = defineComponent('SocialReceiveAddress', z
+    .object({
+    address: z.string().describe('The FairCoin address.'),
+    derivation_index: z
+        .number()
+        .int()
+        .positive()
+        .describe("Its index in the account's social-receive tree (`deriveSocialReceiveAddress(key, index)`); index 0, the stable default address, is never handed out."),
+    identity_public_key: z
+        .string()
+        .nullable()
+        .describe("The identity public key the address was derived from, in the encoding of the cursor's `identity_public_key` (lowercase hex of the DID `#key-1` bytes). It may be a key the account has since replaced. `null` only for an address handed out before keys were recorded."),
+    network,
+    created: unixSeconds.describe('When the address was handed out.'),
+})
+    .strict());
+export const socialReceiveAddressesSchema = defineComponent('SocialReceiveAddresses', z
+    .object({
+    addresses: z
+        .array(socialReceiveAddressSchema)
+        .describe('In ascending `derivation_index`, each address once.'),
+    has_more: z.boolean().describe('More addresses follow `sync_cursor`: ask again with it.'),
+    sync_cursor: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe('Pass as `after` to continue — the highest `derivation_index` in this page, or `after` when the page is empty. Monotonic: an address handed out later always has a higher index, so a wallet that stored it misses nothing by asking from it.'),
+})
+    .strict());
 export const socialPaymentsQuery = networkQuery;
 /**
  * One social payment as the CALLER saw it — the address-free view, and the
@@ -145,7 +200,7 @@ export const socialRoutes = [
         path: '/v1/social/{username}/next_address',
         tag: 'Social payments',
         summary: 'Reserve an address to pay a person',
-        description: "A fresh address of the recipient's, derived from their Oxy identity key. Limited per (sender, recipient) pair; a recipient without an identity answers 409 `keyless_recipient`, and one whose wallet watches no further address (every index below its watched bound is taken) 503 `faircoin_receive_tree_full`; paying yourself is refused.",
+        description: "A fresh address of the recipient's, derived from their Oxy identity key — or the one this sender already holds and has not paid. Limited per sender and per (sender, recipient) pair; a recipient without an identity answers 409 `keyless_recipient`, and one handed too many fresh `@username` addresses in the last day 503 `faircoin_capacity_reached`; paying yourself is refused.",
         auth: 'user',
         params: { username: 'The recipient’s Oxy username.' },
         body: socialNextAddressParams,
@@ -162,6 +217,17 @@ export const socialRoutes = [
         query: socialReceiveCursorQuery,
         response: socialReceiveCursorSchema,
     }),
+    defineRoute({
+        operationId: 'listSocialReceiveAddresses',
+        method: 'get',
+        path: '/v1/social/me/receive_addresses',
+        tag: 'Social payments',
+        summary: "List the caller's receive addresses",
+        description: "Every FairCoin address handed out in the caller's Peable wallet on `network` — payments and `@username` alike, under every key the account has had — after `after`, in ascending index, for whoever the session acts as (an organization's, when acting as it). The wallet watches exactly this set (ADR 0021 D9). Read-only.",
+        auth: 'user',
+        query: socialReceiveAddressesQuery,
+        response: socialReceiveAddressesSchema,
+    }),
     defineRoute({
         operationId: 'listSocialPayments',
         method: 'get',

package/dist/esm/vocabulary/errors.js

@@ -129,8 +129,7 @@ export const ERROR_CODE_DESCRIPTIONS = {
     faircoin_price_unavailable: 'No fresh FairCoin price exists right now, so this order cannot be quoted in FAIR. The other payment methods still work; try FairCoin again shortly.',
     faircoin_wallet_missing: "The Peable wallet that receives this payment (the merchant owner's, or the seller's) isn't set up yet, so it cannot be paid in FairCoin. The other payment methods still work.",
     faircoin_network_closed: 'FairCoin payments on this network are not open on this deployment yet. The other payment methods still work.',
-    faircoin_capacity_reached: 'Too many FairCoin payments to this recipient are waiting to be paid right now, so no new FairCoin address can be handed out. The other payment methods still work; try FairCoin again shortly.',
-    faircoin_receive_tree_full: "Every FairCoin address the recipient's Peable wallet watches has been handed out, so no new one can be derived for them. Nothing was reserved.",
+    faircoin_capacity_reached: 'Too many FairCoin addresses of this recipient were handed out in the last day without being paid, so no new one is handed out right now. Nothing was reserved. The other payment methods still work; try FairCoin again later.',
     faircoin_amount_too_small: "One seller's share of this order is below the smallest amount the FairCoin network relays, so it cannot be paid in FairCoin. The other payment methods still work.",
     credit_note_exceeds_invoice: "The credit note's amount exceeds what the invoice can still credit.",
     test_clock_unexpected_state: 'The test clock is advancing; wait until it is ready.',

package/dist/esm/vocabulary/index.js

@@ -22,4 +22,3 @@ export * from './identity.js';
 export * from './merchants.js';
 export * from './paymentMethodConfigurations.js';
 export * from './realtime.js';
-export * from './receiveTree.js';

package/dist/esm/vocabulary/payments.js

@@ -10,8 +10,8 @@ export const PAYMENT_INTENT_RAILS = ['faircoin', 'card'];
 /**
  * The longest a PaymentIntent created through the API may stay payable before
  * it expires (`expires_in_seconds`): 24 hours. A FairCoin payment holds a
- * reserved address in the recipient's wallet for as long as it is payable, so
- * an unbounded expiry is an address nobody can ever recycle (ADR 0021 D9).
+ * reserved address in the recipient's wallet for as long as it is payable, and
+ * the recipient's bound on unpaid addresses looks back over a day (ADR 0021 D9).
  */
 export const PAYMENT_INTENT_MAX_EXPIRES_IN_SECONDS = 24 * 60 * 60;
 /**
@@ -197,6 +197,12 @@ export const SOCIAL_PAYMENT_DIRECTIONS = ['sent', 'received'];
 export const ENRICHMENT_KINDS = ['merchant', 'user', 'unknown'];
 /** How many addresses one `POST /v1/enrich` resolves (and one social history lists). */
 export const ENRICH_MAX_ADDRESSES = 50;
+/**
+ * One page of `GET /v1/social/me/receive_addresses` (ADR 0021 D9, amended
+ * 2026-11-06): the default and the most a wallet may ask for at once.
+ */
+export const SOCIAL_RECEIVE_ADDRESSES_PAGE_DEFAULT = 500;
+export const SOCIAL_RECEIVE_ADDRESSES_PAGE_MAX = 1000;
 // ---------------------------------------------------------------------------
 // Test helpers
 // ---------------------------------------------------------------------------

package/dist/types/resources/payments/index.d.ts

@@ -3712,7 +3712,7 @@ export declare const paymentsRoutes: readonly [{
     readonly path: "/v1/social/{username}/next_address";
     readonly tag: "Social payments";
     readonly summary: "Reserve an address to pay a person";
-    readonly description: "A fresh address of the recipient's, derived from their Oxy identity key. Limited per (sender, recipient) pair; a recipient without an identity answers 409 `keyless_recipient`, and one whose wallet watches no further address (every index below its watched bound is taken) 503 `faircoin_receive_tree_full`; paying yourself is refused.";
+    readonly description: "A fresh address of the recipient's, derived from their Oxy identity key — or the one this sender already holds and has not paid. Limited per sender and per (sender, recipient) pair; a recipient without an identity answers 409 `keyless_recipient`, and one handed too many fresh `@username` addresses in the last day 503 `faircoin_capacity_reached`; paying yourself is refused.";
     readonly auth: "user";
     readonly params: {
         readonly username: "The recipient’s Oxy username.";
@@ -3750,6 +3750,36 @@ export declare const paymentsRoutes: readonly [{
         identity_public_key: import("zod").ZodNullable<import("zod").ZodString>;
         account_identity_public_key: import("zod").ZodNullable<import("zod").ZodString>;
     }, import("zod/v4/core").$strict>;
+}, {
+    readonly operationId: "listSocialReceiveAddresses";
+    readonly method: "get";
+    readonly path: "/v1/social/me/receive_addresses";
+    readonly tag: "Social payments";
+    readonly summary: "List the caller's receive addresses";
+    readonly description: "Every FairCoin address handed out in the caller's Peable wallet on `network` — payments and `@username` alike, under every key the account has had — after `after`, in ascending index, for whoever the session acts as (an organization's, when acting as it). The wallet watches exactly this set (ADR 0021 D9). Read-only.";
+    readonly auth: "user";
+    readonly query: import("zod").ZodObject<{
+        network: import("zod").ZodEnum<{
+            mainnet: "mainnet";
+            testnet: "testnet";
+        }>;
+        after: import("zod").ZodOptional<import("zod").ZodPipe<import("zod").ZodPipe<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString]>, import("zod").ZodTransform<number, string | number>>, import("zod").ZodNumber>>;
+        limit: import("zod").ZodOptional<import("zod").ZodPipe<import("zod").ZodPipe<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString]>, import("zod").ZodTransform<number, string | number>>, import("zod").ZodNumber>>;
+    }, import("zod/v4/core").$strict>;
+    readonly response: import("zod").ZodObject<{
+        addresses: import("zod").ZodArray<import("zod").ZodObject<{
+            address: import("zod").ZodString;
+            derivation_index: import("zod").ZodNumber;
+            identity_public_key: import("zod").ZodNullable<import("zod").ZodString>;
+            network: import("zod").ZodEnum<{
+                mainnet: "mainnet";
+                testnet: "testnet";
+            }>;
+            created: import("zod").ZodNumber;
+        }, import("zod/v4/core").$strict>>;
+        has_more: import("zod").ZodBoolean;
+        sync_cursor: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strict>;
 }, {
     readonly operationId: "listSocialPayments";
     readonly method: "get";

package/dist/types/resources/payments/social.d.ts

@@ -68,10 +68,10 @@ export declare const socialReceiveCursorQuery: z.ZodObject<{
 }, z.core.$strip>;
 export type SocialReceiveCursorParams = z.input<typeof socialReceiveCursorQuery>;
 /**
- * Lets the caller's device resync its watch window: every `next_address`
- * advances a monotonic index whether or not it is ever paid, so a burst of
- * reservations can outrun a device that widens only on payment. Watch
- * `0..reserved_through + gap`.
+ * The caller's cursor and keys. The addresses to watch are
+ * `GET /v1/social/me/receive_addresses` (ADR 0021 D9, amended 2026-11-06);
+ * `reserved_through` only says how far the cursor went, and the device
+ * compares its key with `account_identity_public_key`.
  */
 export declare const socialReceiveCursorSchema: z.ZodObject<{
     reserved_through: z.ZodNumber;
@@ -79,6 +79,53 @@ export declare const socialReceiveCursorSchema: z.ZodObject<{
     account_identity_public_key: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
 export type SocialReceiveCursorResponse = z.output<typeof socialReceiveCursorSchema>;
+/**
+ * The caller's receive addresses after a sync cursor (ADR 0021 D9, amended
+ * 2026-11-06). `after` is the `sync_cursor` of the previous answer, `0` (the
+ * default) from the start.
+ */
+export declare const socialReceiveAddressesQuery: z.ZodObject<{
+    network: z.ZodEnum<{
+        mainnet: "mainnet";
+        testnet: "testnet";
+    }>;
+    after: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+    limit: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+}, z.core.$strict>;
+export type SocialReceiveAddressesParams = z.input<typeof socialReceiveAddressesQuery>;
+/**
+ * One FairCoin address the gateway handed out in the caller's Peable wallet —
+ * for a payment (merchant, seller, invoice, raw intent, one output of a split
+ * payment) or an `@username` request — under ANY key the account has had.
+ * Addresses are never reused: each is a fresh index of the account's one
+ * cursor (ADR 0002, ADR 0021 D5, D9).
+ */
+export declare const socialReceiveAddressSchema: z.ZodObject<{
+    address: z.ZodString;
+    derivation_index: z.ZodNumber;
+    identity_public_key: z.ZodNullable<z.ZodString>;
+    network: z.ZodEnum<{
+        mainnet: "mainnet";
+        testnet: "testnet";
+    }>;
+    created: z.ZodNumber;
+}, z.core.$strict>;
+export type SocialReceiveAddress = z.output<typeof socialReceiveAddressSchema>;
+export declare const socialReceiveAddressesSchema: z.ZodObject<{
+    addresses: z.ZodArray<z.ZodObject<{
+        address: z.ZodString;
+        derivation_index: z.ZodNumber;
+        identity_public_key: z.ZodNullable<z.ZodString>;
+        network: z.ZodEnum<{
+            mainnet: "mainnet";
+            testnet: "testnet";
+        }>;
+        created: z.ZodNumber;
+    }, z.core.$strict>>;
+    has_more: z.ZodBoolean;
+    sync_cursor: z.ZodNumber;
+}, z.core.$strict>;
+export type SocialReceiveAddressesResponse = z.output<typeof socialReceiveAddressesSchema>;
 export declare const socialPaymentsQuery: z.ZodObject<{
     network: z.ZodEnum<{
         mainnet: "mainnet";
@@ -166,7 +213,7 @@ export declare const socialRoutes: readonly [{
     readonly path: "/v1/social/{username}/next_address";
     readonly tag: "Social payments";
     readonly summary: "Reserve an address to pay a person";
-    readonly description: "A fresh address of the recipient's, derived from their Oxy identity key. Limited per (sender, recipient) pair; a recipient without an identity answers 409 `keyless_recipient`, and one whose wallet watches no further address (every index below its watched bound is taken) 503 `faircoin_receive_tree_full`; paying yourself is refused.";
+    readonly description: "A fresh address of the recipient's, derived from their Oxy identity key — or the one this sender already holds and has not paid. Limited per sender and per (sender, recipient) pair; a recipient without an identity answers 409 `keyless_recipient`, and one handed too many fresh `@username` addresses in the last day 503 `faircoin_capacity_reached`; paying yourself is refused.";
     readonly auth: "user";
     readonly params: {
         readonly username: "The recipient’s Oxy username.";
@@ -204,6 +251,36 @@ export declare const socialRoutes: readonly [{
         identity_public_key: z.ZodNullable<z.ZodString>;
         account_identity_public_key: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>;
+}, {
+    readonly operationId: "listSocialReceiveAddresses";
+    readonly method: "get";
+    readonly path: "/v1/social/me/receive_addresses";
+    readonly tag: "Social payments";
+    readonly summary: "List the caller's receive addresses";
+    readonly description: "Every FairCoin address handed out in the caller's Peable wallet on `network` — payments and `@username` alike, under every key the account has had — after `after`, in ascending index, for whoever the session acts as (an organization's, when acting as it). The wallet watches exactly this set (ADR 0021 D9). Read-only.";
+    readonly auth: "user";
+    readonly query: z.ZodObject<{
+        network: z.ZodEnum<{
+            mainnet: "mainnet";
+            testnet: "testnet";
+        }>;
+        after: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+        limit: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+    }, z.core.$strict>;
+    readonly response: z.ZodObject<{
+        addresses: z.ZodArray<z.ZodObject<{
+            address: z.ZodString;
+            derivation_index: z.ZodNumber;
+            identity_public_key: z.ZodNullable<z.ZodString>;
+            network: z.ZodEnum<{
+                mainnet: "mainnet";
+                testnet: "testnet";
+            }>;
+            created: z.ZodNumber;
+        }, z.core.$strict>>;
+        has_more: z.ZodBoolean;
+        sync_cursor: z.ZodNumber;
+    }, z.core.$strict>;
 }, {
     readonly operationId: "listSocialPayments";
     readonly method: "get";

package/dist/types/vocabulary/errors.d.ts

@@ -108,8 +108,7 @@ export declare const ERROR_CODE_DESCRIPTIONS: {
     readonly faircoin_price_unavailable: "No fresh FairCoin price exists right now, so this order cannot be quoted in FAIR. The other payment methods still work; try FairCoin again shortly.";
     readonly faircoin_wallet_missing: "The Peable wallet that receives this payment (the merchant owner's, or the seller's) isn't set up yet, so it cannot be paid in FairCoin. The other payment methods still work.";
     readonly faircoin_network_closed: "FairCoin payments on this network are not open on this deployment yet. The other payment methods still work.";
-    readonly faircoin_capacity_reached: "Too many FairCoin payments to this recipient are waiting to be paid right now, so no new FairCoin address can be handed out. The other payment methods still work; try FairCoin again shortly.";
-    readonly faircoin_receive_tree_full: "Every FairCoin address the recipient's Peable wallet watches has been handed out, so no new one can be derived for them. Nothing was reserved.";
+    readonly faircoin_capacity_reached: "Too many FairCoin addresses of this recipient were handed out in the last day without being paid, so no new one is handed out right now. Nothing was reserved. The other payment methods still work; try FairCoin again later.";
     readonly faircoin_amount_too_small: "One seller's share of this order is below the smallest amount the FairCoin network relays, so it cannot be paid in FairCoin. The other payment methods still work.";
     readonly credit_note_exceeds_invoice: "The credit note's amount exceeds what the invoice can still credit.";
     readonly test_clock_unexpected_state: "The test clock is advancing; wait until it is ready.";

package/dist/types/vocabulary/index.d.ts

@@ -18,4 +18,3 @@ export * from './identity';
 export * from './merchants';
 export * from './paymentMethodConfigurations';
 export * from './realtime';
-export * from './receiveTree';

package/dist/types/vocabulary/payments.d.ts

@@ -7,8 +7,8 @@ export type PaymentIntentRail = (typeof PAYMENT_INTENT_RAILS)[number];
 /**
  * The longest a PaymentIntent created through the API may stay payable before
  * it expires (`expires_in_seconds`): 24 hours. A FairCoin payment holds a
- * reserved address in the recipient's wallet for as long as it is payable, so
- * an unbounded expiry is an address nobody can ever recycle (ADR 0021 D9).
+ * reserved address in the recipient's wallet for as long as it is payable, and
+ * the recipient's bound on unpaid addresses looks back over a day (ADR 0021 D9).
  */
 export declare const PAYMENT_INTENT_MAX_EXPIRES_IN_SECONDS: number;
 /**
@@ -122,6 +122,12 @@ export declare const ENRICHMENT_KINDS: readonly ["merchant", "user", "unknown"];
 export type EnrichmentKind = (typeof ENRICHMENT_KINDS)[number];
 /** How many addresses one `POST /v1/enrich` resolves (and one social history lists). */
 export declare const ENRICH_MAX_ADDRESSES = 50;
+/**
+ * One page of `GET /v1/social/me/receive_addresses` (ADR 0021 D9, amended
+ * 2026-11-06): the default and the most a wallet may ask for at once.
+ */
+export declare const SOCIAL_RECEIVE_ADDRESSES_PAGE_DEFAULT = 500;
+export declare const SOCIAL_RECEIVE_ADDRESSES_PAGE_MAX = 1000;
 /**
  * What `simulate_faircoin_payment` pretends the payer did: `settled` paid the
  * full amount (`processing` → `succeeded`); `underpaid` sent less

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/contracts",
-  "version": "5.6.0",
+  "version": "6.0.0",
   "description": "The Peable wire, declared once: Zod contracts of every public route, the OpenAPI 3.1 generator and the closed value sets (ADR 0014 D5).",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/dist/cjs/vocabulary/receiveTree.js

@@ -1,44 +0,0 @@
-"use strict";
-/**
- * The size of a recipient's FairCoin receive tree (ADR 0021 D9, amended
- * 2026-11-06) — ONE answer, read by the gateway that hands out indices and by
- * the Peable wallet that watches them.
- *
- * Every FairCoin address the gateway reserves for an account — a merchant
- * payment, a marketplace seller's, an invoice's, `@username` — is index `i` of
- * that account's identity tree (ADR 0002, ADR 0021 D5). The wallet watches a
- * contiguous window, indices `0 .. SOCIAL_RECEIVE_MAX_WATCHED - 1`, reaching
- * {@link SOCIAL_RECEIVE_GAP_LIMIT} past the highest index reserved
- * (`planSocialReceiveWindow` in `packages/frontend/src/wallet/social-receive.ts`),
- * and stops offering `@username` once that reach would pass its bound. So an
- * index is reserved only when the wallet, after reserving it, still reaches
- * the gap above it inside its bound:
- *
- *     index + SOCIAL_RECEIVE_GAP_LIMIT  <=  SOCIAL_RECEIVE_MAX_WATCHED - 1
- *     index                             <   SOCIAL_RECEIVE_INDEX_LIMIT
- *
- * The gateway refuses to mint `index >= SOCIAL_RECEIVE_INDEX_LIMIT` (in the
- * reservation's own statement), so every address it hands out is inside the
- * window the wallet watches. Zod-free and dependency-free: the wallet bundles
- * this module alone (`@peable.to/contracts/vocabulary/receiveTree`).
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SOCIAL_RECEIVE_NEARLY_FULL_REMAINING = exports.SOCIAL_RECEIVE_INDEX_LIMIT = exports.SOCIAL_RECEIVE_GAP_LIMIT = exports.SOCIAL_RECEIVE_MAX_WATCHED = void 0;
-/** The most indices the wallet watches: `0 .. SOCIAL_RECEIVE_MAX_WATCHED - 1`. */
-exports.SOCIAL_RECEIVE_MAX_WATCHED = 2000;
-/**
- * How many unused addresses the wallet watches beyond the highest index used
- * or reserved — the FairCoin BIP44 external-chain gap limit.
- */
-exports.SOCIAL_RECEIVE_GAP_LIMIT = 20;
-/**
- * The first index the gateway never mints (exclusive bound): `1 980`. Every
- * minted index `i` satisfies `i < SOCIAL_RECEIVE_INDEX_LIMIT`, i.e.
- * `i + SOCIAL_RECEIVE_GAP_LIMIT <= SOCIAL_RECEIVE_MAX_WATCHED - 1`.
- */
-exports.SOCIAL_RECEIVE_INDEX_LIMIT = exports.SOCIAL_RECEIVE_MAX_WATCHED - exports.SOCIAL_RECEIVE_GAP_LIMIT;
-/**
- * How close to {@link SOCIAL_RECEIVE_INDEX_LIMIT} a tree is "nearly full":
- * Orbit warns the owners once fewer fresh indices than this are left.
- */
-exports.SOCIAL_RECEIVE_NEARLY_FULL_REMAINING = 200;

package/dist/esm/vocabulary/receiveTree.js

@@ -1,41 +0,0 @@
-/**
- * The size of a recipient's FairCoin receive tree (ADR 0021 D9, amended
- * 2026-11-06) — ONE answer, read by the gateway that hands out indices and by
- * the Peable wallet that watches them.
- *
- * Every FairCoin address the gateway reserves for an account — a merchant
- * payment, a marketplace seller's, an invoice's, `@username` — is index `i` of
- * that account's identity tree (ADR 0002, ADR 0021 D5). The wallet watches a
- * contiguous window, indices `0 .. SOCIAL_RECEIVE_MAX_WATCHED - 1`, reaching
- * {@link SOCIAL_RECEIVE_GAP_LIMIT} past the highest index reserved
- * (`planSocialReceiveWindow` in `packages/frontend/src/wallet/social-receive.ts`),
- * and stops offering `@username` once that reach would pass its bound. So an
- * index is reserved only when the wallet, after reserving it, still reaches
- * the gap above it inside its bound:
- *
- *     index + SOCIAL_RECEIVE_GAP_LIMIT  <=  SOCIAL_RECEIVE_MAX_WATCHED - 1
- *     index                             <   SOCIAL_RECEIVE_INDEX_LIMIT
- *
- * The gateway refuses to mint `index >= SOCIAL_RECEIVE_INDEX_LIMIT` (in the
- * reservation's own statement), so every address it hands out is inside the
- * window the wallet watches. Zod-free and dependency-free: the wallet bundles
- * this module alone (`@peable.to/contracts/vocabulary/receiveTree`).
- */
-/** The most indices the wallet watches: `0 .. SOCIAL_RECEIVE_MAX_WATCHED - 1`. */
-export const SOCIAL_RECEIVE_MAX_WATCHED = 2000;
-/**
- * How many unused addresses the wallet watches beyond the highest index used
- * or reserved — the FairCoin BIP44 external-chain gap limit.
- */
-export const SOCIAL_RECEIVE_GAP_LIMIT = 20;
-/**
- * The first index the gateway never mints (exclusive bound): `1 980`. Every
- * minted index `i` satisfies `i < SOCIAL_RECEIVE_INDEX_LIMIT`, i.e.
- * `i + SOCIAL_RECEIVE_GAP_LIMIT <= SOCIAL_RECEIVE_MAX_WATCHED - 1`.
- */
-export const SOCIAL_RECEIVE_INDEX_LIMIT = SOCIAL_RECEIVE_MAX_WATCHED - SOCIAL_RECEIVE_GAP_LIMIT;
-/**
- * How close to {@link SOCIAL_RECEIVE_INDEX_LIMIT} a tree is "nearly full":
- * Orbit warns the owners once fewer fresh indices than this are left.
- */
-export const SOCIAL_RECEIVE_NEARLY_FULL_REMAINING = 200;

package/dist/types/vocabulary/receiveTree.d.ts

@@ -1,41 +0,0 @@
-/**
- * The size of a recipient's FairCoin receive tree (ADR 0021 D9, amended
- * 2026-11-06) — ONE answer, read by the gateway that hands out indices and by
- * the Peable wallet that watches them.
- *
- * Every FairCoin address the gateway reserves for an account — a merchant
- * payment, a marketplace seller's, an invoice's, `@username` — is index `i` of
- * that account's identity tree (ADR 0002, ADR 0021 D5). The wallet watches a
- * contiguous window, indices `0 .. SOCIAL_RECEIVE_MAX_WATCHED - 1`, reaching
- * {@link SOCIAL_RECEIVE_GAP_LIMIT} past the highest index reserved
- * (`planSocialReceiveWindow` in `packages/frontend/src/wallet/social-receive.ts`),
- * and stops offering `@username` once that reach would pass its bound. So an
- * index is reserved only when the wallet, after reserving it, still reaches
- * the gap above it inside its bound:
- *
- *     index + SOCIAL_RECEIVE_GAP_LIMIT  <=  SOCIAL_RECEIVE_MAX_WATCHED - 1
- *     index                             <   SOCIAL_RECEIVE_INDEX_LIMIT
- *
- * The gateway refuses to mint `index >= SOCIAL_RECEIVE_INDEX_LIMIT` (in the
- * reservation's own statement), so every address it hands out is inside the
- * window the wallet watches. Zod-free and dependency-free: the wallet bundles
- * this module alone (`@peable.to/contracts/vocabulary/receiveTree`).
- */
-/** The most indices the wallet watches: `0 .. SOCIAL_RECEIVE_MAX_WATCHED - 1`. */
-export declare const SOCIAL_RECEIVE_MAX_WATCHED = 2000;
-/**
- * How many unused addresses the wallet watches beyond the highest index used
- * or reserved — the FairCoin BIP44 external-chain gap limit.
- */
-export declare const SOCIAL_RECEIVE_GAP_LIMIT = 20;
-/**
- * The first index the gateway never mints (exclusive bound): `1 980`. Every
- * minted index `i` satisfies `i < SOCIAL_RECEIVE_INDEX_LIMIT`, i.e.
- * `i + SOCIAL_RECEIVE_GAP_LIMIT <= SOCIAL_RECEIVE_MAX_WATCHED - 1`.
- */
-export declare const SOCIAL_RECEIVE_INDEX_LIMIT: number;
-/**
- * How close to {@link SOCIAL_RECEIVE_INDEX_LIMIT} a tree is "nearly full":
- * Orbit warns the owners once fewer fresh indices than this are left.
- */
-export declare const SOCIAL_RECEIVE_NEARLY_FULL_REMAINING = 200;