Stipendex

Конверт: Quote / Proof / Receipt

Три объекта, описывающие один платёж. Общие правила: JWS (Ed25519), суммы — десятичные строки, stipendex: "<type>/0.1". Mandate и Confirmation — в mandate-wallet.md.

Quote — котировка получателя

Одноразовое предложение «заплати X — получишь Y». Издаёт получатель в ответ на вызов без оплаты (см. transports.md).

{
  "stipendex": "quote/0.1",
  "quote_id": "q_8f3d1c…",
  "receiver": {
    "id": "mcp:exa-search",
    "key": "ed25519:GfHq…",
    "registry": "https://registry.4agents.io/receivers/exa-search"
  },
  "amount": { "value": "0.0042", "currency": "USD" },
  "description": "web_search: ~3k tokens",
  "rails": [
    { "scheme": "account", "facilitator": "https://pay.4agents.io" },
    { "scheme": "x402", "network": "base", "asset": "USDC", "to": "0x9a…" }
  ],
  "session": { "id": "s_42", "mode": "tab", "cap": "5.00" },
  "expires_at": "2026-07-16T12:05:00Z",
  "sig": "<jws получателя>"
}
Поле Обяз. Правила
quote_id да одноразовый; повторное предъявление MUST быть отклонено
receiver.id да стабильный идентификатор (mcp:<slug> или URL)
receiver.key да ключ подписи; MUST совпадать с ключом в дескрипторе реестра, если получатель верифицирован
receiver.registry нет ссылка на дескриптор в реестре доверия
amount или estimate да (ровно одно) amount — фиксированная цена (service); estimate — оценка с допуском (checkout/metered), см. ниже
description да человекочитаемо: показывается принципалу при HITL
rails[] да допустимые схемы расчёта, поля схемы — в rails.md
session нет предложение tab-агрегации, см. ниже
expires_at да SHOULD: минуты для service, 10–15 минут для checkout

estimate + tolerance (суммы, неизвестные заранее)

Для metered-инструментов и товарного checkout финальная сумма известна только после исполнения (токены, доставка, налог, дрейф цены фида):

"estimate": {
  "value": "84.00",
  "currency": "USD",
  "tolerance": { "value": "8.40" }
}

Семантика: кошелёк авторизует (холдирует) estimate + tolerance; списать можно только подтверждённую финальную сумму ≤ estimate + tolerance (инвариант I3). Превышение допуска — не «пересписание», а новый цикл: re-quote и повторное подтверждение. Механика заимствована из 4agents order-flow v2.1 («ACCEPT — источник истины по сумме»).

session — сессия-tab (агрегация микроплатежей)

Per-call расчёт для микросумм дорог и не нужен. Получатель MAY предложить tab:

Proof — доказательство оплаты

Издаёт кошелёк после успешного расчёта (или холда) по выбранному рельсу.

{
  "stipendex": "proof/0.1",
  "proof_id": "p_c81a…",
  "quote_id": "q_8f3d1c…",
  "mode": "capture",
  "scheme": "account",
  "evidence": "<rail-specific: JWS фасилитатора | tx-hash | payment_intent id>",
  "mandate_ref": "sha256:9e1b…",
  "confirmation_id": null,
  "payer_key": "ed25519:BBBB…",
  "sig": "<jws кошелька>"
}
Поле Правила
mode capture (списано, service) или hold (захолдировано, checkout)
evidence проверяемое рельсом доказательство; формат — per-scheme (rails.md)
mandate_ref hash мандата, не сам мандат — лимиты и allowlist принципала получателю не раскрываются (приватность); полная цепочка доступна принципалу и, по запросу спора, фасилитатору
confirmation_id ссылка на Confirmation, если был HITL (checkout — обязателен)

Идемпотентность: получатель, увидевший знакомый proof_id, MUST вернуть прежний результат/Receipt без повторного исполнения и списания.

Receipt — расписка получателя

Издаёт получатель после исполнения. Закрывает цикл и служит доказательством в аудите и спорах.

{
  "stipendex": "receipt/0.1",
  "receipt_id": "r_11ac…",
  "quote_id": "q_8f3d1c…",
  "proof_id": "p_c81a…",
  "status": "settled",
  "amount_final": { "value": "0.0042", "currency": "USD" },
  "result_hash": "sha256:44fe…",
  "issued_at": "2026-07-16T12:04:31Z",
  "sig": "<jws получателя>"
}
status Смысл
settled списано и исполнено (service happy path)
held захолдировано, исполнение ожидает подтверждения (checkout до ACCEPT)
captured финальная сумма списана после подтверждения (checkout после ACCEPT)
voided холд отменён без списания (DECLINE / таймаут / выход за допуск)
refunded возврат (расширение; сам возврат исполняет рельс)

result_hash — hash результата вызова (service) или идентификатор заказа (checkout). Связка proof → receipt(result_hash) — доказательство «оплатил и получил/не получил».

Сводка идемпотентности и повторов