@ixo/action-protocol 0.5.0 → 0.7.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,98 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.7.0
4
+
5
+ Two operation kinds for reviewed submissions the person makes on a claim
6
+ collection. Both are approved with `/decision` (no separate sign step); the Hub
7
+ signs with the keys it holds for the person.
8
+
9
+ - `ixo.bid.submit.v1`: send an application (`role: "SA"`) to the collection's
10
+ bids bot. `data` is the JSON object of the `#bco` SurveyJS answers;
11
+ `summary` is what the card shows: 0-100 `{field, label, value}` rows, one
12
+ per answer of `data` (`submissionSummaryIssue`, `submissionDisplayValue`:
13
+ the parser refuses a card that does not show exactly its data). Receipt
14
+ `ixo.bid.submission.v1` (`collectionId`, `bidId` or null, `submittedAt`).
15
+ - `ixo.claim.submit.v1`: submit a claim. `data` is the JSON object of the
16
+ `#vct` answers without file questions; `evidence` (0-30) lists files the
17
+ channel gateway holds (`field`, https `url`, `filename`, `mimetype`, `size`,
18
+ lowercase `sha256`), which the Hub uploads to the collection's VFS claims
19
+ lane and places at `field`. Receipt `ixo.claim.submission.v1`
20
+ (`collectionId`, `claimId`, lowercase `transactionHash`, `height` of the
21
+ block that included it, `submittedAt`).
22
+ - `ixo.submission.failed.v1`: the receipt of a failed application or claim
23
+ submission (`step`: collection, evidence, key, bid_bot, claim_bot or chain;
24
+ `message`; optional `detail`; `failedAt`). v2 envelopes only. `message` is
25
+ plain words the Hub chose from the step and a known cause, always with a
26
+ next step: the only text a gateway or runtime may show or relay. `detail`
27
+ is optional technical text (what a service or the network said) for the
28
+ review page's closed disclosure; never relay it. Both are at most 500 and
29
+ must already be in `sanitizeSubmissionText` form (no control, zero-width or
30
+ bidi characters, nothing link-like, collapsed whitespace), or the parser
31
+ refuses them.
32
+ - `sanitizeSubmissionText(text)`, `SUBMISSION_TEXT_MAX`: the sanitizer the
33
+ parser checks against (idempotent). It looks at the first 2000 characters
34
+ only and its expressions are bounded, so no input makes it slow; unpaired
35
+ surrogates are dropped and the result is always a fixed point.
36
+ - Review view `collectionName` (application and claim cards): the
37
+ collection's name as the Hub read it when the card was made, or null.
38
+ - Review view `networkFee` (claim cards only): `covered` (a usable fee grant
39
+ allows the claim's MsgExec) or `balance` (the person's IXO pays it, also
40
+ when the grants could not be read). `SUBMISSION_NETWORK_FEES`.
41
+ - The Hub offers and accepts these kinds only from callers that declare
42
+ `?version=5` (wire level 5 = level 4 + these cards; a 0.6.0 parser
43
+ rejects an unknown kind).
44
+
45
+ ## 0.6.0
46
+
47
+ One card kind for every chain transaction: `ixo.chain.tx.v1`. Every existing
48
+ shape is unchanged. The Hub shows it only to callers that declare
49
+ `?version=4` (wire level 4 = level 3 + chain transactions; the envelope tags
50
+ stay `ixo.auth-capabilities/2` / `ixo.auth-outcome/2`), because released
51
+ 0.5.0 runtimes already declare `?version=3` and parse with exact-key parsers.
52
+
53
+ - Operation `ixo.chain.tx.v1`: `chainId`, `network`, `signer`, `memo`
54
+ (0..256 UTF-8 bytes) and `messages` (1..8, one transaction, all or
55
+ nothing). Message types (`CHAIN_TX_MESSAGE_TYPES`): `cosmos.bank.send`,
56
+ `ixo.claims.submit`, `ixo.claims.evaluate` (status 1..4), and
57
+ `ixo.token.transfer` (IXO impact tokens, 1..32 token lines).
58
+ - `chainTxIssue(operation)`: the first malformed field as the Hub's 400
59
+ `reason` (`invalid_message: messages[1].toAddress`, 0-based index, or
60
+ `invalid_operation: memo`), or null. `parseOperation` throws
61
+ `Invalid messages[1].toAddress` for the same field.
62
+ - Review view `chainTx` (`ChainTxDisplay`, `parseChainTxDisplay`): the
63
+ Hub-computed steps (title, one sentence, facts, risk, cannotUndo, the
64
+ bank-send `TransferDisplay` for bank steps), overall `riskLevel`,
65
+ `confirmTwice` (high or critical), consent text, fee, signer and `wrapped`.
66
+ It must match the operation's signer and message types in order.
67
+ - Receipt `ixo.chain.tx.v1`: chain id, tx hash, height, code, `steps` (the
68
+ message types in order), and on failure a `reason`
69
+ (`CHAIN_TX_FAILURE_REASONS`: `check_tx_rejected`, `expired_not_included`,
70
+ or `tx_failed` = included with code != 0) with an optional plain
71
+ `message` (at most 240). Never in a `/1` outcome envelope.
72
+ - Capabilities `chainTx` (`parseChainTxCapabilities`):
73
+ `{messageTypes, maxMessages}`, present exactly when `operations` lists
74
+ `ixo.chain.tx.v1`; absent (or null) otherwise.
75
+ - The operation JSON schema supports `integer` (used by the evaluation
76
+ `reason`, a uint32 the evaluator defines).
77
+ - Validation is stricter than the first 0.6.0 draft (`chainTxIssue`,
78
+ `parseOperation`): claim ids and token ids must match
79
+ `^[A-Za-z0-9:._/-]+$`; every address must decode to a 20-byte account;
80
+ a DID's `%` must start a valid `%xx` escape; the memo refuses control
81
+ characters; `verificationProof` is at most 300 characters (was 512), so
82
+ the review display can show it whole.
83
+ - No caps: chain transactions have no per-message capability rows, no
84
+ per-message enablement and no amount caps (product decision); the kind is
85
+ on by default and an operator can only disable it as a whole.
86
+ `/transfer-limits` stay for `ixo.bank.send.v1`.
87
+ - Retirement plan for `ixo.bank.send.v1` (not in this release): unchanged
88
+ until `cosmos.bank.send` in a chain tx card is proven live on every
89
+ network; then runtimes stop creating it, the Hub serves existing rows until
90
+ they are terminal and past retention, and the kind is removed in a major
91
+ version.
92
+ - Rollout order: Hub, then gateways on 0.6.0 (a pre-0.6.0 strict parser
93
+ fails its confirmation reads of chain-tx receipts), then runtimes on
94
+ `?version=4`.
95
+
3
96
  ## 0.5.0
4
97
 
5
98
  Everything in the P1 0.3.0 entry below (shipped on the stacked P1 branch), on
@@ -23,7 +116,8 @@ top of 0.4.1, plus:
23
116
 
24
117
  ## 0.3.0
25
118
 
26
- All additions are optional or v2-only; v1 envelopes are unchanged.
119
+ All additions are optional. The Hub only emits them to callers that declare
120
+ `?version=3`; v1 and v2 callers keep the 0.4.1 shapes.
27
121
 
28
122
  - Bank send `denom`: any Cosmos denom matching `DENOM`; absent means `uixo`
29
123
  (the parser fills it in).
package/README.md CHANGED
@@ -15,7 +15,46 @@ Callers declare the envelope version they parse with `?version=2` on
15
15
 
16
16
  - v1 (`ixo.auth-outcome/1`, `ixo.auth-capabilities/1`): the 0.1.0 status set
17
17
  and the 0.4.1 receipt shape, exactly. Fields added later never appear in v1.
18
- - v2 (`ixo.auth-outcome/2`, `ixo.auth-capabilities/2`): every current field.
18
+ - v2 (`ixo.auth-outcome/2`, `ixo.auth-capabilities/2`): the 0.4.1 shapes, exactly.
19
+ - `?version=3` (0.5.0): the same `/2` tags with every current field (bank
20
+ receipt `denom`/`amountBaseUnits`, capability `transfer.limits`, any-denom
21
+ sends). Declare it to receive them; v1/v2 callers never do.
22
+ - `?version=4` (0.6.0): level 3 plus chain transactions (`ixo.chain.tx.v1`
23
+ in capabilities, the `chainTx` capability key, and the right to create the
24
+ kind). Callers below 4 never see the kind, and a `POST` of it answers
25
+ `400 protocol_version_required`.
26
+
27
+ - `?version=5` (0.7.0): level 4 plus the application and claim cards
28
+ (`ixo.bid.submit.v1`, `ixo.claim.submit.v1`) and their receipts. Callers
29
+ below 5 never see the kinds and get `400 protocol_version_required` for
30
+ them.
31
+
32
+ ## Applications and claims (`ixo.bid.submit.v1`, `ixo.claim.submit.v1`, 0.7.0)
33
+
34
+ - `summary`: one row per answer of `data`, `{field, label, value}`. `field`
35
+ is the answer's path (object keys and array indices joined with `.`, e.g.
36
+ `shops.1.name`); `value` is exactly `submissionDisplayValue(answer)`: a
37
+ string as it is, a number or boolean as `String(value)`, `null` as `""`,
38
+ an array of strings, numbers and booleans joined with `", "`. The answers
39
+ are the leaves of `data` (objects and arrays of objects are walked, not
40
+ shown); every answer needs exactly one row, no row may name anything
41
+ else, keys may not be empty or contain `.`, and a claim's evidence `field`
42
+ must not already hold an answer. `parseOperation` refuses any other card;
43
+ `submissionSummaryIssue(op)` names the first problem.
44
+ - Approved with `/decision` and `declaration: true`; the Hub runs the steps as the person and may
45
+ finish after the approve response (`submitted` first, then `succeeded` or
46
+ `failed`; a claim's transaction can also be `unknown` until it is seen).
47
+ - Receipts: `ixo.bid.submission.v1` (`collectionId`, `bidId` or null,
48
+ `submittedAt`); `ixo.claim.submission.v1` (`collectionId`, `claimId`,
49
+ lowercase `transactionHash`, `height`, `submittedAt`).
50
+ - Failure: `ixo.submission.failed.v1` with `step`, `message`, optional
51
+ `detail`, `failedAt`. Show or relay **`message` only**: it is the Hub's own
52
+ plain sentence and always says what to do next. `detail` is technical text
53
+ for the review page's "Show technical details"; never show it in a chat.
54
+ Both are sanitized (`sanitizeSubmissionText`) and the parser refuses any
55
+ other form.
56
+ - A claim card's review view carries `networkFee`: `covered` or `balance`
57
+ (who pays the network fee; no amount).
19
58
 
20
59
  ## Bank send (`ixo.bank.send.v1`)
21
60
 
@@ -32,7 +71,86 @@ Callers declare the envelope version they parse with `?version=2` on
32
71
  factory/cw20 token can call it "USDC"): `decimals` is 0, `amountDisplay` is
33
72
  base units, and the UI must show the full denom and an "unverified token"
34
73
  marker. Show the full denom for anything that is not `uixo`.
35
- - v2 bank receipts carry `denom` and `amountBaseUnits`.
74
+ - Bank receipts carry `denom` and `amountBaseUnits` for `?version=3` callers.
75
+
76
+ ## Chain transactions (`ixo.chain.tx.v1`)
77
+
78
+ One card kind for every chain transaction. The person sees every step in
79
+ plain words, ticks a box, and signs once; the steps run as one transaction
80
+ (all succeed or none do).
81
+
82
+ ```ts
83
+ {
84
+ kind: "ixo.chain.tx.v1",
85
+ chainId: string, // the Hub's chain
86
+ network: "ixo mainnet" | "ixo testnet" | "ixo devnet", // the Hub's network
87
+ signer: string, // the person's Hub wallet address
88
+ memo: string, // 0..256 UTF-8 bytes
89
+ messages: ChainTxMessage[], // 1..8
90
+ }
91
+ ```
92
+
93
+ | `type` | Fields | What it does |
94
+ | --- | --- | --- |
95
+ | `cosmos.bank.send` | `toAddress`, `amountBaseUnits`, `denom?` (absent = `uixo`) | Sends coins from the person's wallet. |
96
+ | `ixo.claims.submit` | `collectionId`, `claimId`, `agentDid`, `adminAddress`, `useIntent?` | Files an existing claim with a collection. The chain `agentAddress` is the signer; the Hub requires `agentDid` to be `did:ixo:<signer>`. |
97
+ | `ixo.claims.evaluate` | `claimId`, `collectionId`, `oracle`, `agentDid`, `agentAddress`, `adminAddress`, `status` (1 approve, 2 reject, 3 dispute, 4 invalidate), `reason?` (uint32), `verificationProof?` (≤ 300) | Records the signer's decision on someone else's claim. `agentDid`/`agentAddress` are the evaluator's (the signer; the Hub requires `agentAddress === signer`), not the claimant's; `oracle` is the evaluator DID recorded on the evaluation. An approval can pay the claimant. |
98
+ | `ixo.token.transfer` | `recipient`, `tokens: [{id, amount}]` (1..32) | Moves IXO impact tokens (1155-style), not IXO coins. The chain `owner` is the signer. |
99
+
100
+ - Authorization: the Hub wraps each claims message in
101
+ `/cosmos.authz.v1beta1.MsgExec {grantee: signer, msgs: [inner]}` (one
102
+ MsgExec per claims message), because submit and evaluate run under the
103
+ collection admin's authorization. Bank and token messages are signed
104
+ directly.
105
+ - Validation: `chainTxIssue(operation)` names the first bad field the way
106
+ the Hub's `400 operation_not_registered` `reason` does
107
+ (`invalid_message: messages[1].toAddress`, 0-based index). Validate with
108
+ it before calling the Hub; the Hub also checks the signer, network, chain
109
+ and bech32 checksums. Claim and token ids use only
110
+ `^[A-Za-z0-9:._/-]+$` (impact token ids on chain are 32-hex strings, and
111
+ 1155 amounts have no decimals).
112
+ - Review view `chainTx` (`ChainTxDisplay`): the Hub's plain words, the only
113
+ step text a page renders. `steps[]` each have a `title`, one-sentence
114
+ `whatItDoes`, `facts` (`technical` facts go behind a disclosure),
115
+ `riskLevel`, `cannotUndo`, and for bank steps the bank-send `transfer`
116
+ display (same verified/unverified rules). Titles and sentences never carry
117
+ a hash, denom or address ("Transfer 3 impact tokens", "Sends 1.5 IXO from
118
+ your wallet to the address below."). The memo is not a step fact: the page
119
+ shows the operation's `memo` once, as "Note", after the steps.
120
+ `confirmTwice` is true for high/critical: the page asks a second time
121
+ before signing. `consent` is the checkbox text.
122
+ - Unhappy paths (what the oracle and the person see):
123
+ 1. The message does not look right: `400 operation_not_registered` with a
124
+ `reason` naming the field (`chainTxIssue` gives the same), no card.
125
+ 2. The Hub cannot prepare it: `400 insufficient_funds`,
126
+ `400 not_authorized`, `400 fee_above_ceiling`, `400 simulation_failed`
127
+ (with a fixed `reason` phrase when known), `409 sequence_mismatch`,
128
+ `503 transfer_unavailable`; no card. At sign time the Hub can still
129
+ refuse with `409 fee_grant_changed` (the fee is no longer covered),
130
+ `409 insufficient_funds` (the wallet no longer covers it) or
131
+ `409 review_changed`; nothing is sent and the person is asked to get a
132
+ new link.
133
+ 3. The transaction failed: a `failed` receipt with `reason`
134
+ `check_tx_rejected` (never included, no fee), `tx_failed` (included with
135
+ an error: nothing in it happened, but the network fee was used) or
136
+ `expired_not_included` (never included), plus a plain `message` for the
137
+ first two.
138
+ - Receipt `ixo.chain.tx.v1`: `chainId`, `txHash`, `height`, `code`, `steps`
139
+ (`[{type}]` in order). A `failed` receipt always has a `reason`:
140
+ `check_tx_rejected` (never included; CheckTx code), `expired_not_included`
141
+ (never included; code null) or `tx_failed` (included with code != 0), and
142
+ may carry a plain `message` (≤ 240) to show the person.
143
+ - Capabilities (`?version=4`):
144
+ `chainTx: {messageTypes, maxMessages}` when the kind is listed. There are
145
+ no per-message caps and no per-message enablement.
146
+ - Retiring `ixo.bank.send.v1`: it stays unchanged until `cosmos.bank.send`
147
+ in this card is proven live on every network. Then runtimes stop creating
148
+ bank-send cards (a one-step chain tx replaces them), the Hub keeps serving
149
+ existing bank-send rows until they are terminal and past retention, and
150
+ only then is the kind removed, in a major version.
151
+ - Rollout: Hub first, then gateways on 0.6.0 (a pre-0.6.0 strict parser
152
+ fails its confirmation reads of chain-tx receipts), then runtimes on
153
+ `?version=4`.
36
154
 
37
155
  ## Options
38
156
 
@@ -45,8 +163,8 @@ unchanged, so 0.4.1 parsers keep working on V2.
45
163
  ## Capabilities
46
164
 
47
165
  `transfer` is either `{limits: [{denom, maxAmountBaseUnits}], maxFeeUixo?}`
48
- (v2; an empty `limits` means no caps) or the legacy
49
- `{maxAmountUixo, maxFeeUixo}` (v1).
166
+ (`?version=3`; an empty `limits` means no caps) or the legacy
167
+ `{maxAmountUixo, maxFeeUixo}` (v1/v2).
50
168
 
51
169
  ## Signed outcome callbacks
52
170
 
@@ -91,6 +209,10 @@ if (!ok) return new Response("unauthorized", { status: 401 });
91
209
  const outcome = parseOutcome(JSON.parse(rawBody));
92
210
  ```
93
211
 
212
+ During the transition the Hub also sends the deprecated per-account
213
+ `x-auth-hub-outcome-key` to accounts that still have one registered; it will
214
+ be removed once every oracle verifies the signature.
215
+
94
216
  Uses WebCrypto Ed25519 only (Node 20+, Cloudflare Workers, modern browsers).
95
217
 
96
218
  ## Tests
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ixo/action-protocol",
3
- "version": "0.5.0",
3
+ "version": "0.7.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
@@ -6,8 +6,54 @@ export type FormField = {
6
6
  value: string;
7
7
  source: "user" | "record" | "suggestion";
8
8
  };
9
+ /**
10
+ * 0.7.0: one row an application or claim card shows: one answer of `data`.
11
+ * `field` is the answer's path in `data` (a key, or a dot path into objects
12
+ * and dynamic panels, e.g. "shops.3.name"); `value` must be exactly
13
+ * `submissionDisplayValue` of the answer there. Every answer of `data` has
14
+ * exactly one row (see `submissionSummaryIssue`).
15
+ */
16
+ export type SubmissionSummaryRow = { field: string; label: string; value: string };
17
+ /** 0.7.0: a file the person sent on the channel, uploaded by the Hub as claim evidence. */
18
+ export type ClaimEvidence = {
19
+ /** SurveyJS question name (a dot path for panel items, e.g. "shops.3.photo"). */
20
+ field: string;
21
+ /** https link the gateway serves the bytes from. */
22
+ url: string;
23
+ filename: string;
24
+ mimetype: string;
25
+ size: number;
26
+ /** Lowercase hex SHA-256 of the bytes. */
27
+ sha256: string;
28
+ };
29
+ export type SubmissionNetwork = "ixo mainnet" | "ixo testnet" | "ixo devnet";
30
+ /** 0.7.0: send an application (the collection's #bco answers) to the bids bot as the person. */
31
+ export type BidSubmitOperation = {
32
+ kind: "ixo.bid.submit.v1";
33
+ network: SubmissionNetwork;
34
+ collectionId: string;
35
+ title: string;
36
+ role: "SA";
37
+ summary: SubmissionSummaryRow[];
38
+ /** JSON object: the SurveyJS answers. */
39
+ data: string;
40
+ };
41
+ /** 0.7.0: submit a claim (the collection's #vct answers plus evidence) as the person. */
42
+ export type ClaimSubmitOperation = {
43
+ kind: "ixo.claim.submit.v1";
44
+ network: SubmissionNetwork;
45
+ collectionId: string;
46
+ title: string;
47
+ summary: SubmissionSummaryRow[];
48
+ /** JSON object: the SurveyJS answers, file questions left out. */
49
+ data: string;
50
+ evidence: ClaimEvidence[];
51
+ };
9
52
  export type ActionOperationV1 =
10
53
  | P2Operation
54
+ | ChainTxOperation
55
+ | BidSubmitOperation
56
+ | ClaimSubmitOperation
11
57
  | {
12
58
  kind: "form.submit.v1";
13
59
  formId: string;
@@ -50,6 +96,53 @@ export type ActionReferenceV1 = {
50
96
  };
51
97
  export type ActionReceiptV1 =
52
98
  | P2Receipt
99
+ | ChainTxReceipt
100
+ | {
101
+ kind: "ixo.bid.submission.v1";
102
+ actionId: string;
103
+ revision: number;
104
+ digest: string;
105
+ collectionId: string;
106
+ /** The bids bot's id for the bid, when it gave one. */
107
+ bidId: string | null;
108
+ submittedAt: number;
109
+ }
110
+ | {
111
+ kind: "ixo.claim.submission.v1";
112
+ actionId: string;
113
+ revision: number;
114
+ digest: string;
115
+ collectionId: string;
116
+ /** The claim's CID from the claims bot. */
117
+ claimId: string;
118
+ /** Lowercase hex: the MsgExec(MsgSubmitClaim) transaction. */
119
+ transactionHash: string;
120
+ /** The block that transaction was included in. */
121
+ height: number;
122
+ submittedAt: number;
123
+ }
124
+ | {
125
+ /** 0.7.0: an application or claim submission that stopped before it finished. */
126
+ kind: "ixo.submission.failed.v1";
127
+ actionId: string;
128
+ revision: number;
129
+ digest: string;
130
+ step: SubmissionFailureStep;
131
+ /**
132
+ * Plain words the Hub chose from the step and a known cause, always with
133
+ * a next step (at most 500, sanitized). The only text a gateway or
134
+ * runtime may show or relay.
135
+ */
136
+ message: string;
137
+ /**
138
+ * Optional technical text (a service's or the network's answer),
139
+ * sanitized: no control, zero-width or bidi characters, nothing
140
+ * link-like, whitespace collapsed, at most 500. For the review page's
141
+ * closed "technical details" disclosure only; never relay it.
142
+ */
143
+ detail?: string;
144
+ failedAt: number;
145
+ }
53
146
  | {
54
147
  kind: "form.submission.v1";
55
148
  actionId: string;
@@ -139,6 +232,22 @@ export type ActionReviewView = {
139
232
  } | null;
140
233
  /** 0.3.0: Hub-computed transfer display (bank sends only). */
141
234
  transfer?: TransferDisplay | null;
235
+ /** 0.6.0: Hub-computed chain transaction display (chain tx cards only). */
236
+ chainTx?: ChainTxDisplay | null;
237
+ /**
238
+ * 0.7.0 (claim cards only): who pays the claim's network fee, read once
239
+ * when the card was made (no amount: the transaction is built later).
240
+ * `covered`: a usable fee grant allows it; `balance`: the person's IXO
241
+ * pays it (also when the grants could not be read).
242
+ */
243
+ networkFee?: SubmissionNetworkFee | null;
244
+ /**
245
+ * 0.7.0 (application and claim cards): the collection's readable name
246
+ * (its protocol entity's Profile `name`, sanitized, at most 120) as the Hub
247
+ * read it when the card was made; null when none could be read. Show it
248
+ * with `operation.collectionId`.
249
+ */
250
+ collectionName?: string | null;
142
251
  };
143
252
  export type TransferDisplay = {
144
253
  denom: string;
@@ -180,7 +289,192 @@ export type ActionCapabilitiesV1 = {
180
289
  maxFeeUixo?: string;
181
290
  }
182
291
  | null;
292
+ /**
293
+ * 0.6.0 (`?version=4` only): present (an object) exactly when `operations`
294
+ * lists `ixo.chain.tx.v1`; absent or null otherwise.
295
+ */
296
+ chainTx?: ChainTxCapabilities | null;
297
+ };
298
+
299
+ /** 0.6.0: one card kind for every chain transaction. */
300
+ export type ChainTxMessageType =
301
+ | "cosmos.bank.send"
302
+ | "ixo.claims.submit"
303
+ | "ixo.claims.evaluate"
304
+ | "ixo.token.transfer";
305
+ /**
306
+ * Field rules (`chainTxIssue` names the first bad field):
307
+ * - addresses: a 20-byte ixo account address, `ixo1` + 38 bech32 characters
308
+ * (the Hub also checks the checksum);
309
+ * - DIDs: `did:<method>:` then segments of [A-Za-z0-9._-] or `%` + two hex
310
+ * digits, joined by ':' (the chain's x/iid rule; `agentDid` is `did:ixo:`);
311
+ * - claim ids, token ids and verification proofs: ^[A-Za-z0-9:._/-]+$;
312
+ * - collectionId: a uint64 without leading zeros.
313
+ */
314
+ export type ChainTxMessage =
315
+ | {
316
+ type: "cosmos.bank.send";
317
+ toAddress: string;
318
+ /** ^[1-9][0-9]*$ */
319
+ amountBaseUnits: string;
320
+ /** Same rule as bank.send (`DENOM`); absent = uixo. */
321
+ denom?: string;
322
+ }
323
+ | {
324
+ type: "ixo.claims.submit";
325
+ /** ^(0|[1-9][0-9]{0,19})$, ≤ 18446744073709551615 */
326
+ collectionId: string;
327
+ /** 1..256, ^[A-Za-z0-9:._/-]+$ */
328
+ claimId: string;
329
+ /**
330
+ * did:ixo:… The person filing: the Hub requires it to be the signer's
331
+ * own DID (the chain records it as attribution only and does not check
332
+ * it against the signer), else `400 operation_not_registered`,
333
+ * `reason: 'invalid_message: messages[i].agentDid'`.
334
+ */
335
+ agentDid: string;
336
+ adminAddress: string;
337
+ useIntent?: boolean;
338
+ }
339
+ | {
340
+ type: "ixo.claims.evaluate";
341
+ /** 1..256, ^[A-Za-z0-9:._/-]+$ */
342
+ claimId: string;
343
+ /** ^(0|[1-9][0-9]{0,19})$, ≤ 18446744073709551615 */
344
+ collectionId: string;
345
+ /** The evaluator DID recorded on the evaluation. */
346
+ oracle: string;
347
+ /**
348
+ * The EVALUATOR (the signer), not the claimant. The Hub requires
349
+ * `agentDid` to be the signer's own DID and `agentAddress` to equal
350
+ * `signer` (`invalid_message: messages[i].agentDid` / `.agentAddress`).
351
+ */
352
+ agentDid: string;
353
+ agentAddress: string;
354
+ adminAddress: string;
355
+ /** EvaluationStatus: 1 approved, 2 rejected, 3 disputed, 4 invalidated (0 pending, 5 flagged refused). */
356
+ status: 1 | 2 | 3 | 4;
357
+ /** uint32 code defined by the evaluator (the chain has no enum for it). */
358
+ reason?: number;
359
+ /** '' or 1..300 of ^[A-Za-z0-9:._/-]+$ (shown whole on the review). */
360
+ verificationProof?: string;
361
+ }
362
+ | {
363
+ type: "ixo.token.transfer";
364
+ recipient: string;
365
+ /** 1..32 lines; id 1..128 of ^[A-Za-z0-9:._/-]+$, amount ^[1-9][0-9]*$ */
366
+ tokens: Array<{ id: string; amount: string }>;
367
+ };
368
+ export type ChainTxOperation = {
369
+ kind: "ixo.chain.tx.v1";
370
+ /** Must equal the Hub RPC's chain id at prepare. */
371
+ chainId: string;
372
+ /** Must equal the Hub's `ixo ${CHAIN_NETWORK}`. */
373
+ network: "ixo mainnet" | "ixo testnet" | "ixo devnet";
374
+ /** 20-byte bech32 ixo address; must equal the person's Hub wallet address. */
375
+ signer: string;
376
+ /**
377
+ * 0..256 UTF-8 bytes, may be ''. No C0/C1 controls (so no newlines),
378
+ * zero-width, bidi or line/paragraph separator characters, no BOM.
379
+ */
380
+ memo: string;
381
+ /** 1..8, executed as ONE transaction (all or nothing). */
382
+ messages: ChainTxMessage[];
183
383
  };
384
+ export type ChainTxRiskLevel = "low" | "medium" | "high" | "critical";
385
+ export type ChainTxFact = { label: string; value: string; technical?: boolean };
386
+ export type ChainTxStep = {
387
+ /** 1-based */
388
+ index: number;
389
+ type: ChainTxMessageType;
390
+ /** ≤ 60, plain words. */
391
+ title: string;
392
+ /** One sentence, ≤ 160. */
393
+ whatItDoes: string;
394
+ /** `technical` facts go behind "Show technical details". */
395
+ facts: ChainTxFact[];
396
+ riskLevel: ChainTxRiskLevel;
397
+ cannotUndo: boolean;
398
+ /** cosmos.bank.send steps: the bank-send display (verified/unverified token rules). */
399
+ transfer?: TransferDisplay;
400
+ };
401
+ export type ChainTxDisplay = {
402
+ /** The highest step risk. */
403
+ riskLevel: ChainTxRiskLevel;
404
+ /** riskLevel is high or critical. */
405
+ confirmTwice: boolean;
406
+ steps: ChainTxStep[];
407
+ /** The checkbox text, ≤ 160. */
408
+ consent: string;
409
+ feeBaseUnits: string;
410
+ feeDenom: "uixo";
411
+ feeDisplay: string;
412
+ gasLimit: number;
413
+ feeGranter: string | null;
414
+ signer: string;
415
+ /** true when any step is wrapped in MsgExec. */
416
+ wrapped: boolean;
417
+ };
418
+ export type ChainTxFailureReason =
419
+ | "check_tx_rejected"
420
+ | "expired_not_included"
421
+ | "tx_failed";
422
+ export type ChainTxReceipt = {
423
+ kind: "ixo.chain.tx.v1";
424
+ actionId: string;
425
+ revision: number;
426
+ digest: string;
427
+ chainId: string;
428
+ txHash: string;
429
+ height: number | null;
430
+ /** Chain result code (0 = success) once included. */
431
+ code: number | null;
432
+ /**
433
+ * `check_tx_rejected`: never included, CheckTx `code` ≠ 0, height null;
434
+ * `expired_not_included`: never included, code null, height null;
435
+ * `tx_failed`: included (height set) with code ≠ 0.
436
+ */
437
+ reason?: ChainTxFailureReason;
438
+ /** ≤ 240, plain words for the person; only with a `reason`. */
439
+ message?: string;
440
+ /** The approved messages' types, in order. */
441
+ steps: Array<{ type: ChainTxMessageType }>;
442
+ };
443
+ export type ChainTxCapabilities = {
444
+ messageTypes: ChainTxMessageType[];
445
+ maxMessages: number;
446
+ };
447
+ export declare const CHAIN_TX_KIND: "ixo.chain.tx.v1";
448
+ export declare const CHAIN_TX_MESSAGE_TYPES: readonly [
449
+ "cosmos.bank.send",
450
+ "ixo.claims.submit",
451
+ "ixo.claims.evaluate",
452
+ "ixo.token.transfer",
453
+ ];
454
+ export declare const CHAIN_TX_MAX_MESSAGES: 8;
455
+ export declare const CHAIN_TX_MAX_TOKEN_LINES: 32;
456
+ export declare const CHAIN_TX_FAILURE_REASONS: readonly [
457
+ "check_tx_rejected",
458
+ "expired_not_included",
459
+ "tx_failed",
460
+ ];
461
+ export declare const CHAIN_TX_RISK_LEVELS: readonly [
462
+ "low",
463
+ "medium",
464
+ "high",
465
+ "critical",
466
+ ];
467
+ export declare const CHAIN_TX_EVALUATION_STATUSES: readonly [1, 2, 3, 4];
468
+ /**
469
+ * Why a proposed chain tx operation is malformed, as the Hub's 400 `reason`
470
+ * (`invalid_message: messages[1].toAddress`, 0-based; `invalid_operation: memo`),
471
+ * or null when it parses.
472
+ */
473
+ export declare function chainTxIssue(input: unknown): string | null;
474
+ export declare function parseChainTxDisplay(input: unknown): ChainTxDisplay;
475
+ export declare function parseChainTxCapabilities(
476
+ input: unknown,
477
+ ): ChainTxCapabilities;
184
478
  export declare function canonicalJson(value: unknown): string;
185
479
  export declare function digestOf(value: unknown): Promise<string>;
186
480
  export declare function parseOperation(value: unknown): ActionOperationV1;
@@ -557,3 +851,45 @@ export declare function publicKeyFromDidDocument(
557
851
  ): Uint8Array;
558
852
  /** The exact 0.1.0 receipt shape for v1 callers (drops the 0.3.0 bank fields). */
559
853
  export declare function v1Receipt<T extends ActionReceiptV1 | null>(receipt: T): T;
854
+
855
+ /** 0.7.0 */
856
+ export type SubmissionFailureStep =
857
+ | "collection"
858
+ | "evidence"
859
+ | "key"
860
+ | "bid_bot"
861
+ | "claim_bot"
862
+ | "chain";
863
+ export declare const SUBMISSION_FAILURE_STEPS: readonly SubmissionFailureStep[];
864
+ /**
865
+ * 0.7.0: how one answer is shown on the card: a string as it is; a number or
866
+ * boolean as String(value); null as ""; an array of strings, numbers and
867
+ * booleans as its items' display forms joined with ", " ("" when empty).
868
+ * Anything else (an object, a nested or mixed array) has no display form:
869
+ * undefined. Objects and arrays of objects are not answers but containers
870
+ * (their answers are the rows below them).
871
+ */
872
+ export declare function submissionDisplayValue(value: unknown): string | undefined;
873
+ /**
874
+ * 0.7.0: why an application or claim card's `summary` does not show exactly
875
+ * its `data`, as the Hub's 400 `reason`, or null. The answers of `data` are
876
+ * its leaves: walking objects key by key and arrays of objects index by
877
+ * index (path segments joined with "."), every other value is an answer at
878
+ * its path. Every answer needs exactly one row with that `field` and its
879
+ * display form as `value`; no row may name anything else; a key may not be
880
+ * empty or contain "."; a claim's evidence `field` must not already hold an
881
+ * answer (a file is shown as a file, not a row).
882
+ */
883
+ export declare function submissionSummaryIssue(
884
+ operation: BidSubmitOperation | ClaimSubmitOperation,
885
+ ): string | null;
886
+ export type SubmissionNetworkFee = "covered" | "balance";
887
+ export declare const SUBMISSION_NETWORK_FEES: readonly SubmissionNetworkFee[];
888
+ /** 0.7.0: the longest failure `message` or `detail` (UTF-16 units). */
889
+ export declare const SUBMISSION_TEXT_MAX: 500;
890
+ /**
891
+ * 0.7.0: plain text safe to show: control characters become spaces,
892
+ * invisible and bidi characters are dropped, link-like text becomes
893
+ * `[link]`, whitespace is collapsed, cut to SUBMISSION_TEXT_MAX. Idempotent.
894
+ */
895
+ export declare function sanitizeSubmissionText(text: string): string;