@fun-xyz/fiat-contract 0.36.0-uda.2 → 0.36.0-uda.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
  // package.json
2
- var version = "0.36.0-uda.2";
2
+ var version = "0.36.0-uda.4";
3
3
 
4
4
  // src/table.ts
5
5
  var TABLE_VERSION = version;
@@ -359,9 +359,16 @@ var TRANSITION_TABLE = {
359
359
  id: "poll",
360
360
  mode: "AWAIT",
361
361
  endpoint: "GET /fiat/orders/:id",
362
- when: "status is non-terminal, or delivery.state is SWAPPING",
362
+ when: "status is non-terminal",
363
363
  note: "Documented giveUpAfterMs 300000 \u2014 on give-up the wizard exits and the durable order takes over."
364
364
  },
365
+ {
366
+ id: "delivery",
367
+ mode: "AWAIT",
368
+ endpoint: "GET /fiat/orders/:id/delivery",
369
+ when: "status is SETTLED and the order is converted: the provider paid a deposit address that converts into the destination",
370
+ note: "The backend decides; the client never infers a converted order. It follows this transition when offered, and otherwise treats SETTLED as done."
371
+ },
365
372
  {
366
373
  id: "retry_payment",
367
374
  mode: "SUBMIT",
@@ -382,7 +389,7 @@ var TRANSITION_TABLE = {
382
389
  note: "TODO(open-decision): cancel placement (FE doc open questions 1+2); per-rail eligibility is contract OQ7."
383
390
  }
384
391
  ],
385
- mayReturn: ["ORDER/CREATED"],
392
+ mayReturn: ["ORDER/CREATED", "DELIVERY:PENDING", "DELIVERY:SUCCEEDED", "DELIVERY:FAILED"],
386
393
  terminal: false,
387
394
  terminalStatuses: TERMINAL_ORDER_STATUSES,
388
395
  notes: [
@@ -390,9 +397,53 @@ var TRANSITION_TABLE = {
390
397
  "A terminal status may still carry a recovery transition: FAILED + retryable failureReason emits it (FE doc Screen 14); non-retryable emits [].",
391
398
  "ON_HOLD is a non-terminal status (resolves to PROCESSING or REFUNDED) \u2014 and is NOT the same thing as the KYC ON_HOLD reason; see the note on that field.",
392
399
  "CAPTURE_ORPHANED is non-terminal pending the backend rank map (added from review 2026-08-14).",
393
- "SETTLED is terminal for the order. When delivery.mode is CONVERTED, the conversion into the destination may still run after SETTLED: the backend keeps offering the AWAIT poll while delivery.state is SWAPPING, and the client keeps polling until delivery.state is DELIVERED or FAILED.",
400
+ "SETTLED is terminal for the order and ends a direct purchase. On a converted order it carries the delivery transition, and the purchase continues in DELIVERY (GET /fiat/orders/:id/delivery). The order body itself never describes the conversion.",
394
401
  "TODO(open-decision): contract OQ7 \u2014 under/over-payment is the biggest unenumerated branch."
395
402
  ]
403
+ },
404
+ "DELIVERY:PENDING": {
405
+ key: "DELIVERY:PENDING",
406
+ kind: "DELIVERY",
407
+ state: "PENDING",
408
+ screens: [7],
409
+ docStatus: "SPECIFIED",
410
+ allowedTransitions: [
411
+ {
412
+ id: "poll",
413
+ mode: "AWAIT",
414
+ endpoint: "GET /fiat/orders/:id/delivery",
415
+ note: "Giving up the poll does not fail the purchase: the backend still finishes the delivery or raises it to support."
416
+ }
417
+ ],
418
+ mayReturn: ["DELIVERY:PENDING", "DELIVERY:SUCCEEDED", "DELIVERY:FAILED"],
419
+ terminal: false,
420
+ notes: [
421
+ "The fiat leg is SETTLED; a crypto asset provider is converting it into the destination and paying the user. The client shows a generic processing screen."
422
+ ]
423
+ },
424
+ "DELIVERY:SUCCEEDED": {
425
+ key: "DELIVERY:SUCCEEDED",
426
+ kind: "DELIVERY",
427
+ state: "SUCCEEDED",
428
+ screens: [13],
429
+ docStatus: "SPECIFIED",
430
+ allowedTransitions: [],
431
+ mayReturn: [],
432
+ terminal: true,
433
+ notes: ["The destination asset reached the user. txHash is the transaction that paid them."]
434
+ },
435
+ "DELIVERY:FAILED": {
436
+ key: "DELIVERY:FAILED",
437
+ kind: "DELIVERY",
438
+ state: "FAILED",
439
+ screens: [],
440
+ docStatus: "SPECIFIED",
441
+ allowedTransitions: [],
442
+ mayReturn: [],
443
+ terminal: true,
444
+ notes: [
445
+ "The buyer has paid and the asset did not arrive. Support recovers the funds, so the client shows a dedicated failure screen that offers no new payment."
446
+ ]
396
447
  }
397
448
  };
398
449
  var STATE_KEYS = Object.keys(TRANSITION_TABLE);
@@ -411,6 +462,7 @@ var DOCUMENTED_ENDPOINTS = [
411
462
  "POST /fiat/instruments",
412
463
  "POST /fiat/orders",
413
464
  "GET /fiat/orders/:id",
465
+ "GET /fiat/orders/:id/delivery",
414
466
  "GET /fiat/orders/:id/instructions",
415
467
  "POST /fiat/orders/:id/confirm-payment",
416
468
  "POST /fiat/orders/:id/reference",
@@ -486,6 +538,8 @@ function stateKey(state) {
486
538
  return state.phase === "CAPTURE" ? "PAYMENT/CAPTURE" : "PAYMENT/INSTRUCT";
487
539
  case "ORDER":
488
540
  return state.phase === "AWAITING_CONFIRMATION" ? "ORDER/AWAITING_CONFIRMATION" : "ORDER/CREATED";
541
+ case "DELIVERY":
542
+ return `DELIVERY:${state.state}`;
489
543
  default: {
490
544
  const exhaustive = state;
491
545
  throw new Error(`unknown FlowState: ${JSON.stringify(exhaustive)}`);
package/dist/index.js CHANGED
@@ -30,6 +30,7 @@ __export(index_exports, {
30
30
  CountryCode: () => CountryCode,
31
31
  CryptoAmountSchema: () => CryptoAmountSchema,
32
32
  DOCUMENTED_ENDPOINTS: () => DOCUMENTED_ENDPOINTS,
33
+ DeliveryStateSchema: () => DeliveryStateSchema,
33
34
  ENDPOINT_PATTERN: () => ENDPOINT_PATTERN,
34
35
  FIAT_CURRENCY_NAMES: () => FIAT_CURRENCY_NAMES,
35
36
  FIAT_TERMS_ENDPOINT: () => FIAT_TERMS_ENDPOINT,
@@ -45,8 +46,6 @@ __export(index_exports, {
45
46
  FiatEndpointSchema: () => FiatEndpointSchema,
46
47
  FiatGeoSchema: () => FiatGeoSchema,
47
48
  FiatNextRequestSchema: () => FiatNextRequestSchema,
48
- FiatOrderDeliverySchema: () => FiatOrderDeliverySchema,
49
- FiatOrderDeliveryStateSchema: () => FiatOrderDeliveryStateSchema,
50
49
  FiatProviderSchema: () => FiatProviderSchema,
51
50
  FiatRoutingQuoteErrorBodySchema: () => FiatRoutingQuoteErrorBodySchema,
52
51
  FiatRoutingQuoteRequestSchema: () => FiatRoutingQuoteRequestSchema,
@@ -626,13 +625,6 @@ var $statusHistoryEntry = obj({ status: $orderStatus });
626
625
  var StatusHistoryEntrySchema = $statusHistoryEntry;
627
626
  var $tx = obj({ chainId: import_zod.z.number(), hash: import_zod.z.string() });
628
627
  var TxSchema = $tx;
629
- var $orderDeliveryState = import_zod.z.enum(["SWAPPING", "DELIVERED", "FAILED"]);
630
- var FiatOrderDeliveryStateSchema = $orderDeliveryState;
631
- var $orderDelivery = import_zod.z.discriminatedUnion("mode", [
632
- obj({ mode: import_zod.z.literal("DIRECT") }),
633
- obj({ mode: import_zod.z.literal("CONVERTED"), state: $orderDeliveryState, finalTxHash: import_zod.z.string().min(1).nullable() })
634
- ]);
635
- var FiatOrderDeliverySchema = $orderDelivery;
636
628
  var $refund = obj({
637
629
  currency: import_zod.z.enum(FIAT_CURRENCY_CODES),
638
630
  amount: import_zod.z.string(),
@@ -1009,12 +1001,17 @@ var $orderCreatedState = obj({
1009
1001
  status: $orderStatus,
1010
1002
  statusHistory: import_zod.z.array($statusHistoryEntry).optional(),
1011
1003
  tx: $tx.optional(),
1012
- delivery: $orderDelivery.optional(),
1013
1004
  refund: $refund.optional(),
1014
1005
  failureReason: $failureReason.optional(),
1015
1006
  error: $failureReason.optional()
1016
1007
  });
1017
1008
  var OrderCreatedStateSchema = $orderCreatedState;
1009
+ var $deliveryState = import_zod.z.discriminatedUnion("state", [
1010
+ obj({ kind: import_zod.z.literal("DELIVERY"), state: import_zod.z.literal("PENDING") }),
1011
+ obj({ kind: import_zod.z.literal("DELIVERY"), state: import_zod.z.literal("SUCCEEDED"), txHash: import_zod.z.string().min(1) }),
1012
+ obj({ kind: import_zod.z.literal("DELIVERY"), state: import_zod.z.literal("FAILED") })
1013
+ ]);
1014
+ var DeliveryStateSchema = $deliveryState;
1018
1015
  var $providerBoundFlowState = import_zod.z.union([
1019
1016
  $quoteState,
1020
1017
  $funAuthState,
@@ -1026,7 +1023,8 @@ var $providerBoundFlowState = import_zod.z.union([
1026
1023
  $paymentCaptureState,
1027
1024
  $paymentInstructState,
1028
1025
  $orderAwaitingConfirmationState,
1029
- $orderCreatedState
1026
+ $orderCreatedState,
1027
+ $deliveryState
1030
1028
  ]);
1031
1029
  var $flowState = import_zod.z.union([$providerBoundFlowState, $blockedState]);
1032
1030
  var FlowStateSchema = $flowState;
@@ -1065,13 +1063,43 @@ var $termsErrorBody = obj({
1065
1063
  recovery: import_zod.z.enum(["RETRY", "REQUOTE", "NONE"])
1066
1064
  });
1067
1065
  var FiatTermsErrorBodySchema = $termsErrorBody;
1068
- var $destination = obj({
1069
- chainId: import_zod.z.string().regex(/^[1-9]\d*$/, "must be a decimal chain id"),
1070
- tokenAddress: import_zod.z.union([
1071
- import_zod.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "must be an EVM address"),
1072
- import_zod.z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/, "must be a Solana base58 address")
1066
+ var $evmAddress = import_zod.z.custom(
1067
+ (value) => typeof value === "string" && /^0x[0-9a-fA-F]{40}$/.test(value),
1068
+ "must be an EVM address: 0x and 40 hex digits"
1069
+ );
1070
+ var $solanaAddress = import_zod.z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/, "must be a Solana base58 address");
1071
+ var $evmDestination = obj({
1072
+ vm: import_zod.z.literal("EVM"),
1073
+ chainId: import_zod.z.number().int().positive(),
1074
+ asset: import_zod.z.discriminatedUnion("kind", [
1075
+ obj({
1076
+ kind: import_zod.z.literal("FUNGIBLE"),
1077
+ token: import_zod.z.discriminatedUnion("type", [
1078
+ obj({ type: import_zod.z.literal("NATIVE") }),
1079
+ obj({ type: import_zod.z.literal("ERC20"), address: $evmAddress })
1080
+ ])
1081
+ }),
1082
+ obj({
1083
+ kind: import_zod.z.literal("NON_FUNGIBLE"),
1084
+ contractAddress: $evmAddress,
1085
+ tokenId: import_zod.z.string().regex(/^(0|[1-9]\d*)$/, "must be a decimal integer")
1086
+ })
1073
1087
  ])
1074
1088
  });
1089
+ var $solanaDestination = obj({
1090
+ vm: import_zod.z.literal("SOLANA"),
1091
+ asset: import_zod.z.discriminatedUnion("kind", [
1092
+ obj({
1093
+ kind: import_zod.z.literal("FUNGIBLE"),
1094
+ token: import_zod.z.discriminatedUnion("type", [
1095
+ obj({ type: import_zod.z.literal("NATIVE") }),
1096
+ obj({ type: import_zod.z.literal("SPL"), mint: $solanaAddress })
1097
+ ])
1098
+ }),
1099
+ obj({ kind: import_zod.z.literal("NON_FUNGIBLE"), mint: $solanaAddress })
1100
+ ])
1101
+ });
1102
+ var $destination = import_zod.z.discriminatedUnion("vm", [$evmDestination, $solanaDestination]);
1075
1103
  var FiatDestinationSchema = $destination;
1076
1104
  var $decimalAmount = import_zod.z.string().regex(/^(?:0|[1-9]\d*)(?:\.\d+)?$/, "must be a decimal string");
1077
1105
  var compareDecimals = (left, right) => {
@@ -1107,9 +1135,7 @@ var $routingTableProvider = obj({
1107
1135
  provider: $routingProvider,
1108
1136
  next: import_zod.z.enum(["READY", "AUTH", "DECLARATIVE_KYC", "DOCUMENTARY_KYC", "PENDING_REVIEW"]),
1109
1137
  visibility: import_zod.z.enum(["COMPLETE", "PARTIAL", "AUTH_GATED"]),
1110
- currentLimit: $decimalAmount.nullable(),
1111
- railAsset: $destination.optional(),
1112
- deliveryMode: import_zod.z.enum(["DIRECT", "CONVERTED"]).optional()
1138
+ currentLimit: $decimalAmount.nullable()
1113
1139
  });
1114
1140
  var $routingTableInterval = obj({
1115
1141
  min: $decimalAmount,
@@ -1265,7 +1291,7 @@ var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStep
1265
1291
  var FiatStepResponseSchema = $stepResponse;
1266
1292
 
1267
1293
  // package.json
1268
- var version = "0.36.0-uda.2";
1294
+ var version = "0.36.0-uda.4";
1269
1295
 
1270
1296
  // src/table.ts
1271
1297
  var TABLE_VERSION = version;
@@ -1625,9 +1651,16 @@ var TRANSITION_TABLE = {
1625
1651
  id: "poll",
1626
1652
  mode: "AWAIT",
1627
1653
  endpoint: "GET /fiat/orders/:id",
1628
- when: "status is non-terminal, or delivery.state is SWAPPING",
1654
+ when: "status is non-terminal",
1629
1655
  note: "Documented giveUpAfterMs 300000 \u2014 on give-up the wizard exits and the durable order takes over."
1630
1656
  },
1657
+ {
1658
+ id: "delivery",
1659
+ mode: "AWAIT",
1660
+ endpoint: "GET /fiat/orders/:id/delivery",
1661
+ when: "status is SETTLED and the order is converted: the provider paid a deposit address that converts into the destination",
1662
+ note: "The backend decides; the client never infers a converted order. It follows this transition when offered, and otherwise treats SETTLED as done."
1663
+ },
1631
1664
  {
1632
1665
  id: "retry_payment",
1633
1666
  mode: "SUBMIT",
@@ -1648,7 +1681,7 @@ var TRANSITION_TABLE = {
1648
1681
  note: "TODO(open-decision): cancel placement (FE doc open questions 1+2); per-rail eligibility is contract OQ7."
1649
1682
  }
1650
1683
  ],
1651
- mayReturn: ["ORDER/CREATED"],
1684
+ mayReturn: ["ORDER/CREATED", "DELIVERY:PENDING", "DELIVERY:SUCCEEDED", "DELIVERY:FAILED"],
1652
1685
  terminal: false,
1653
1686
  terminalStatuses: TERMINAL_ORDER_STATUSES,
1654
1687
  notes: [
@@ -1656,9 +1689,53 @@ var TRANSITION_TABLE = {
1656
1689
  "A terminal status may still carry a recovery transition: FAILED + retryable failureReason emits it (FE doc Screen 14); non-retryable emits [].",
1657
1690
  "ON_HOLD is a non-terminal status (resolves to PROCESSING or REFUNDED) \u2014 and is NOT the same thing as the KYC ON_HOLD reason; see the note on that field.",
1658
1691
  "CAPTURE_ORPHANED is non-terminal pending the backend rank map (added from review 2026-08-14).",
1659
- "SETTLED is terminal for the order. When delivery.mode is CONVERTED, the conversion into the destination may still run after SETTLED: the backend keeps offering the AWAIT poll while delivery.state is SWAPPING, and the client keeps polling until delivery.state is DELIVERED or FAILED.",
1692
+ "SETTLED is terminal for the order and ends a direct purchase. On a converted order it carries the delivery transition, and the purchase continues in DELIVERY (GET /fiat/orders/:id/delivery). The order body itself never describes the conversion.",
1660
1693
  "TODO(open-decision): contract OQ7 \u2014 under/over-payment is the biggest unenumerated branch."
1661
1694
  ]
1695
+ },
1696
+ "DELIVERY:PENDING": {
1697
+ key: "DELIVERY:PENDING",
1698
+ kind: "DELIVERY",
1699
+ state: "PENDING",
1700
+ screens: [7],
1701
+ docStatus: "SPECIFIED",
1702
+ allowedTransitions: [
1703
+ {
1704
+ id: "poll",
1705
+ mode: "AWAIT",
1706
+ endpoint: "GET /fiat/orders/:id/delivery",
1707
+ note: "Giving up the poll does not fail the purchase: the backend still finishes the delivery or raises it to support."
1708
+ }
1709
+ ],
1710
+ mayReturn: ["DELIVERY:PENDING", "DELIVERY:SUCCEEDED", "DELIVERY:FAILED"],
1711
+ terminal: false,
1712
+ notes: [
1713
+ "The fiat leg is SETTLED; a crypto asset provider is converting it into the destination and paying the user. The client shows a generic processing screen."
1714
+ ]
1715
+ },
1716
+ "DELIVERY:SUCCEEDED": {
1717
+ key: "DELIVERY:SUCCEEDED",
1718
+ kind: "DELIVERY",
1719
+ state: "SUCCEEDED",
1720
+ screens: [13],
1721
+ docStatus: "SPECIFIED",
1722
+ allowedTransitions: [],
1723
+ mayReturn: [],
1724
+ terminal: true,
1725
+ notes: ["The destination asset reached the user. txHash is the transaction that paid them."]
1726
+ },
1727
+ "DELIVERY:FAILED": {
1728
+ key: "DELIVERY:FAILED",
1729
+ kind: "DELIVERY",
1730
+ state: "FAILED",
1731
+ screens: [],
1732
+ docStatus: "SPECIFIED",
1733
+ allowedTransitions: [],
1734
+ mayReturn: [],
1735
+ terminal: true,
1736
+ notes: [
1737
+ "The buyer has paid and the asset did not arrive. Support recovers the funds, so the client shows a dedicated failure screen that offers no new payment."
1738
+ ]
1662
1739
  }
1663
1740
  };
1664
1741
  var STATE_KEYS = Object.keys(TRANSITION_TABLE);
@@ -1677,6 +1754,7 @@ var DOCUMENTED_ENDPOINTS = [
1677
1754
  "POST /fiat/instruments",
1678
1755
  "POST /fiat/orders",
1679
1756
  "GET /fiat/orders/:id",
1757
+ "GET /fiat/orders/:id/delivery",
1680
1758
  "GET /fiat/orders/:id/instructions",
1681
1759
  "POST /fiat/orders/:id/confirm-payment",
1682
1760
  "POST /fiat/orders/:id/reference",
@@ -1752,6 +1830,8 @@ function stateKey(state) {
1752
1830
  return state.phase === "CAPTURE" ? "PAYMENT/CAPTURE" : "PAYMENT/INSTRUCT";
1753
1831
  case "ORDER":
1754
1832
  return state.phase === "AWAITING_CONFIRMATION" ? "ORDER/AWAITING_CONFIRMATION" : "ORDER/CREATED";
1833
+ case "DELIVERY":
1834
+ return `DELIVERY:${state.state}`;
1755
1835
  default: {
1756
1836
  const exhaustive = state;
1757
1837
  throw new Error(`unknown FlowState: ${JSON.stringify(exhaustive)}`);
@@ -1769,6 +1849,43 @@ function isTerminal(state) {
1769
1849
 
1770
1850
  // src/fixtures/data.ts
1771
1851
  var FIXTURE_DATA = {
1852
+ "delivery-01-pending": {
1853
+ "state": {
1854
+ "kind": "DELIVERY",
1855
+ "state": "PENDING"
1856
+ },
1857
+ "provider": "MOONPAY",
1858
+ "transitions": [
1859
+ {
1860
+ "id": "poll",
1861
+ "mode": "AWAIT",
1862
+ "poll": {
1863
+ "endpoint": "GET /fiat/orders/o_31c/delivery",
1864
+ "intervalMs": 3e3,
1865
+ "backoffFactor": 1.5,
1866
+ "maxIntervalMs": 1e4,
1867
+ "giveUpAfterMs": 3e5
1868
+ }
1869
+ }
1870
+ ]
1871
+ },
1872
+ "delivery-02-succeeded": {
1873
+ "state": {
1874
+ "kind": "DELIVERY",
1875
+ "state": "SUCCEEDED",
1876
+ "txHash": "5VER\u2026"
1877
+ },
1878
+ "provider": "MOONPAY",
1879
+ "transitions": []
1880
+ },
1881
+ "delivery-03-failed": {
1882
+ "state": {
1883
+ "kind": "DELIVERY",
1884
+ "state": "FAILED"
1885
+ },
1886
+ "provider": "MOONPAY",
1887
+ "transitions": []
1888
+ },
1772
1889
  "screen-01-quote": {
1773
1890
  "state": {
1774
1891
  "kind": "QUOTE",
@@ -2304,6 +2421,45 @@ var FIXTURE_DATA = {
2304
2421
  "provider": "TRANSAK",
2305
2422
  "transitions": []
2306
2423
  },
2424
+ "screen-13b-order-settled-converted": {
2425
+ "state": {
2426
+ "kind": "ORDER",
2427
+ "phase": "CREATED",
2428
+ "order": {
2429
+ "orderId": "o_31c",
2430
+ "fiat": {
2431
+ "currency": "USD",
2432
+ "amount": "50.00"
2433
+ },
2434
+ "crypto": {
2435
+ "currency": "USDC",
2436
+ "network": "base",
2437
+ "amount": "48.73"
2438
+ },
2439
+ "method": "apple_pay",
2440
+ "createdAt": "\u2026"
2441
+ },
2442
+ "status": "SETTLED",
2443
+ "tx": {
2444
+ "chainId": 8453,
2445
+ "hash": "0x\u2026"
2446
+ }
2447
+ },
2448
+ "provider": "MOONPAY",
2449
+ "transitions": [
2450
+ {
2451
+ "id": "delivery",
2452
+ "mode": "AWAIT",
2453
+ "poll": {
2454
+ "endpoint": "GET /fiat/orders/o_31c/delivery",
2455
+ "intervalMs": 3e3,
2456
+ "backoffFactor": 1.5,
2457
+ "maxIntervalMs": 1e4,
2458
+ "giveUpAfterMs": 3e5
2459
+ }
2460
+ }
2461
+ ]
2462
+ },
2307
2463
  "screen-14-order-failed": {
2308
2464
  "state": {
2309
2465
  "kind": "ORDER",
@@ -2611,6 +2767,17 @@ var FIXTURES = [
2611
2767
  screen: 13,
2612
2768
  stateKey: "ORDER/CREATED"
2613
2769
  },
2770
+ {
2771
+ id: "screen-13b-order-settled-converted",
2772
+ file: "screen-13b-order-settled-converted.json",
2773
+ source: "CONTRACT_DOC",
2774
+ docRef: "Package README \xA7Delivery \xB7 a converted order at SETTLED",
2775
+ screen: 13,
2776
+ stateKey: "ORDER/CREATED",
2777
+ notes: [
2778
+ "The order body is the fiat leg only, as for a direct order. The backend offers the delivery transition because this order is converted; the client follows it instead of showing success."
2779
+ ]
2780
+ },
2614
2781
  {
2615
2782
  id: "screen-14-order-failed",
2616
2783
  file: "screen-14-order-failed.json",
@@ -2661,6 +2828,28 @@ var FIXTURES = [
2661
2828
  notes: [
2662
2829
  "The response-level `orderId` case. TODO(open-decision): orderId placement (beside `state` here vs inside it in the FE doc v0)."
2663
2830
  ]
2831
+ },
2832
+ {
2833
+ id: "delivery-01-pending",
2834
+ file: "delivery-01-pending.json",
2835
+ source: "CONTRACT_DOC",
2836
+ docRef: "Package README \xA7Delivery \xB7 the conversion is running",
2837
+ stateKey: "DELIVERY:PENDING"
2838
+ },
2839
+ {
2840
+ id: "delivery-02-succeeded",
2841
+ file: "delivery-02-succeeded.json",
2842
+ source: "CONTRACT_DOC",
2843
+ docRef: "Package README \xA7Delivery \xB7 the destination asset reached the user",
2844
+ stateKey: "DELIVERY:SUCCEEDED"
2845
+ },
2846
+ {
2847
+ id: "delivery-03-failed",
2848
+ file: "delivery-03-failed.json",
2849
+ source: "CONTRACT_DOC",
2850
+ docRef: "Package README \xA7Delivery \xB7 the conversion failed after payment",
2851
+ stateKey: "DELIVERY:FAILED",
2852
+ notes: ["No transition: the buyer has paid, so the client offers no new payment. Support recovers the funds."]
2664
2853
  }
2665
2854
  ];
2666
2855
  var FIXTURE_COVERAGE_GAPS = [
package/dist/index.mjs CHANGED
@@ -12,7 +12,7 @@ import {
12
12
  tableEntry,
13
13
  unofferedEndpoints,
14
14
  unreachableStates
15
- } from "./chunk-7GDFZ5UR.mjs";
15
+ } from "./chunk-WFLO72JO.mjs";
16
16
  import {
17
17
  MOONPAY_ENDPOINTS
18
18
  } from "./chunk-TIEGTTFY.mjs";
@@ -475,13 +475,6 @@ var $statusHistoryEntry = obj({ status: $orderStatus });
475
475
  var StatusHistoryEntrySchema = $statusHistoryEntry;
476
476
  var $tx = obj({ chainId: z.number(), hash: z.string() });
477
477
  var TxSchema = $tx;
478
- var $orderDeliveryState = z.enum(["SWAPPING", "DELIVERED", "FAILED"]);
479
- var FiatOrderDeliveryStateSchema = $orderDeliveryState;
480
- var $orderDelivery = z.discriminatedUnion("mode", [
481
- obj({ mode: z.literal("DIRECT") }),
482
- obj({ mode: z.literal("CONVERTED"), state: $orderDeliveryState, finalTxHash: z.string().min(1).nullable() })
483
- ]);
484
- var FiatOrderDeliverySchema = $orderDelivery;
485
478
  var $refund = obj({
486
479
  currency: z.enum(FIAT_CURRENCY_CODES),
487
480
  amount: z.string(),
@@ -858,12 +851,17 @@ var $orderCreatedState = obj({
858
851
  status: $orderStatus,
859
852
  statusHistory: z.array($statusHistoryEntry).optional(),
860
853
  tx: $tx.optional(),
861
- delivery: $orderDelivery.optional(),
862
854
  refund: $refund.optional(),
863
855
  failureReason: $failureReason.optional(),
864
856
  error: $failureReason.optional()
865
857
  });
866
858
  var OrderCreatedStateSchema = $orderCreatedState;
859
+ var $deliveryState = z.discriminatedUnion("state", [
860
+ obj({ kind: z.literal("DELIVERY"), state: z.literal("PENDING") }),
861
+ obj({ kind: z.literal("DELIVERY"), state: z.literal("SUCCEEDED"), txHash: z.string().min(1) }),
862
+ obj({ kind: z.literal("DELIVERY"), state: z.literal("FAILED") })
863
+ ]);
864
+ var DeliveryStateSchema = $deliveryState;
867
865
  var $providerBoundFlowState = z.union([
868
866
  $quoteState,
869
867
  $funAuthState,
@@ -875,7 +873,8 @@ var $providerBoundFlowState = z.union([
875
873
  $paymentCaptureState,
876
874
  $paymentInstructState,
877
875
  $orderAwaitingConfirmationState,
878
- $orderCreatedState
876
+ $orderCreatedState,
877
+ $deliveryState
879
878
  ]);
880
879
  var $flowState = z.union([$providerBoundFlowState, $blockedState]);
881
880
  var FlowStateSchema = $flowState;
@@ -914,13 +913,43 @@ var $termsErrorBody = obj({
914
913
  recovery: z.enum(["RETRY", "REQUOTE", "NONE"])
915
914
  });
916
915
  var FiatTermsErrorBodySchema = $termsErrorBody;
917
- var $destination = obj({
918
- chainId: z.string().regex(/^[1-9]\d*$/, "must be a decimal chain id"),
919
- tokenAddress: z.union([
920
- z.string().regex(/^0x[0-9a-fA-F]{40}$/, "must be an EVM address"),
921
- z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/, "must be a Solana base58 address")
916
+ var $evmAddress = z.custom(
917
+ (value) => typeof value === "string" && /^0x[0-9a-fA-F]{40}$/.test(value),
918
+ "must be an EVM address: 0x and 40 hex digits"
919
+ );
920
+ var $solanaAddress = z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/, "must be a Solana base58 address");
921
+ var $evmDestination = obj({
922
+ vm: z.literal("EVM"),
923
+ chainId: z.number().int().positive(),
924
+ asset: z.discriminatedUnion("kind", [
925
+ obj({
926
+ kind: z.literal("FUNGIBLE"),
927
+ token: z.discriminatedUnion("type", [
928
+ obj({ type: z.literal("NATIVE") }),
929
+ obj({ type: z.literal("ERC20"), address: $evmAddress })
930
+ ])
931
+ }),
932
+ obj({
933
+ kind: z.literal("NON_FUNGIBLE"),
934
+ contractAddress: $evmAddress,
935
+ tokenId: z.string().regex(/^(0|[1-9]\d*)$/, "must be a decimal integer")
936
+ })
937
+ ])
938
+ });
939
+ var $solanaDestination = obj({
940
+ vm: z.literal("SOLANA"),
941
+ asset: z.discriminatedUnion("kind", [
942
+ obj({
943
+ kind: z.literal("FUNGIBLE"),
944
+ token: z.discriminatedUnion("type", [
945
+ obj({ type: z.literal("NATIVE") }),
946
+ obj({ type: z.literal("SPL"), mint: $solanaAddress })
947
+ ])
948
+ }),
949
+ obj({ kind: z.literal("NON_FUNGIBLE"), mint: $solanaAddress })
922
950
  ])
923
951
  });
952
+ var $destination = z.discriminatedUnion("vm", [$evmDestination, $solanaDestination]);
924
953
  var FiatDestinationSchema = $destination;
925
954
  var $decimalAmount = z.string().regex(/^(?:0|[1-9]\d*)(?:\.\d+)?$/, "must be a decimal string");
926
955
  var compareDecimals = (left, right) => {
@@ -956,9 +985,7 @@ var $routingTableProvider = obj({
956
985
  provider: $routingProvider,
957
986
  next: z.enum(["READY", "AUTH", "DECLARATIVE_KYC", "DOCUMENTARY_KYC", "PENDING_REVIEW"]),
958
987
  visibility: z.enum(["COMPLETE", "PARTIAL", "AUTH_GATED"]),
959
- currentLimit: $decimalAmount.nullable(),
960
- railAsset: $destination.optional(),
961
- deliveryMode: z.enum(["DIRECT", "CONVERTED"]).optional()
988
+ currentLimit: $decimalAmount.nullable()
962
989
  });
963
990
  var $routingTableInterval = obj({
964
991
  min: $decimalAmount,
@@ -1115,6 +1142,43 @@ var FiatStepResponseSchema = $stepResponse;
1115
1142
 
1116
1143
  // src/fixtures/data.ts
1117
1144
  var FIXTURE_DATA = {
1145
+ "delivery-01-pending": {
1146
+ "state": {
1147
+ "kind": "DELIVERY",
1148
+ "state": "PENDING"
1149
+ },
1150
+ "provider": "MOONPAY",
1151
+ "transitions": [
1152
+ {
1153
+ "id": "poll",
1154
+ "mode": "AWAIT",
1155
+ "poll": {
1156
+ "endpoint": "GET /fiat/orders/o_31c/delivery",
1157
+ "intervalMs": 3e3,
1158
+ "backoffFactor": 1.5,
1159
+ "maxIntervalMs": 1e4,
1160
+ "giveUpAfterMs": 3e5
1161
+ }
1162
+ }
1163
+ ]
1164
+ },
1165
+ "delivery-02-succeeded": {
1166
+ "state": {
1167
+ "kind": "DELIVERY",
1168
+ "state": "SUCCEEDED",
1169
+ "txHash": "5VER\u2026"
1170
+ },
1171
+ "provider": "MOONPAY",
1172
+ "transitions": []
1173
+ },
1174
+ "delivery-03-failed": {
1175
+ "state": {
1176
+ "kind": "DELIVERY",
1177
+ "state": "FAILED"
1178
+ },
1179
+ "provider": "MOONPAY",
1180
+ "transitions": []
1181
+ },
1118
1182
  "screen-01-quote": {
1119
1183
  "state": {
1120
1184
  "kind": "QUOTE",
@@ -1650,6 +1714,45 @@ var FIXTURE_DATA = {
1650
1714
  "provider": "TRANSAK",
1651
1715
  "transitions": []
1652
1716
  },
1717
+ "screen-13b-order-settled-converted": {
1718
+ "state": {
1719
+ "kind": "ORDER",
1720
+ "phase": "CREATED",
1721
+ "order": {
1722
+ "orderId": "o_31c",
1723
+ "fiat": {
1724
+ "currency": "USD",
1725
+ "amount": "50.00"
1726
+ },
1727
+ "crypto": {
1728
+ "currency": "USDC",
1729
+ "network": "base",
1730
+ "amount": "48.73"
1731
+ },
1732
+ "method": "apple_pay",
1733
+ "createdAt": "\u2026"
1734
+ },
1735
+ "status": "SETTLED",
1736
+ "tx": {
1737
+ "chainId": 8453,
1738
+ "hash": "0x\u2026"
1739
+ }
1740
+ },
1741
+ "provider": "MOONPAY",
1742
+ "transitions": [
1743
+ {
1744
+ "id": "delivery",
1745
+ "mode": "AWAIT",
1746
+ "poll": {
1747
+ "endpoint": "GET /fiat/orders/o_31c/delivery",
1748
+ "intervalMs": 3e3,
1749
+ "backoffFactor": 1.5,
1750
+ "maxIntervalMs": 1e4,
1751
+ "giveUpAfterMs": 3e5
1752
+ }
1753
+ }
1754
+ ]
1755
+ },
1653
1756
  "screen-14-order-failed": {
1654
1757
  "state": {
1655
1758
  "kind": "ORDER",
@@ -1957,6 +2060,17 @@ var FIXTURES = [
1957
2060
  screen: 13,
1958
2061
  stateKey: "ORDER/CREATED"
1959
2062
  },
2063
+ {
2064
+ id: "screen-13b-order-settled-converted",
2065
+ file: "screen-13b-order-settled-converted.json",
2066
+ source: "CONTRACT_DOC",
2067
+ docRef: "Package README \xA7Delivery \xB7 a converted order at SETTLED",
2068
+ screen: 13,
2069
+ stateKey: "ORDER/CREATED",
2070
+ notes: [
2071
+ "The order body is the fiat leg only, as for a direct order. The backend offers the delivery transition because this order is converted; the client follows it instead of showing success."
2072
+ ]
2073
+ },
1960
2074
  {
1961
2075
  id: "screen-14-order-failed",
1962
2076
  file: "screen-14-order-failed.json",
@@ -2007,6 +2121,28 @@ var FIXTURES = [
2007
2121
  notes: [
2008
2122
  "The response-level `orderId` case. TODO(open-decision): orderId placement (beside `state` here vs inside it in the FE doc v0)."
2009
2123
  ]
2124
+ },
2125
+ {
2126
+ id: "delivery-01-pending",
2127
+ file: "delivery-01-pending.json",
2128
+ source: "CONTRACT_DOC",
2129
+ docRef: "Package README \xA7Delivery \xB7 the conversion is running",
2130
+ stateKey: "DELIVERY:PENDING"
2131
+ },
2132
+ {
2133
+ id: "delivery-02-succeeded",
2134
+ file: "delivery-02-succeeded.json",
2135
+ source: "CONTRACT_DOC",
2136
+ docRef: "Package README \xA7Delivery \xB7 the destination asset reached the user",
2137
+ stateKey: "DELIVERY:SUCCEEDED"
2138
+ },
2139
+ {
2140
+ id: "delivery-03-failed",
2141
+ file: "delivery-03-failed.json",
2142
+ source: "CONTRACT_DOC",
2143
+ docRef: "Package README \xA7Delivery \xB7 the conversion failed after payment",
2144
+ stateKey: "DELIVERY:FAILED",
2145
+ notes: ["No transition: the buyer has paid, so the client offers no new payment. Support recovers the funds."]
2010
2146
  }
2011
2147
  ];
2012
2148
  var FIXTURE_COVERAGE_GAPS = [
@@ -2387,6 +2523,7 @@ export {
2387
2523
  CountryCode,
2388
2524
  CryptoAmountSchema,
2389
2525
  DOCUMENTED_ENDPOINTS,
2526
+ DeliveryStateSchema,
2390
2527
  ENDPOINT_PATTERN,
2391
2528
  FIAT_CURRENCY_NAMES,
2392
2529
  FIAT_TERMS_ENDPOINT,
@@ -2402,8 +2539,6 @@ export {
2402
2539
  FiatEndpointSchema,
2403
2540
  FiatGeoSchema,
2404
2541
  FiatNextRequestSchema,
2405
- FiatOrderDeliverySchema,
2406
- FiatOrderDeliveryStateSchema,
2407
2542
  FiatProviderSchema,
2408
2543
  FiatRoutingQuoteErrorBodySchema,
2409
2544
  FiatRoutingQuoteRequestSchema,
@@ -43,7 +43,8 @@ export interface MoonPaySdkCredentials {
43
43
  }
44
44
  /**
45
45
  * On every request, not part of the result. `credentials` is present after `connect`.
46
- * `destination` is the asset the user receives at the end; `checkout.destination` stays the quote's.
46
+ * `destination` is the asset the user receives at the end; `checkout.destination` stays the quote's
47
+ * asset, which MoonPay delivers.
47
48
  */
48
49
  export type MoonPayRequestContext = {
49
50
  checkout: MoonPayCheckout;
@@ -252,7 +253,7 @@ export type MoonPayOrderRefusal = 'CUSTOMER_MISMATCH' | 'WALLET_MISMATCH' | 'UNR
252
253
  export type MoonPayNextAction = MoonPayConsentNextAction | MoonPaySessionNextAction | MoonPayConnectNextAction | MoonPayKycNextAction | MoonPayPrepareCaptureNextAction | MoonPayCaptureNextAction | MoonPayWaitNextAction | MoonPayOrderNextAction;
253
254
  /**
254
255
  * The order is terminal. `order` is its body, which the shared order screen renders. Nothing is left to
255
- * send to `/fiat/next`; a `CONVERTED` `delivery` still `SWAPPING` keeps the body's `GET /fiat/orders/:id` poll.
256
+ * send to `/fiat/next`. A converted order's `SETTLED` body offers the `delivery` transition: follow it.
256
257
  */
257
258
  export type MoonPayDone = {
258
259
  next: 'done';
package/dist/routing.d.ts CHANGED
@@ -21,7 +21,7 @@
21
21
  * an extra key or a blank string fails them, so send only the declared fields.
22
22
  */
23
23
  import type { CountryCode, FiatCurrencyCode, PaymentMethodCategory } from './codes';
24
- import type { FiatAmount, FiatDestination, FiatOrderDelivery, FiatProvider, QuoteLimitRange } from './types';
24
+ import type { FiatAmount, FiatDestination, FiatProvider, QuoteLimitRange } from './types';
25
25
  export declare const ROUTING_ENDPOINTS: {
26
26
  readonly table: "POST /fiat/routing/table";
27
27
  /** Temporary: `POST /fiat/next` replaces it for each provider that moves there. */
@@ -55,7 +55,10 @@ export interface FiatRoutingTableRequest {
55
55
  methods: PaymentMethodCategory[];
56
56
  /** Optional provider-specific inputs. */
57
57
  providers?: FiatRoutingTableProviderInputs;
58
- /** The asset the user receives, when it differs from `cryptoCurrencyCode` on `chainId`. */
58
+ /**
59
+ * The asset the user receives. Always sent; the backend adds a conversion only when it differs
60
+ * from the partner's configured asset. Optional so an older client still parses.
61
+ */
59
62
  destination?: FiatDestination;
60
63
  }
61
64
  /** What a provider needs from this buyer before it can take the payment. */
@@ -80,27 +83,7 @@ export interface RoutingTableProvider {
80
83
  * table's currency. `null` when unknown. The interval edges are the most after every step on offer.
81
84
  */
82
85
  currentLimit: string | null;
83
- /**
84
- * The asset this provider delivers on the order: the request's `cryptoCurrencyCode` on `chainId`,
85
- * or, when the request names a `destination`, the asset the backend chose to buy for it. Quote this
86
- * asset. Absent from a backend that predates it.
87
- */
88
- railAsset?: RoutingTableRailAsset;
89
- /** How the order reaches the user. Absent from a backend that predates it. */
90
- deliveryMode?: RoutingDeliveryMode;
91
- }
92
- /** An asset by chain and token address, in `FiatDestination`'s format. */
93
- export interface RoutingTableRailAsset {
94
- chainId: string;
95
- tokenAddress: string;
96
86
  }
97
- /**
98
- * `DIRECT`: the provider pays `railAsset` to the user's wallet, so the purchase is done when the
99
- * order settles. `CONVERTED`: the provider pays a deposit address that converts `railAsset` into the
100
- * request's `destination`, so the purchase is done when the order's `delivery.state` is `DELIVERED`.
101
- * The same values as the order's `delivery.mode`.
102
- */
103
- export type RoutingDeliveryMode = FiatOrderDelivery['mode'];
104
87
  /**
105
88
  * A `QuoteLimitRange` with two decimals (`"20.00"`) and the providers that serve it. The next
106
89
  * interval starts one cent above `max`. Adjacent intervals always rank differently.
@@ -149,7 +132,10 @@ export interface FiatRoutingQuoteTerms {
149
132
  routingOverrides?: {
150
133
  providers: RoutingProvider[];
151
134
  };
152
- /** The asset the user receives, when it differs from `cryptoCurrencyCode` on `chainId`. */
135
+ /**
136
+ * The asset the user receives. Always sent; the backend adds a conversion only when it differs
137
+ * from the partner's configured asset. Optional so an older client still parses.
138
+ */
153
139
  destination?: FiatDestination;
154
140
  }
155
141
  /**
package/dist/schemas.d.ts CHANGED
@@ -28,7 +28,7 @@
28
28
  */
29
29
  import { z } from 'zod';
30
30
  import type { UsStateCode } from './codes';
31
- import type { BlockedReason, CryptoAmount, FailureReason, FeeLine, FiatAmount, FiatEndpoint, FiatProvider, FiatStepResponse, FieldSpec, FlowState, FormDescriptor, FormField, FormFieldType, InstructionField, Instructions, Instrument, JsonValue, KYCProvider, KycReviewDuration, OrderRef, OrderStatus, OrderSummary, PollSpec, PreparedPayment, PaymentSurface, Quote, QuoteLimitRange, QuoteLimits, Recovery, Refund, ReportSpec, SelectOption, StatusHistoryEntry, Surface, PreferredIdentityDocument, KycFieldId, ClientExecutedDelivery, KycSdkResultReport, SurfaceKind, SurfaceProvider, TermsAcceptance, Transition, TransitionInputs, TransitionParams, Tx, FiatDestination, FiatGeo, FiatOrderDelivery, FiatOrderDeliveryState, FiatNextRequest } from './types';
31
+ import type { BlockedReason, CryptoAmount, FailureReason, FeeLine, FiatAmount, FiatEndpoint, FiatProvider, FiatStepResponse, FieldSpec, FlowState, FormDescriptor, FormField, FormFieldType, InstructionField, Instructions, Instrument, JsonValue, KYCProvider, KycReviewDuration, OrderRef, OrderStatus, OrderSummary, PollSpec, PreparedPayment, PaymentSurface, Quote, QuoteLimitRange, QuoteLimits, Recovery, Refund, ReportSpec, SelectOption, StatusHistoryEntry, Surface, PreferredIdentityDocument, KycFieldId, ClientExecutedDelivery, KycSdkResultReport, SurfaceKind, SurfaceProvider, TermsAcceptance, Transition, TransitionInputs, TransitionParams, Tx, FiatDestination, FiatGeo, FiatNextRequest } from './types';
32
32
  import type { FiatTermsErrorBody, FiatTermsRequest, FiatTermsResponse, TermsDocument, TermsDocumentAcceptance } from './terms';
33
33
  import type { FiatRoutingQuoteErrorBody, FiatRoutingQuoteRequest, FiatRoutingQuoteTerms, FiatRoutingTableErrorBody, FiatRoutingTableRequest, FiatRoutingTableResponse } from './routing';
34
34
  export declare const JsonSchema: z.ZodType<JsonValue>;
@@ -54,8 +54,6 @@ export declare const OrderRefSchema: z.ZodType<OrderRef>;
54
54
  export declare const OrderSummarySchema: z.ZodType<OrderSummary>;
55
55
  export declare const StatusHistoryEntrySchema: z.ZodType<StatusHistoryEntry>;
56
56
  export declare const TxSchema: z.ZodType<Tx>;
57
- export declare const FiatOrderDeliveryStateSchema: z.ZodType<FiatOrderDeliveryState>;
58
- export declare const FiatOrderDeliverySchema: z.ZodType<FiatOrderDelivery>;
59
57
  export declare const RefundSchema: z.ZodType<Refund>;
60
58
  export declare const SurfaceKindSchema: z.ZodType<SurfaceKind>;
61
59
  export declare const PreferredIdentityDocumentSchema: z.ZodType<PreferredIdentityDocument>;
@@ -109,6 +107,7 @@ export declare const PaymentCaptureStateSchema: z.ZodType<State<'PAYMENT', 'CAPT
109
107
  export declare const PaymentInstructStateSchema: z.ZodType<State<'PAYMENT', 'INSTRUCT'>>;
110
108
  export declare const OrderAwaitingConfirmationStateSchema: z.ZodType<State<'ORDER', 'AWAITING_CONFIRMATION'>>;
111
109
  export declare const OrderCreatedStateSchema: z.ZodType<State<'ORDER', 'CREATED'>>;
110
+ export declare const DeliveryStateSchema: z.ZodType<State<'DELIVERY'>>;
112
111
  export declare const FlowStateSchema: z.ZodType<FlowState>;
113
112
  export declare const TermsDocumentSchema: z.ZodType<TermsDocument>;
114
113
  export declare const TermsDocumentAcceptanceSchema: z.ZodType<TermsDocumentAcceptance>;
package/dist/table.d.ts CHANGED
@@ -12,12 +12,14 @@
12
12
  * - Terminality of `ORDER{CREATED}` rides `status`, because terminal outcomes are OrderStatus,
13
13
  * never kinds (contract §The fiat step response). The set is enumerated below as
14
14
  * `TERMINAL_ORDER_STATUSES` — clients read it, they never derive it.
15
+ * - `DELIVERY` is keyed by its `state`, like KYC by `reason`: its three states differ in
16
+ * terminality and in what they may carry.
15
17
  * - A terminal *state* carries no transitions. A terminal *status* still can: `FAILED` with a
16
18
  * retryable `failureReason` carries the recovery CTA (FE doc Screen 14).
17
19
  * - The stale rule means any call may return any state. `mayReturn` is the conformance
18
20
  * assertion on the *typical* server sequence — the client never uses it to gate rendering.
19
21
  */
20
- import type { FiatEndpoint, FlowState, OrderStatus, TransitionMode } from './types';
22
+ import type { DeliveryState, FiatEndpoint, FlowState, OrderStatus, TransitionMode } from './types';
21
23
  /**
22
24
  * The package version IS the capability handshake's table version (contract §Conformance
23
25
  * package → Versioning). Derived from `package.json#version` at build time so the two can
@@ -28,9 +30,9 @@ export declare const TABLE_VERSION: string;
28
30
  /**
29
31
  * State identity = kind + phase + the state's named discriminant (FE doc §Decisions).
30
32
  * The table keys on kind + phase (+ `reason` for KYC, whose three reasons differ in terminality
31
- * and in what they may carry).
33
+ * and in what they may carry; `DELIVERY` keys on its `state` for the same reason).
32
34
  */
33
- export type StateKey = 'QUOTE' | 'FUN_AUTH' | 'SESSION_AUTH' | 'KYC/CAPTURE' | 'KYC/INPUT_REQUIRED' | 'KYC/NO_ACTION_REQUIRED:IN_REVIEW' | 'KYC/NO_ACTION_REQUIRED:ON_HOLD' | 'KYC/NO_ACTION_REQUIRED:REJECTED' | 'PENDING_ORDER' | 'BLOCKED' | 'PAYMENT/CAPTURE' | 'PAYMENT/INSTRUCT' | 'ORDER/AWAITING_CONFIRMATION' | 'ORDER/CREATED';
35
+ export type StateKey = 'QUOTE' | 'FUN_AUTH' | 'SESSION_AUTH' | 'KYC/CAPTURE' | 'KYC/INPUT_REQUIRED' | 'KYC/NO_ACTION_REQUIRED:IN_REVIEW' | 'KYC/NO_ACTION_REQUIRED:ON_HOLD' | 'KYC/NO_ACTION_REQUIRED:REJECTED' | 'PENDING_ORDER' | 'BLOCKED' | 'PAYMENT/CAPTURE' | 'PAYMENT/INSTRUCT' | 'ORDER/AWAITING_CONFIRMATION' | 'ORDER/CREATED' | 'DELIVERY:PENDING' | 'DELIVERY:SUCCEEDED' | 'DELIVERY:FAILED';
34
36
  /**
35
37
  * Terminal per the OrderStatus machine's monotonic ranks (contract §The fiat step response).
36
38
  *
@@ -64,6 +66,8 @@ export interface TableEntry {
64
66
  phase?: string;
65
67
  /** KYC `NO_ACTION_REQUIRED` only. */
66
68
  reason?: 'IN_REVIEW' | 'ON_HOLD' | 'REJECTED';
69
+ /** `DELIVERY` only. */
70
+ state?: DeliveryState;
67
71
  /** FE doc screen numbers that render this state. */
68
72
  screens: readonly number[];
69
73
  /**
@@ -90,7 +94,7 @@ export declare const STATE_KEYS: StateKey[];
90
94
  * named by the table (QUOTE's capture-first entry) while the doc's endpoint table still lists no
91
95
  * session-minting call for that rail.
92
96
  */
93
- export declare const DOCUMENTED_ENDPOINTS: readonly ["GET /fiat/payment-methods", "POST /fiat/quote", "POST /fiat/auth", "POST /fiat/payment-session", "POST /fiat/session", "POST /fiat/session/verify", "GET /fiat/quotes/:quoteRef", "POST /fiat/kyc/form", "POST /fiat/kyc/capture", "POST /fiat/kyc/sdk-token", "POST /fiat/kyc/document", "POST /fiat/instruments", "POST /fiat/orders", "GET /fiat/orders/:id", "GET /fiat/orders/:id/instructions", "POST /fiat/orders/:id/confirm-payment", "POST /fiat/orders/:id/reference", "POST /fiat/orders/:id/cancel", "POST /fiat/orders/:id/surface-result"];
97
+ export declare const DOCUMENTED_ENDPOINTS: readonly ["GET /fiat/payment-methods", "POST /fiat/quote", "POST /fiat/auth", "POST /fiat/payment-session", "POST /fiat/session", "POST /fiat/session/verify", "GET /fiat/quotes/:quoteRef", "POST /fiat/kyc/form", "POST /fiat/kyc/capture", "POST /fiat/kyc/sdk-token", "POST /fiat/kyc/document", "POST /fiat/instruments", "POST /fiat/orders", "GET /fiat/orders/:id", "GET /fiat/orders/:id/delivery", "GET /fiat/orders/:id/instructions", "POST /fiat/orders/:id/confirm-payment", "POST /fiat/orders/:id/reference", "POST /fiat/orders/:id/cancel", "POST /fiat/orders/:id/surface-result"];
94
98
  /**
95
99
  * Documented endpoints no flow state offers, and why. Declared so an endpoint nothing can reach is
96
100
  * visible instead of silent — the table test asserts the unoffered set equals exactly these.
package/dist/table.js CHANGED
@@ -36,7 +36,7 @@ __export(table_exports, {
36
36
  module.exports = __toCommonJS(table_exports);
37
37
 
38
38
  // package.json
39
- var version = "0.36.0-uda.2";
39
+ var version = "0.36.0-uda.4";
40
40
 
41
41
  // src/table.ts
42
42
  var TABLE_VERSION = version;
@@ -396,9 +396,16 @@ var TRANSITION_TABLE = {
396
396
  id: "poll",
397
397
  mode: "AWAIT",
398
398
  endpoint: "GET /fiat/orders/:id",
399
- when: "status is non-terminal, or delivery.state is SWAPPING",
399
+ when: "status is non-terminal",
400
400
  note: "Documented giveUpAfterMs 300000 \u2014 on give-up the wizard exits and the durable order takes over."
401
401
  },
402
+ {
403
+ id: "delivery",
404
+ mode: "AWAIT",
405
+ endpoint: "GET /fiat/orders/:id/delivery",
406
+ when: "status is SETTLED and the order is converted: the provider paid a deposit address that converts into the destination",
407
+ note: "The backend decides; the client never infers a converted order. It follows this transition when offered, and otherwise treats SETTLED as done."
408
+ },
402
409
  {
403
410
  id: "retry_payment",
404
411
  mode: "SUBMIT",
@@ -419,7 +426,7 @@ var TRANSITION_TABLE = {
419
426
  note: "TODO(open-decision): cancel placement (FE doc open questions 1+2); per-rail eligibility is contract OQ7."
420
427
  }
421
428
  ],
422
- mayReturn: ["ORDER/CREATED"],
429
+ mayReturn: ["ORDER/CREATED", "DELIVERY:PENDING", "DELIVERY:SUCCEEDED", "DELIVERY:FAILED"],
423
430
  terminal: false,
424
431
  terminalStatuses: TERMINAL_ORDER_STATUSES,
425
432
  notes: [
@@ -427,9 +434,53 @@ var TRANSITION_TABLE = {
427
434
  "A terminal status may still carry a recovery transition: FAILED + retryable failureReason emits it (FE doc Screen 14); non-retryable emits [].",
428
435
  "ON_HOLD is a non-terminal status (resolves to PROCESSING or REFUNDED) \u2014 and is NOT the same thing as the KYC ON_HOLD reason; see the note on that field.",
429
436
  "CAPTURE_ORPHANED is non-terminal pending the backend rank map (added from review 2026-08-14).",
430
- "SETTLED is terminal for the order. When delivery.mode is CONVERTED, the conversion into the destination may still run after SETTLED: the backend keeps offering the AWAIT poll while delivery.state is SWAPPING, and the client keeps polling until delivery.state is DELIVERED or FAILED.",
437
+ "SETTLED is terminal for the order and ends a direct purchase. On a converted order it carries the delivery transition, and the purchase continues in DELIVERY (GET /fiat/orders/:id/delivery). The order body itself never describes the conversion.",
431
438
  "TODO(open-decision): contract OQ7 \u2014 under/over-payment is the biggest unenumerated branch."
432
439
  ]
440
+ },
441
+ "DELIVERY:PENDING": {
442
+ key: "DELIVERY:PENDING",
443
+ kind: "DELIVERY",
444
+ state: "PENDING",
445
+ screens: [7],
446
+ docStatus: "SPECIFIED",
447
+ allowedTransitions: [
448
+ {
449
+ id: "poll",
450
+ mode: "AWAIT",
451
+ endpoint: "GET /fiat/orders/:id/delivery",
452
+ note: "Giving up the poll does not fail the purchase: the backend still finishes the delivery or raises it to support."
453
+ }
454
+ ],
455
+ mayReturn: ["DELIVERY:PENDING", "DELIVERY:SUCCEEDED", "DELIVERY:FAILED"],
456
+ terminal: false,
457
+ notes: [
458
+ "The fiat leg is SETTLED; a crypto asset provider is converting it into the destination and paying the user. The client shows a generic processing screen."
459
+ ]
460
+ },
461
+ "DELIVERY:SUCCEEDED": {
462
+ key: "DELIVERY:SUCCEEDED",
463
+ kind: "DELIVERY",
464
+ state: "SUCCEEDED",
465
+ screens: [13],
466
+ docStatus: "SPECIFIED",
467
+ allowedTransitions: [],
468
+ mayReturn: [],
469
+ terminal: true,
470
+ notes: ["The destination asset reached the user. txHash is the transaction that paid them."]
471
+ },
472
+ "DELIVERY:FAILED": {
473
+ key: "DELIVERY:FAILED",
474
+ kind: "DELIVERY",
475
+ state: "FAILED",
476
+ screens: [],
477
+ docStatus: "SPECIFIED",
478
+ allowedTransitions: [],
479
+ mayReturn: [],
480
+ terminal: true,
481
+ notes: [
482
+ "The buyer has paid and the asset did not arrive. Support recovers the funds, so the client shows a dedicated failure screen that offers no new payment."
483
+ ]
433
484
  }
434
485
  };
435
486
  var STATE_KEYS = Object.keys(TRANSITION_TABLE);
@@ -448,6 +499,7 @@ var DOCUMENTED_ENDPOINTS = [
448
499
  "POST /fiat/instruments",
449
500
  "POST /fiat/orders",
450
501
  "GET /fiat/orders/:id",
502
+ "GET /fiat/orders/:id/delivery",
451
503
  "GET /fiat/orders/:id/instructions",
452
504
  "POST /fiat/orders/:id/confirm-payment",
453
505
  "POST /fiat/orders/:id/reference",
@@ -523,6 +575,8 @@ function stateKey(state) {
523
575
  return state.phase === "CAPTURE" ? "PAYMENT/CAPTURE" : "PAYMENT/INSTRUCT";
524
576
  case "ORDER":
525
577
  return state.phase === "AWAITING_CONFIRMATION" ? "ORDER/AWAITING_CONFIRMATION" : "ORDER/CREATED";
578
+ case "DELIVERY":
579
+ return `DELIVERY:${state.state}`;
526
580
  default: {
527
581
  const exhaustive = state;
528
582
  throw new Error(`unknown FlowState: ${JSON.stringify(exhaustive)}`);
package/dist/table.mjs CHANGED
@@ -11,7 +11,7 @@ import {
11
11
  tableEntry,
12
12
  unofferedEndpoints,
13
13
  unreachableStates
14
- } from "./chunk-7GDFZ5UR.mjs";
14
+ } from "./chunk-WFLO72JO.mjs";
15
15
  export {
16
16
  DOCUMENTED_ENDPOINTS,
17
17
  STATE_KEYS,
package/dist/types.d.ts CHANGED
@@ -56,7 +56,7 @@ export type HttpVerb = 'GET' | 'POST';
56
56
  * cannot express "no slash", so `GET /fiat/orders/${string}` also admits sub-paths. Precision at
57
57
  * that level is the table's job (`allowedTransitions` + `endpointMatches`), not the type's.
58
58
  */
59
- export type FiatEndpoint = 'GET /fiat/payment-methods' | 'POST /fiat/quote' | 'POST /fiat/auth' | 'POST /fiat/payment-session' | 'POST /fiat/session' | 'POST /fiat/session/verify' | `GET /fiat/quotes/${string}` | 'POST /fiat/kyc/form' | 'POST /fiat/kyc/capture' | 'POST /fiat/kyc/sdk-token' | 'POST /fiat/kyc/document' | 'POST /fiat/instruments' | 'POST /fiat/orders' | `GET /fiat/orders/${string}` | `GET /fiat/orders/${string}/instructions` | `POST /fiat/orders/${string}/confirm-payment` | `POST /fiat/orders/${string}/reference` | `POST /fiat/orders/${string}/cancel` | `POST /fiat/orders/${string}/surface-result`;
59
+ export type FiatEndpoint = 'GET /fiat/payment-methods' | 'POST /fiat/quote' | 'POST /fiat/auth' | 'POST /fiat/payment-session' | 'POST /fiat/session' | 'POST /fiat/session/verify' | `GET /fiat/quotes/${string}` | 'POST /fiat/kyc/form' | 'POST /fiat/kyc/capture' | 'POST /fiat/kyc/sdk-token' | 'POST /fiat/kyc/document' | 'POST /fiat/instruments' | 'POST /fiat/orders' | `GET /fiat/orders/${string}` | `GET /fiat/orders/${string}/delivery` | `GET /fiat/orders/${string}/instructions` | `POST /fiat/orders/${string}/confirm-payment` | `POST /fiat/orders/${string}/reference` | `POST /fiat/orders/${string}/cancel` | `POST /fiat/orders/${string}/surface-result`;
60
60
  /**
61
61
  * Routing metadata, not sequencing policy. Reserved values may be emitted only after their adapter
62
62
  * and conformance fixture land.
@@ -76,9 +76,9 @@ export type FiatProvider = 'TRANSAK' | 'SWAPPED' | 'BANXA' | 'MOONPAY' | 'STRIPE
76
76
  */
77
77
  export type OrderStatus = 'CREATING' | 'AWAITING_PAYMENT' | 'PAYMENT_VERIFYING' | 'PROCESSING' | 'PENDING_DELIVERY' | 'ON_HOLD' | 'CRYPTO_SENT'
78
78
  /**
79
- * The provider's crypto reached the deposit address. Terminal for the order. When the order's
80
- * `delivery` is `CONVERTED`, the swap into the destination may still be running: read
81
- * `delivery.state`.
79
+ * The provider's crypto reached the deposit address. Terminal for the order. A converted order
80
+ * (the provider pays a deposit address that converts into the destination) offers the `delivery`
81
+ * transition here, and the purchase continues in `DELIVERY`.
82
82
  */
83
83
  | 'SETTLED' | 'EXPIRED' | 'CANCELLED' | 'FAILED' | 'REFUNDED'
84
84
  /**
@@ -560,7 +560,7 @@ export type KycReviewDuration = {
560
560
  /**
561
561
  * The semantic state. Three rules keep this union honest:
562
562
  * 1. sub-states are payload discriminants, never new kinds
563
- * 2. terminal outcomes are OrderStatus, never kinds
563
+ * 2. terminal outcomes are OrderStatus (after the order, the `DELIVERY` state), never kinds
564
564
  * 3. every fallible state carries `error?: FailureReason`
565
565
  */
566
566
  export type FlowState =
@@ -679,13 +679,32 @@ export type FlowState =
679
679
  status: OrderStatus;
680
680
  statusHistory?: StatusHistoryEntry[];
681
681
  tx?: Tx;
682
- /** How the order reaches the user. Absent from a backend that predates it. */
683
- delivery?: FiatOrderDelivery;
684
682
  refund?: Refund;
685
683
  failureReason?: FailureReason;
686
684
  error?: FailureReason;
685
+ }
686
+ /**
687
+ * The crypto delivery after the fiat provider's leg, from `GET /fiat/orders/:id/delivery`. Only a
688
+ * converted order has one: its `ORDER{CREATED, SETTLED}` offers the `delivery` transition here.
689
+ * `PENDING` polls itself. `SUCCEEDED` carries the transaction that paid the user. `FAILED` means the
690
+ * buyer has paid and the asset did not arrive: support recovers the funds, so the client never offers
691
+ * another payment from it.
692
+ */
693
+ | {
694
+ kind: 'DELIVERY';
695
+ state: 'PENDING';
696
+ } | {
697
+ kind: 'DELIVERY';
698
+ state: 'SUCCEEDED';
699
+ txHash: string;
700
+ } | {
701
+ kind: 'DELIVERY';
702
+ state: 'FAILED';
687
703
  };
688
704
  export type FlowStateKind = FlowState['kind'];
705
+ export type DeliveryState = Extract<FlowState, {
706
+ kind: 'DELIVERY';
707
+ }>['state'];
689
708
  export type BlockedReason = 'REGION_UNSUPPORTED' | 'ASSET_UNSUPPORTED' | 'ALL_PROVIDERS_DECLINED' | 'AMOUNT_UNSERVABLE'
690
709
  /** The installed client did not declare a capability required by every otherwise-viable route. */
691
710
  | 'CLIENT_UPGRADE_REQUIRED';
@@ -750,33 +769,50 @@ export type FiatStepResponse = (FiatStepResponseBase & {
750
769
  };
751
770
  });
752
771
  /**
753
- * The asset the user receives at the end of the purchase. Optional on every request that can lead
754
- * the backend to pick a deposit address. When it differs from the asset the provider delivers, the
755
- * backend pays a deposit address that swaps into it. The recipient always comes from the verified
756
- * partner assertion, never from this field.
757
- */
758
- export interface FiatDestination {
759
- /** Decimal, as the routing requests send it: `"8453"`, Solana `"1151111081099710"`. */
760
- chainId: string;
761
- /** An EVM `0x` address (40 hex digits) or a Solana base58 mint. */
762
- tokenAddress: string;
763
- }
764
- /**
765
- * How an order reaches the user. `DIRECT`: the provider pays the user's wallet, so the purchase is
766
- * done at `SETTLED`. `CONVERTED`: the provider pays a deposit address that converts the provider's
767
- * asset into the request's `destination`. The order still ends at `SETTLED`, and `state` reports the
768
- * conversion: `SWAPPING` while it runs, `DELIVERED` once the destination asset reached the user's
769
- * wallet, `FAILED` when it stopped without paying the user. `finalTxHash` is the transaction that paid
770
- * the user, `null` until `DELIVERED`.
772
+ * The asset the user receives at the end of the purchase. The client always sends it. The backend
773
+ * compares it with the partner's configured asset and adds a conversion only when they differ,
774
+ * so its presence never turns a conversion on. The fields that carry it are optional only so a client
775
+ * that predates it still parses; a missing destination means the partner's configured asset. The
776
+ * recipient always comes from the verified partner assertion, never from this field.
777
+ *
778
+ * Split by VM, then by asset kind. Solana carries no chain id: the backend maps each VM to its own
779
+ * chain ids in one place. `NON_FUNGIBLE` is reserved: the backend does not serve it yet and answers
780
+ * it as unservable.
771
781
  */
772
- export type FiatOrderDelivery = {
773
- mode: 'DIRECT';
782
+ export type FiatDestination = {
783
+ vm: 'EVM';
784
+ /** The EVM chain id: `8453` for Base. */
785
+ chainId: number;
786
+ asset: {
787
+ kind: 'FUNGIBLE';
788
+ token: {
789
+ type: 'NATIVE';
790
+ } | {
791
+ type: 'ERC20';
792
+ address: `0x${string}`;
793
+ };
794
+ } | {
795
+ kind: 'NON_FUNGIBLE';
796
+ contractAddress: `0x${string}`;
797
+ /** A decimal integer string, so a uint256 id keeps its precision. */
798
+ tokenId: string;
799
+ };
774
800
  } | {
775
- mode: 'CONVERTED';
776
- state: FiatOrderDeliveryState;
777
- finalTxHash: string | null;
801
+ vm: 'SOLANA';
802
+ /** Every `mint` is a base58 address. */
803
+ asset: {
804
+ kind: 'FUNGIBLE';
805
+ token: {
806
+ type: 'NATIVE';
807
+ } | {
808
+ type: 'SPL';
809
+ mint: string;
810
+ };
811
+ } | {
812
+ kind: 'NON_FUNGIBLE';
813
+ mint: string;
814
+ };
778
815
  };
779
- export type FiatOrderDeliveryState = 'SWAPPING' | 'DELIVERED' | 'FAILED';
780
816
  /** The geo endpoint's response, sent on every `/next` request. `alpha2` is ISO 3166-1 alpha-2. */
781
817
  export type FiatGeo = {
782
818
  alpha2: string;
@@ -784,7 +820,7 @@ export type FiatGeo = {
784
820
  ip?: string;
785
821
  };
786
822
  /**
787
- * The body of every `POST /fiat/next`: `provider`, `geo`, the optional `destination`, and the
823
+ * The body of every `POST /fiat/next`: `provider`, `geo`, the `destination`, and the
788
824
  * provider's own request, which names its `action`. Each provider defines its actions and their
789
825
  * fields (`./moonpay`).
790
826
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fun-xyz/fiat-contract",
3
- "version": "0.36.0-uda.2",
3
+ "version": "0.36.0-uda.4",
4
4
  "description": "Published conformance contract for Fun's headless fiat onramp: FlowState/Transition types, zod schemas, the transition table as data, recorded fixtures, assertion helpers.",
5
5
  "license": "MIT",
6
6
  "repository": {