@ixo/action-protocol 0.9.2 → 0.10.0

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,44 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.10.0
4
+
5
+ One operation kind for sending a token from the person's wallet to another
6
+ address (wire level 8). Every existing shape is unchanged. The Hub offers and
7
+ accepts it only from callers that declare `?version=8`, because every earlier
8
+ parser refuses a capabilities document, card or receipt that names a kind it
9
+ does not know.
10
+
11
+ - `ixo.wallet.send.v1` (`network`, `from: {chain, denom}`, `to: {chain,
12
+ denom}`, `recipient`, `amountBaseUnits`, `speed`): send `amountBaseUnits`
13
+ of `from.denom` on `from.chain` so that `to.denom` arrives at `recipient`
14
+ on `to.chain` (the same chain and token, or another one). `chain` is the
15
+ Hub's chain key (`^[a-z0-9]{2,16}$`); `denom` is the chain's own denom,
16
+ `^[A-Za-z0-9][A-Za-z0-9/:._-]{1,255}$` (a bank denom or a `0x` token
17
+ contract); `recipient` is `^[A-Za-z0-9]{10,128}$` (the Hub checks it for
18
+ the destination chain); `amountBaseUnits` is an integer above 0 of at most
19
+ 78 digits (never "all"); `speed` is `standard`, `fast` or `null` (the
20
+ person picks on the page). The card has no free text: its words are the
21
+ Hub's own. Approved with `/decision`; the approve body adds `send: {speed,
22
+ quotedLossPercent}` (the quote the person saw).
23
+ - Receipt `ixo.wallet.sent.v1` (`moveId`, `toChain`, `denom`,
24
+ `amountBaseUnits` = what arrived, `recipient`, `completedAt`). It must name
25
+ the operation's `to.chain` and recipient (compared without case: the Hub
26
+ returns EIP-55 or lower-case bech32).
27
+ - A send that did not start or did not reach the recipient ends `failed`
28
+ with `ixo.submission.failed.v1`, `step: "send"` (added to
29
+ `SUBMISSION_FAILURE_STEPS`).
30
+ - Review view field `walletSend` (`WalletSendDisplay`): the Hub-computed
31
+ `from` (chain, chainName, denom, symbol, decimals, amountBaseUnits), `to`
32
+ (chain, chainName, denom, symbol, decimals, and optional `known`: true
33
+ when the Hub itself knows the token; false or absent, the page shows the
34
+ denom too), `recipient` (canonical), `recipientOwn` and `moveId` (null
35
+ until approved). `parseReviewView` refuses one that does not describe
36
+ exactly the operation.
37
+ - No wire shape for the face check: the Hub starts a send to someone else's
38
+ address only after the person passed a face check at IXO Self. Until then
39
+ the card stays `submitted`; a check that did not pass ends it `failed`
40
+ with `ixo.submission.failed.v1`, `step: "send"`.
41
+
3
42
  ## 0.9.2
4
43
 
5
44
  - Add an owner-only `surveyReview` to the browser review view for mainnet Youth Voice collection 13530.
package/README.md CHANGED
@@ -36,6 +36,56 @@ Callers declare the envelope version they parse with `?version=2` on
36
36
  (`CHAIN_TX_GROUP_MESSAGE_TYPES`, `chainTxMessageTypesForLevel(7)`).
37
37
  Callers at level 6 see the 33 (`CHAIN_TX_LEVEL6_MESSAGE_TYPES`) and get
38
38
  `400 protocol_version_required` for a group type.
39
+ - `?version=8` (0.10.0): level 7 plus the wallet send card
40
+ (`ixo.wallet.send.v1`) and its receipt `ixo.wallet.sent.v1`. Callers below
41
+ 8 never see the kind and get `400 protocol_version_required` for it.
42
+
43
+ ## Wallet send (`ixo.wallet.send.v1`, 0.10.0)
44
+
45
+ Send `amountBaseUnits` of `from.denom` on `from.chain` from the person's
46
+ wallet so that `to.denom` arrives at `recipient` on `to.chain` (the same
47
+ chain and token, or another one).
48
+
49
+ - `{network, from: {chain, denom}, to: {chain, denom}, recipient,
50
+ amountBaseUnits, speed}`:
51
+ - `network`: the Hub's own, e.g. `"ixo mainnet"`.
52
+ - `chain`: the Hub's chain key (`ixo`, `base`, `osmosis`, …),
53
+ `^[a-z0-9]{2,16}$`.
54
+ - `denom`: the chain's own denom, a bank denom or a `0x` token contract,
55
+ `^[A-Za-z0-9][A-Za-z0-9/:._-]{1,255}$`.
56
+ - `recipient`: the address on `to.chain`, `^[A-Za-z0-9]{10,128}$` (the Hub
57
+ checks it for that chain).
58
+ - `amountBaseUnits`: an integer above 0, at most 78 digits, never "all".
59
+ - `speed`: `"standard"`, `"fast"` or `null` (the person picks on the page).
60
+ - No free text: the review page explains the send in the Hub's own words from
61
+ the checked fields and a live quote.
62
+ - The Hub refuses what it would refuse from the wallet's own Send page:
63
+ `400 invalid_recipient`, `422 recipient_not_allowed`, `send_to_self`,
64
+ `fast_unavailable`, `chain_not_allowed`, `route_unavailable`, and
65
+ `503 sends_disabled` while sending is switched off (today it is on only on
66
+ mainnet).
67
+ - The review view (`ActionReviewView.walletSend`, type `WalletSendDisplay`)
68
+ carries what the Hub computed: `from` (chain, chainName, denom, symbol,
69
+ decimals, amountBaseUnits), `to` (chain, chainName, denom, symbol,
70
+ decimals, optional `known`), `recipient` (the Hub's spelling: EIP-55 or
71
+ lower-case bech32), `recipientOwn` and `moveId` (null until the move
72
+ exists). `parseReviewView` refuses one that does not describe exactly the
73
+ operation.
74
+ - A send to someone else's address (`recipientOwn: false`) starts only after
75
+ the person passed a face check at IXO Self bound to exactly that send. The
76
+ review view carries no face check state: the Hub's own page reads it from
77
+ `GET /api/action-reviews/:id/send-check` (`status` `pending`, `verified`,
78
+ `started`, `failed` or `expired`; see `docs/action-operations-api.md`).
79
+ For the oracle the card stays `submitted` while the check waits. A move to
80
+ the person's own address needs no check.
81
+ - Outcomes: `authorized` and `submitted` on approval, then `succeeded`
82
+ (`ixo.wallet.sent.v1`: `moveId`, `toChain`, `denom`, `amountBaseUnits` =
83
+ what arrived, `recipient`, `completedAt`) or `failed`
84
+ (`ixo.submission.failed.v1`, `step: "send"`; relay its `message` only).
85
+ A face check that did not pass ends `failed` the same way, and nothing
86
+ was sent. A send the Hub's team has to look at is `unknown` until it ends.
87
+ `assertReceiptForOperation` checks that `ixo.wallet.sent.v1` names the
88
+ operation's `to.chain` and recipient (recipient compared without case).
39
89
 
40
90
  ## Applications and claims (`ixo.bid.submit.v1`, `ixo.claim.submit.v1`, 0.7.0)
41
91
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ixo/action-protocol",
3
- "version": "0.9.2",
3
+ "version": "0.10.0",
4
4
  "description": "Shared wire contract between IXO Auth Hub, oracle runtimes and channel gateways for reviewed action cards (operations, capabilities, outcomes, receipts).",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
package/src/index.d.ts CHANGED
@@ -49,11 +49,70 @@ export type ClaimSubmitOperation = {
49
49
  data: string;
50
50
  evidence: ClaimEvidence[];
51
51
  };
52
+ /** 0.10.0: a token on one of the Hub's move chains. */
53
+ export type WalletToken = {
54
+ /** The Hub's chain key ("ixo", "base", "osmosis", …), `^[a-z0-9]{2,16}$`. */
55
+ chain: string;
56
+ /** The chain's own denom: a bank denom or a 0x token contract. */
57
+ denom: string;
58
+ };
59
+ /**
60
+ * 0.10.0: send a token from the person's wallet to another address,
61
+ * optionally arriving as another token on another chain (wire level 8). No
62
+ * free text: the review page's words are the Hub's own. The Hub checks the
63
+ * chains, tokens and recipient exactly as for a send from the wallet.
64
+ */
65
+ export type WalletSendOperation = {
66
+ kind: "ixo.wallet.send.v1";
67
+ /** The Hub executes only its own network. */
68
+ network: SubmissionNetwork;
69
+ from: WalletToken;
70
+ to: WalletToken;
71
+ /** The address on `to.chain` that receives the funds, `^[A-Za-z0-9]{10,128}$`. */
72
+ recipient: string;
73
+ /** Base units of `from.denom`: an integer above 0, at most 78 digits. */
74
+ amountBaseUnits: string;
75
+ /** null: the person picks on the review page. */
76
+ speed: "standard" | "fast" | null;
77
+ };
78
+ /** 0.10.0: the Hub-computed display of a wallet send (`ActionReviewView.walletSend`). */
79
+ export type WalletSendDisplay = {
80
+ from: {
81
+ chain: string;
82
+ chainName: string;
83
+ denom: string;
84
+ symbol: string;
85
+ decimals: number;
86
+ amountBaseUnits: string;
87
+ };
88
+ /** The token that arrives (the Hub's pinned denom for USDC on ixo). */
89
+ to: {
90
+ chain: string;
91
+ chainName: string;
92
+ denom: string;
93
+ symbol: string;
94
+ decimals: number;
95
+ /**
96
+ * true when the Hub itself knows the token (the chain's own coin, or one
97
+ * it lists by name). false or absent: the symbol is a token list's or a
98
+ * stand-in, so the page also shows the denom (a lookalike symbol is
99
+ * then visible).
100
+ */
101
+ known?: boolean;
102
+ };
103
+ /** The recipient as the Hub checked it (EIP-55 or lower-case bech32). */
104
+ recipient: string;
105
+ /** The person's own address on `to.chain`: a move, not a send. */
106
+ recipientOwn: boolean;
107
+ /** The move's id once approved, else null. */
108
+ moveId: string | null;
109
+ };
52
110
  export type ActionOperationV1 =
53
111
  | P2Operation
54
112
  | ChainTxOperation
55
113
  | BidSubmitOperation
56
114
  | ClaimSubmitOperation
115
+ | WalletSendOperation
57
116
  | {
58
117
  kind: "form.submit.v1";
59
118
  formId: string;
@@ -122,7 +181,26 @@ export type ActionReceiptV1 =
122
181
  submittedAt: number;
123
182
  }
124
183
  | {
125
- /** 0.7.0: an application or claim submission that stopped before it finished. */
184
+ /** 0.10.0: a wallet send that arrived at the recipient. */
185
+ kind: "ixo.wallet.sent.v1";
186
+ actionId: string;
187
+ revision: number;
188
+ digest: string;
189
+ /** The Hub's move id (the person's wallet history). */
190
+ moveId: string;
191
+ toChain: string;
192
+ /** The denom that arrived. */
193
+ denom: string;
194
+ /** What arrived, base units of `denom`. */
195
+ amountBaseUnits: string;
196
+ recipient: string;
197
+ completedAt: number;
198
+ }
199
+ | {
200
+ /**
201
+ * 0.7.0: an application or claim submission that stopped before it
202
+ * finished (0.10.0: also a wallet send, step `send`).
203
+ */
126
204
  kind: "ixo.submission.failed.v1";
127
205
  actionId: string;
128
206
  revision: number;
@@ -250,6 +328,8 @@ export type ActionReviewView = {
250
328
  collectionName?: string | null;
251
329
  /** Private, owner-authenticated review only. Never part of the submitted claim. */
252
330
  surveyReview?: SurveyReview | null;
331
+ /** 0.10.0 (wallet send cards only): what leaves, what arrives, and where. */
332
+ walletSend?: WalletSendDisplay | null;
253
333
  };
254
334
  export type SurveyReview = {
255
335
  status: 'ready' | 'unavailable';
@@ -1667,7 +1747,9 @@ export type SubmissionFailureStep =
1667
1747
  | "key"
1668
1748
  | "bid_bot"
1669
1749
  | "claim_bot"
1670
- | "chain";
1750
+ | "chain"
1751
+ /** 0.10.0: a wallet send that did not start or did not reach the recipient. */
1752
+ | "send";
1671
1753
  export declare const SUBMISSION_FAILURE_STEPS: readonly SubmissionFailureStep[];
1672
1754
  /**
1673
1755
  * 0.7.0: how one answer is shown on the card: a string as it is; a number or
package/src/index.js CHANGED
@@ -11,6 +11,13 @@ const INT = /^(0|[1-9][0-9]*)$/;
11
11
  const FIELD = /^[a-z][a-z0-9_]{0,39}$/;
12
12
  /** 0.7.0 application and claim cards: an existing collection (never 0). */
13
13
  const SUBMISSION_COLLECTION_ID = /^[1-9][0-9]{0,19}$/;
14
+ /** 0.10.0 wallet send: the kind, and the shapes its receipt and view repeat. */
15
+ const WALLET_SEND_KIND = "ixo.wallet.send.v1";
16
+ const WALLET_CHAIN = /^[a-z0-9]{2,16}$/;
17
+ const WALLET_DENOM = /^[A-Za-z0-9][A-Za-z0-9/:._-]{1,255}$/;
18
+ const WALLET_RECIPIENT = /^[A-Za-z0-9]{10,128}$/;
19
+ const WALLET_AMOUNT = /^[1-9][0-9]{0,77}$/;
20
+ const WALLET_MOVE_ID = /^[A-Za-z0-9-]{1,64}$/;
14
21
  /** Envelope tags. v1 carries only the 0.1 status/receipt set; v2 adds terminal non-execution outcomes. */
15
22
  export const OUTCOME_VERSION_V1 = "ixo.auth-outcome/1";
16
23
  export const OUTCOME_VERSION_V2 = "ixo.auth-outcome/2";
@@ -250,6 +257,10 @@ export function parseOperation(input) {
250
257
  }
251
258
  return op;
252
259
  }
260
+ // 0.10.0: the schema checks every field (chains, denoms, the recipient's
261
+ // characters, the amount, the speed); the Hub checks the chains, tokens and
262
+ // recipient against its own lists, as it does for a send from the wallet.
263
+ if (op.kind === WALLET_SEND_KIND) return op;
253
264
  if (op.kind === "resource.read.v1") {
254
265
  exact(
255
266
  op,
@@ -459,9 +470,91 @@ export function parseReceipt(input) {
459
470
  num(receipt.failedAt, "receipt.failedAt");
460
471
  return receipt;
461
472
  }
473
+ if (receipt.kind === "ixo.wallet.sent.v1") {
474
+ exact(
475
+ receipt,
476
+ [
477
+ "kind",
478
+ "actionId",
479
+ "revision",
480
+ "digest",
481
+ "moveId",
482
+ "toChain",
483
+ "denom",
484
+ "amountBaseUnits",
485
+ "recipient",
486
+ "completedAt",
487
+ ],
488
+ "receipt",
489
+ );
490
+ tuple(receipt);
491
+ pattern(receipt.moveId, WALLET_MOVE_ID, "receipt.moveId");
492
+ pattern(receipt.toChain, WALLET_CHAIN, "receipt.toChain");
493
+ pattern(receipt.denom, WALLET_DENOM, "receipt.denom");
494
+ // What arrived at the recipient, base units of `denom`.
495
+ pattern(receipt.amountBaseUnits, WALLET_AMOUNT, "receipt.amountBaseUnits");
496
+ pattern(receipt.recipient, WALLET_RECIPIENT, "receipt.recipient");
497
+ num(receipt.completedAt, "receipt.completedAt");
498
+ return receipt;
499
+ }
462
500
  return fail("receipt.kind");
463
501
  }
464
502
 
503
+ /**
504
+ * 0.10.0: the Hub's display of a wallet send (the review page's words come
505
+ * from these fields, never from oracle text). It must describe exactly the
506
+ * operation: the same source token and amount, the same destination chain
507
+ * (the delivered denom may be the Hub's pinned form of `to.denom`) and the
508
+ * same recipient (the Hub's canonical spelling of it).
509
+ */
510
+ function parseWalletSendDisplay(input, op) {
511
+ const view = object(input, "view.walletSend");
512
+ exact(view, ["from", "to", "recipient", "recipientOwn", "moveId"], "view.walletSend");
513
+ const side = (value, field, keys) => {
514
+ const s = object(value, field);
515
+ exact(s, keys, field);
516
+ pattern(s.chain, WALLET_CHAIN, `${field}.chain`);
517
+ if (stripHiddenCharacters(str(s.chainName, `${field}.chainName`, 1, 60)) !== s.chainName)
518
+ fail(`${field}.chainName`);
519
+ pattern(s.denom, WALLET_DENOM, `${field}.denom`);
520
+ if (stripHiddenCharacters(str(s.symbol, `${field}.symbol`, 1, 40)) !== s.symbol)
521
+ fail(`${field}.symbol`);
522
+ if (!Number.isSafeInteger(s.decimals) || s.decimals < 0 || s.decimals > 36)
523
+ fail(`${field}.decimals`);
524
+ return s;
525
+ };
526
+ const from = side(view.from, "view.walletSend.from", [
527
+ "chain",
528
+ "chainName",
529
+ "denom",
530
+ "symbol",
531
+ "decimals",
532
+ "amountBaseUnits",
533
+ ]);
534
+ const to = side(view.to, "view.walletSend.to", [
535
+ "chain",
536
+ "chainName",
537
+ "denom",
538
+ "symbol",
539
+ "decimals",
540
+ "known",
541
+ ]);
542
+ if (to.known !== undefined && typeof to.known !== "boolean") fail("view.walletSend.to.known");
543
+ if (
544
+ from.chain !== op.from.chain ||
545
+ from.denom !== op.from.denom ||
546
+ from.amountBaseUnits !== op.amountBaseUnits
547
+ )
548
+ fail("view.walletSend.from");
549
+ if (to.chain !== op.to.chain) fail("view.walletSend.to");
550
+ pattern(view.recipient, WALLET_RECIPIENT, "view.walletSend.recipient");
551
+ if (view.recipient.toLowerCase() !== op.recipient.toLowerCase())
552
+ fail("view.walletSend.recipient");
553
+ if (typeof view.recipientOwn !== "boolean") fail("view.walletSend.recipientOwn");
554
+ if (view.moveId !== null) pattern(view.moveId, WALLET_MOVE_ID, "view.walletSend.moveId");
555
+ return view;
556
+ }
557
+
465
558
  export function isYouthSurveyClaim(operation) {
466
559
  return operation?.kind === 'ixo.claim.submit.v1' &&
467
560
  operation.network === 'ixo mainnet' && operation.collectionId === '13530';
@@ -492,11 +585,17 @@ export function parseReviewView(input) {
492
585
  "networkFee",
493
586
  "collectionName",
494
587
  "surveyReview",
588
+ "walletSend",
495
589
  ],
496
590
  "view",
497
591
  );
498
592
  parseReference(view.reference);
499
593
  parseOperation(view.operation);
594
+ // 0.10.0: the Hub-computed display of a wallet send (wallet send cards only).
595
+ if (view.walletSend !== undefined && view.walletSend !== null) {
596
+ if (view.operation?.kind !== WALLET_SEND_KIND) fail("view.walletSend");
597
+ parseWalletSendDisplay(view.walletSend, view.operation);
598
+ }
500
599
  if (view.surveyReview !== undefined && view.surveyReview !== null) {
501
600
  if (!isYouthSurveyClaim(view.operation)) fail('view.surveyReview');
502
601
  const review = object(view.surveyReview, 'view.surveyReview');
@@ -1032,10 +1131,13 @@ const receiptKinds = {
1032
1131
  "ixo.chain.tx.v1": "ixo.chain.tx.v1",
1033
1132
  "ixo.bid.submit.v1": "ixo.bid.submission.v1",
1034
1133
  "ixo.claim.submit.v1": "ixo.claim.submission.v1",
1134
+ "ixo.wallet.send.v1": "ixo.wallet.sent.v1",
1035
1135
  };
1036
1136
  /** 0.7.0: kinds whose failed outcome carries `ixo.submission.failed.v1`. */
1037
1137
  const SUBMISSION_KINDS = ["ixo.bid.submit.v1", "ixo.claim.submit.v1"];
1038
- /** 0.7.0: the step a bid or claim submission stopped at. */
1138
+ /** 0.10.0: every kind whose failed outcome carries `ixo.submission.failed.v1`. */
1139
+ const SUBMISSION_FAILED_KINDS = [...SUBMISSION_KINDS, WALLET_SEND_KIND];
1140
+ /** 0.7.0: the step a bid or claim submission stopped at (0.10.0: `send`). */
1039
1141
  export const SUBMISSION_FAILURE_STEPS = [
1040
1142
  "collection",
1041
1143
  "evidence",
@@ -1043,6 +1145,7 @@ export const SUBMISSION_FAILURE_STEPS = [
1043
1145
  "bid_bot",
1044
1146
  "claim_bot",
1045
1147
  "chain",
1148
+ "send",
1046
1149
  ];
1047
1150
  /**
1048
1151
  * 0.7.0: a claim card's network fee as read when the card was made: a
@@ -1178,7 +1281,7 @@ export function assertReceiptForOperation(
1178
1281
  if (
1179
1282
  status === "failed" &&
1180
1283
  receipt.kind === "ixo.submission.failed.v1" &&
1181
- SUBMISSION_KINDS.includes(operation.kind)
1284
+ SUBMISSION_FAILED_KINDS.includes(operation.kind)
1182
1285
  )
1183
1286
  return receipt;
1184
1287
  if (
@@ -1202,6 +1305,14 @@ export function assertReceiptForOperation(
1202
1305
  receipt.collectionId !== operation.collectionId
1203
1306
  )
1204
1307
  fail("receipt collection");
1308
+ // 0.10.0: a wallet send's receipt names the approved destination chain and
1309
+ // recipient (the Hub's canonical spelling: EIP-55 or lower-case bech32).
1310
+ if (
1311
+ operation.kind === WALLET_SEND_KIND &&
1312
+ (receipt.toChain !== operation.to.chain ||
1313
+ receipt.recipient.toLowerCase() !== operation.recipient.toLowerCase())
1314
+ )
1315
+ fail("receipt recipient");
1205
1316
  // Every kind: the receipt must name the approved connection / target.
1206
1317
  if (
1207
1318
  "connectionId" in operation &&
@@ -68,6 +68,16 @@ const evidence = object({
68
68
  size: integer(1, 52428800),
69
69
  sha256: hex,
70
70
  });
71
+ // 0.10.0 wallet send: a token on one of the Hub's move chains (a chain key
72
+ // such as "base" or "ixo", and the chain's own denom: a bank denom or a 0x
73
+ // token contract), and the receiving address (only its characters here; the
74
+ // Hub checks it for the destination chain).
75
+ const walletToken = object({
76
+ chain: { ...string(2, 16), pattern: "^[a-z0-9]{2,16}$" },
77
+ denom: { ...string(2, 256), pattern: "^[A-Za-z0-9][A-Za-z0-9/:._-]{1,255}$" },
78
+ });
79
+ const walletRecipient = { ...string(10, 128), pattern: "^[A-Za-z0-9]{10,128}$" };
80
+ const walletAmount = { ...string(1, 78), pattern: "^[1-9][0-9]{0,77}$" };
71
81
  // One ASCII mailbox only; no display names, address lists or header characters.
72
82
  const mailbox = {
73
83
  ...string(3, 254),
@@ -638,6 +648,17 @@ const registry = {
638
648
  data: string(2, 60000),
639
649
  evidence: { type: "array", items: evidence, maxItems: 30 },
640
650
  },
651
+ // 0.10.0: send a token from the person's wallet to another address,
652
+ // optionally as another token on another chain. No free text: the card's
653
+ // words are the Hub's own. `speed` null = the person picks on the page.
654
+ "ixo.wallet.send.v1": {
655
+ network,
656
+ from: walletToken,
657
+ to: walletToken,
658
+ recipient: walletRecipient,
659
+ amountBaseUnits: walletAmount,
660
+ speed: nullable(enumeration("standard", "fast")),
661
+ },
641
662
  };
642
663
  export const operationKinds = Object.freeze(Object.keys(registry));
643
664
  export const operationJsonSchema = Object.freeze({