@ixo/action-protocol 0.4.1 → 0.6.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 ADDED
@@ -0,0 +1,98 @@
1
+ # Changelog
2
+
3
+ ## 0.6.0
4
+
5
+ One card kind for every chain transaction: `ixo.chain.tx.v1`. Every existing
6
+ shape is unchanged. The Hub shows it only to callers that declare
7
+ `?version=4` (wire level 4 = level 3 + chain transactions; the envelope tags
8
+ stay `ixo.auth-capabilities/2` / `ixo.auth-outcome/2`), because released
9
+ 0.5.0 runtimes already declare `?version=3` and parse with exact-key parsers.
10
+
11
+ - Operation `ixo.chain.tx.v1`: `chainId`, `network`, `signer`, `memo`
12
+ (0..256 UTF-8 bytes) and `messages` (1..8, one transaction, all or
13
+ nothing). Message types (`CHAIN_TX_MESSAGE_TYPES`): `cosmos.bank.send`,
14
+ `ixo.claims.submit`, `ixo.claims.evaluate` (status 1..4), and
15
+ `ixo.token.transfer` (IXO impact tokens, 1..32 token lines).
16
+ - `chainTxIssue(operation)`: the first malformed field as the Hub's 400
17
+ `reason` (`invalid_message: messages[1].toAddress`, 0-based index, or
18
+ `invalid_operation: memo`), or null. `parseOperation` throws
19
+ `Invalid messages[1].toAddress` for the same field.
20
+ - Review view `chainTx` (`ChainTxDisplay`, `parseChainTxDisplay`): the
21
+ Hub-computed steps (title, one sentence, facts, risk, cannotUndo, the
22
+ bank-send `TransferDisplay` for bank steps), overall `riskLevel`,
23
+ `confirmTwice` (high or critical), consent text, fee, signer and `wrapped`.
24
+ It must match the operation's signer and message types in order.
25
+ - Receipt `ixo.chain.tx.v1`: chain id, tx hash, height, code, `steps` (the
26
+ message types in order), and on failure a `reason`
27
+ (`CHAIN_TX_FAILURE_REASONS`: `check_tx_rejected`, `expired_not_included`,
28
+ or `tx_failed` = included with code != 0) with an optional plain
29
+ `message` (at most 240). Never in a `/1` outcome envelope.
30
+ - Capabilities `chainTx` (`parseChainTxCapabilities`):
31
+ `{messageTypes, maxMessages}`, present exactly when `operations` lists
32
+ `ixo.chain.tx.v1`; absent (or null) otherwise.
33
+ - The operation JSON schema supports `integer` (used by the evaluation
34
+ `reason`, a uint32 the evaluator defines).
35
+ - Validation is stricter than the first 0.6.0 draft (`chainTxIssue`,
36
+ `parseOperation`): claim ids and token ids must match
37
+ `^[A-Za-z0-9:._/-]+$`; every address must decode to a 20-byte account;
38
+ a DID's `%` must start a valid `%xx` escape; the memo refuses control
39
+ characters; `verificationProof` is at most 300 characters (was 512), so
40
+ the review display can show it whole.
41
+ - No caps: chain transactions have no per-message capability rows, no
42
+ per-message enablement and no amount caps (product decision); the kind is
43
+ on by default and an operator can only disable it as a whole.
44
+ `/transfer-limits` stay for `ixo.bank.send.v1`.
45
+ - Retirement plan for `ixo.bank.send.v1` (not in this release): unchanged
46
+ until `cosmos.bank.send` in a chain tx card is proven live on every
47
+ network; then runtimes stop creating it, the Hub serves existing rows until
48
+ they are terminal and past retention, and the kind is removed in a major
49
+ version.
50
+ - Rollout order: Hub, then gateways on 0.6.0 (a pre-0.6.0 strict parser
51
+ fails its confirmation reads of chain-tx receipts), then runtimes on
52
+ `?version=4`.
53
+
54
+ ## 0.5.0
55
+
56
+ Everything in the P1 0.3.0 entry below (shipped on the stacked P1 branch), on
57
+ top of 0.4.1, plus:
58
+
59
+ - Operation JSON schema: bank `denom` is any Cosmos denom (`DENOM`, optional,
60
+ default `uixo`) and `feeBaseUnits` is optional (the Hub simulates the fee).
61
+ Optional schema properties are validated when present.
62
+ - `/options?version=3` (`ixo.auth-options/3`): V2 plus `transfer.tokens`
63
+ (`OptionsToken`: `denom`, `symbol`, `decimals`, `verified`,
64
+ `balanceBaseUnits`), parsed by `parseOptionsTransfer`. V1/V2 unchanged.
65
+ - Wire changes summary for consumers:
66
+ - outcome callbacks are signed (`x-auth-hub-timestamp`, `x-auth-hub-key-id`,
67
+ `x-auth-hub-signature` over `${timestamp}.${audience}.${sha256hex(body)}`);
68
+ the per-account `x-auth-hub-outcome-key` header is gone;
69
+ - v2 bank receipts add `denom` + `amountBaseUnits`; v1 receipts are the
70
+ 0.4.1 shape exactly;
71
+ - review views may carry `transfer` (`TransferDisplay` with `verified`);
72
+ - v2 capabilities `transfer` is `{limits, maxFeeUixo}`; v1 keeps
73
+ `{maxAmountUixo, maxFeeUixo}`.
74
+
75
+ ## 0.3.0
76
+
77
+ All additions are optional. The Hub only emits them to callers that declare
78
+ `?version=3`; v1 and v2 callers keep the 0.4.1 shapes.
79
+
80
+ - Bank send `denom`: any Cosmos denom matching `DENOM`; absent means `uixo`
81
+ (the parser fills it in).
82
+ - Bank send `feeBaseUnits`: optional; the Hub ignores it and simulates the fee.
83
+ - Bank receipt: optional `denom` and `amountBaseUnits`. `parseOutcome` rejects
84
+ them (and `reason`) in an `ixo.auth-outcome/1` envelope; `outcomeForVersion`
85
+ and the new `v1Receipt` strip them for v1 callers.
86
+ - Review view: optional `transfer` (`TransferDisplay`, parsed by
87
+ `parseTransferDisplay`): Hub-computed amount display, symbol, decimals,
88
+ `verified` (false = untrusted metadata: base units, show the full denom and
89
+ an unverified marker), simulated fee, gas limit and fee granter.
90
+ - Capabilities `transfer`: new `{limits: [{denom, maxAmountBaseUnits}],
91
+ maxFeeUixo?}` form beside the legacy `{maxAmountUixo, maxFeeUixo}`.
92
+ - Signed outcome callbacks: `OUTCOME_SIGNATURE_HEADERS`,
93
+ `OUTCOME_SIGNATURE_MAX_SKEW_SECONDS` (300), `outcomeAudience`,
94
+ `outcomeSigningPayload`, `signOutcomeRequest`, `verifyOutcomeRequest`,
95
+ `ed25519PublicKeyFromMultibase`, `publicKeyFromDidDocument`. The signed
96
+ string is `${timestamp}.${audience}.${sha256hex(rawBody)}` with audience =
97
+ the receiving oracle's https origin; `verifyOutcomeRequest` requires
98
+ `expectedAudience`. Receivers dedupe by event id.
package/README.md ADDED
@@ -0,0 +1,190 @@
1
+ # @ixo/action-protocol
2
+
3
+ Dependency-free wire parsers, types and helpers for Auth Hub action operations
4
+ (`ixo-auth-hub` `/api/internal/actions/*` and the outcome callbacks). The Hub,
5
+ the channel gateway and oracle runtimes use the same parsers, so a shape one
6
+ side emits is exactly what the other side accepts.
7
+
8
+ The full API is documented in `docs/action-operations-api.md` in the
9
+ ixo-auth-hub repository. This file covers the contract a consumer must follow.
10
+
11
+ ## Envelope versions
12
+
13
+ Callers declare the envelope version they parse with `?version=2` on
14
+ `GET /capabilities`, `POST /operations` and `GET /operations/:id`.
15
+
16
+ - v1 (`ixo.auth-outcome/1`, `ixo.auth-capabilities/1`): the 0.1.0 status set
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`): 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
+ ## Bank send (`ixo.bank.send.v1`)
28
+
29
+ - `denom`: any Cosmos denom matching `DENOM`
30
+ (`^[a-zA-Z][a-zA-Z0-9/:._-]{2,127}$`); absent means `uixo`.
31
+ - `feeBaseUnits`: optional and ignored. The Hub simulates gas and fee itself
32
+ and freezes them into the SignDoc.
33
+ - The review view carries `transfer` (`TransferDisplay`): the Hub-computed
34
+ `amountDisplay`, `symbol`, `decimals`, `verified`, `feeBaseUnits`,
35
+ `feeDenom` (`uixo`), `feeDisplay`, `gasLimit` and `feeGranter`. Never do
36
+ decimal math or guess `ibc/` hashes on the client; show what the Hub returns.
37
+ - `verified` is true only for `uixo` and `ibc/` denoms with metadata. When it
38
+ is false the symbol and decimals are not trusted (anyone controlling a
39
+ factory/cw20 token can call it "USDC"): `decimals` is 0, `amountDisplay` is
40
+ base units, and the UI must show the full denom and an "unverified token"
41
+ marker. Show the full denom for anything that is not `uixo`.
42
+ - Bank receipts carry `denom` and `amountBaseUnits` for `?version=3` callers.
43
+
44
+ ## Chain transactions (`ixo.chain.tx.v1`)
45
+
46
+ One card kind for every chain transaction. The person sees every step in
47
+ plain words, ticks a box, and signs once; the steps run as one transaction
48
+ (all succeed or none do).
49
+
50
+ ```ts
51
+ {
52
+ kind: "ixo.chain.tx.v1",
53
+ chainId: string, // the Hub's chain
54
+ network: "ixo mainnet" | "ixo testnet" | "ixo devnet", // the Hub's network
55
+ signer: string, // the person's Hub wallet address
56
+ memo: string, // 0..256 UTF-8 bytes
57
+ messages: ChainTxMessage[], // 1..8
58
+ }
59
+ ```
60
+
61
+ | `type` | Fields | What it does |
62
+ | --- | --- | --- |
63
+ | `cosmos.bank.send` | `toAddress`, `amountBaseUnits`, `denom?` (absent = `uixo`) | Sends coins from the person's wallet. |
64
+ | `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>`. |
65
+ | `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. |
66
+ | `ixo.token.transfer` | `recipient`, `tokens: [{id, amount}]` (1..32) | Moves IXO impact tokens (1155-style), not IXO coins. The chain `owner` is the signer. |
67
+
68
+ - Authorization: the Hub wraps each claims message in
69
+ `/cosmos.authz.v1beta1.MsgExec {grantee: signer, msgs: [inner]}` (one
70
+ MsgExec per claims message), because submit and evaluate run under the
71
+ collection admin's authorization. Bank and token messages are signed
72
+ directly.
73
+ - Validation: `chainTxIssue(operation)` names the first bad field the way
74
+ the Hub's `400 operation_not_registered` `reason` does
75
+ (`invalid_message: messages[1].toAddress`, 0-based index). Validate with
76
+ it before calling the Hub; the Hub also checks the signer, network, chain
77
+ and bech32 checksums. Claim and token ids use only
78
+ `^[A-Za-z0-9:._/-]+$` (impact token ids on chain are 32-hex strings, and
79
+ 1155 amounts have no decimals).
80
+ - Review view `chainTx` (`ChainTxDisplay`): the Hub's plain words, the only
81
+ step text a page renders. `steps[]` each have a `title`, one-sentence
82
+ `whatItDoes`, `facts` (`technical` facts go behind a disclosure),
83
+ `riskLevel`, `cannotUndo`, and for bank steps the bank-send `transfer`
84
+ display (same verified/unverified rules). Titles and sentences never carry
85
+ a hash, denom or address ("Transfer 3 impact tokens", "Sends 1.5 IXO from
86
+ your wallet to the address below."). The memo is not a step fact: the page
87
+ shows the operation's `memo` once, as "Note", after the steps.
88
+ `confirmTwice` is true for high/critical: the page asks a second time
89
+ before signing. `consent` is the checkbox text.
90
+ - Unhappy paths (what the oracle and the person see):
91
+ 1. The message does not look right: `400 operation_not_registered` with a
92
+ `reason` naming the field (`chainTxIssue` gives the same), no card.
93
+ 2. The Hub cannot prepare it: `400 insufficient_funds`,
94
+ `400 not_authorized`, `400 fee_above_ceiling`, `400 simulation_failed`
95
+ (with a fixed `reason` phrase when known), `409 sequence_mismatch`,
96
+ `503 transfer_unavailable`; no card. At sign time the Hub can still
97
+ refuse with `409 fee_grant_changed` (the fee is no longer covered),
98
+ `409 insufficient_funds` (the wallet no longer covers it) or
99
+ `409 review_changed`; nothing is sent and the person is asked to get a
100
+ new link.
101
+ 3. The transaction failed: a `failed` receipt with `reason`
102
+ `check_tx_rejected` (never included, no fee), `tx_failed` (included with
103
+ an error: nothing in it happened, but the network fee was used) or
104
+ `expired_not_included` (never included), plus a plain `message` for the
105
+ first two.
106
+ - Receipt `ixo.chain.tx.v1`: `chainId`, `txHash`, `height`, `code`, `steps`
107
+ (`[{type}]` in order). A `failed` receipt always has a `reason`:
108
+ `check_tx_rejected` (never included; CheckTx code), `expired_not_included`
109
+ (never included; code null) or `tx_failed` (included with code != 0), and
110
+ may carry a plain `message` (≤ 240) to show the person.
111
+ - Capabilities (`?version=4`):
112
+ `chainTx: {messageTypes, maxMessages}` when the kind is listed. There are
113
+ no per-message caps and no per-message enablement.
114
+ - Retiring `ixo.bank.send.v1`: it stays unchanged until `cosmos.bank.send`
115
+ in this card is proven live on every network. Then runtimes stop creating
116
+ bank-send cards (a one-step chain tx replaces them), the Hub keeps serving
117
+ existing bank-send rows until they are terminal and past retention, and
118
+ only then is the kind removed, in a major version.
119
+ - Rollout: Hub first, then gateways on 0.6.0 (a pre-0.6.0 strict parser
120
+ fails its confirmation reads of chain-tx receipts), then runtimes on
121
+ `?version=4`.
122
+
123
+ ## Options
124
+
125
+ `GET /options?version=3` (`ixo.auth-options/3`) is V2 plus
126
+ `transfer: {tokens: [{denom, symbol, decimals, verified, balanceBaseUnits}]} | null`
127
+ (one AllBalances page, at most 50 tokens). The same `verified` rule as the
128
+ review view applies. Copy `denom` and base-unit amounts from it; V2 is
129
+ unchanged, so 0.4.1 parsers keep working on V2.
130
+
131
+ ## Capabilities
132
+
133
+ `transfer` is either `{limits: [{denom, maxAmountBaseUnits}], maxFeeUixo?}`
134
+ (`?version=3`; an empty `limits` means no caps) or the legacy
135
+ `{maxAmountUixo, maxFeeUixo}` (v1/v2).
136
+
137
+ ## Signed outcome callbacks
138
+
139
+ The Hub signs every callback with its service DID key, the `#key-0` Ed25519
140
+ key in `https://<hub host>/.well-known/did.json`.
141
+
142
+ | Header | Value |
143
+ | --- | --- |
144
+ | `x-auth-hub-timestamp` | unix seconds |
145
+ | `x-auth-hub-key-id` | `did:web:<hub host>#key-0` |
146
+ | `x-auth-hub-signature` | base64url Ed25519 over `${timestamp}.${audience}.${sha256hex(rawBody)}` |
147
+
148
+ `audience` is your https origin (the origin of the oracle URL registered on
149
+ the channel account). It is not sent: pass your own public origin from
150
+ configuration as the required `expectedAudience`, so a callback signed for
151
+ another oracle never verifies at yours. Verify with the exact raw body bytes,
152
+ the Hub DID you were configured with (never a DID taken from the request) and
153
+ a 300 s maximum clock skew, and dedupe accepted callbacks by event id (a
154
+ valid callback can arrive again within the skew window or on a Hub retry):
155
+
156
+ ```js
157
+ import {
158
+ parseOutcome,
159
+ publicKeyFromDidDocument,
160
+ verifyOutcomeRequest,
161
+ } from "@ixo/action-protocol";
162
+
163
+ const hubDid = "did:web:auth.ixo.earth"; // configuration, not the request
164
+ const keyId = `${hubDid}#key-0`;
165
+ const didDocument = await (
166
+ await fetch("https://auth.ixo.earth/.well-known/did.json")
167
+ ).json(); // cache this
168
+ const rawBody = await request.text();
169
+ const ok = await verifyOutcomeRequest({
170
+ rawBody,
171
+ headers: request.headers,
172
+ publicKey: publicKeyFromDidDocument(didDocument, keyId),
173
+ expectedKeyId: keyId,
174
+ expectedAudience: "https://oracle.example", // your own origin, from config
175
+ });
176
+ if (!ok) return new Response("unauthorized", { status: 401 });
177
+ const outcome = parseOutcome(JSON.parse(rawBody));
178
+ ```
179
+
180
+ During the transition the Hub also sends the deprecated per-account
181
+ `x-auth-hub-outcome-key` to accounts that still have one registered; it will
182
+ be removed once every oracle verifies the signature.
183
+
184
+ Uses WebCrypto Ed25519 only (Node 20+, Cloudflare Workers, modern browsers).
185
+
186
+ ## Tests
187
+
188
+ ```sh
189
+ node --test test/*.test.mjs
190
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ixo/action-protocol",
3
- "version": "0.4.1",
3
+ "version": "0.6.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": {
@@ -17,7 +17,8 @@
17
17
  }
18
18
  },
19
19
  "files": [
20
- "src"
20
+ "src",
21
+ "CHANGELOG.md"
21
22
  ],
22
23
  "engines": {
23
24
  "node": ">=20"
package/src/index.d.ts CHANGED
@@ -8,6 +8,7 @@ export type FormField = {
8
8
  };
9
9
  export type ActionOperationV1 =
10
10
  | P2Operation
11
+ | ChainTxOperation
11
12
  | {
12
13
  kind: "form.submit.v1";
13
14
  formId: string;
@@ -22,8 +23,10 @@ export type ActionOperationV1 =
22
23
  fromAddress: string;
23
24
  toAddress: string;
24
25
  amountBaseUnits: string;
25
- denom: "uixo";
26
- feeBaseUnits: string;
26
+ /** Any bank denom (0.3.0); parseOperation fills "uixo" when absent. */
27
+ denom: string;
28
+ /** Optional since 0.3.0 and ignored by the Hub (it simulates the fee). */
29
+ feeBaseUnits?: string;
27
30
  memo: string;
28
31
  }
29
32
  | {
@@ -48,6 +51,7 @@ export type ActionReferenceV1 = {
48
51
  };
49
52
  export type ActionReceiptV1 =
50
53
  | P2Receipt
54
+ | ChainTxReceipt
51
55
  | {
52
56
  kind: "form.submission.v1";
53
57
  actionId: string;
@@ -72,6 +76,9 @@ export type ActionReceiptV1 =
72
76
  * `expired_not_included` has `code: null` (timeout height passed).
73
77
  */
74
78
  reason?: "check_tx_rejected" | "expired_not_included";
79
+ /** 0.3.0: the denom and base-unit amount that moved. */
80
+ denom?: string;
81
+ amountBaseUnits?: string;
75
82
  };
76
83
  export type ActionOutcomeStatus =
77
84
  | "authorized"
@@ -132,6 +139,28 @@ export type ActionReviewView = {
132
139
  accountLabel: string | null;
133
140
  resource: ResourceDescriptor | null;
134
141
  } | null;
142
+ /** 0.3.0: Hub-computed transfer display (bank sends only). */
143
+ transfer?: TransferDisplay | null;
144
+ /** 0.6.0: Hub-computed chain transaction display (chain tx cards only). */
145
+ chainTx?: ChainTxDisplay | null;
146
+ };
147
+ export type TransferDisplay = {
148
+ denom: string;
149
+ symbol: string;
150
+ decimals: number;
151
+ /**
152
+ * true only for uixo and ibc/ denoms with metadata. false: the symbol and
153
+ * decimals are not trusted (decimals is 0, amountDisplay is base units);
154
+ * show the full denom and an "unverified token" marker.
155
+ */
156
+ verified: boolean;
157
+ amountDisplay: string;
158
+ feeBaseUnits: string;
159
+ feeDenom: "uixo";
160
+ feeDisplay: string;
161
+ gasLimit: number;
162
+ /** The fee granter frozen into the SignDoc, or null when the user pays. */
163
+ feeGranter: string | null;
135
164
  };
136
165
  export type ActionCapabilitiesV1 = {
137
166
  version: "ixo.auth-capabilities/1" | "ixo.auth-capabilities/2";
@@ -146,8 +175,201 @@ export type ActionCapabilitiesV1 = {
146
175
  fields: Omit<FormField, "value" | "source">[];
147
176
  declaration: string | null;
148
177
  }[];
149
- transfer: { maxAmountUixo: string; maxFeeUixo: string } | null;
178
+ transfer:
179
+ | { maxAmountUixo: string; maxFeeUixo: string }
180
+ | {
181
+ /** Optional per-denom amount caps (empty = no cap). */
182
+ limits: { denom: string; maxAmountBaseUnits: string }[];
183
+ /** The Hub-wide simulated-fee ceiling. */
184
+ maxFeeUixo?: string;
185
+ }
186
+ | null;
187
+ /**
188
+ * 0.6.0 (`?version=4` only): present (an object) exactly when `operations`
189
+ * lists `ixo.chain.tx.v1`; absent or null otherwise.
190
+ */
191
+ chainTx?: ChainTxCapabilities | null;
192
+ };
193
+
194
+ /** 0.6.0: one card kind for every chain transaction. */
195
+ export type ChainTxMessageType =
196
+ | "cosmos.bank.send"
197
+ | "ixo.claims.submit"
198
+ | "ixo.claims.evaluate"
199
+ | "ixo.token.transfer";
200
+ /**
201
+ * Field rules (`chainTxIssue` names the first bad field):
202
+ * - addresses: a 20-byte ixo account address, `ixo1` + 38 bech32 characters
203
+ * (the Hub also checks the checksum);
204
+ * - DIDs: `did:<method>:` then segments of [A-Za-z0-9._-] or `%` + two hex
205
+ * digits, joined by ':' (the chain's x/iid rule; `agentDid` is `did:ixo:`);
206
+ * - claim ids, token ids and verification proofs: ^[A-Za-z0-9:._/-]+$;
207
+ * - collectionId: a uint64 without leading zeros.
208
+ */
209
+ export type ChainTxMessage =
210
+ | {
211
+ type: "cosmos.bank.send";
212
+ toAddress: string;
213
+ /** ^[1-9][0-9]*$ */
214
+ amountBaseUnits: string;
215
+ /** Same rule as bank.send (`DENOM`); absent = uixo. */
216
+ denom?: string;
217
+ }
218
+ | {
219
+ type: "ixo.claims.submit";
220
+ /** ^(0|[1-9][0-9]{0,19})$, ≤ 18446744073709551615 */
221
+ collectionId: string;
222
+ /** 1..256, ^[A-Za-z0-9:._/-]+$ */
223
+ claimId: string;
224
+ /**
225
+ * did:ixo:… The person filing: the Hub requires it to be the signer's
226
+ * own DID (the chain records it as attribution only and does not check
227
+ * it against the signer), else `400 operation_not_registered`,
228
+ * `reason: 'invalid_message: messages[i].agentDid'`.
229
+ */
230
+ agentDid: string;
231
+ adminAddress: string;
232
+ useIntent?: boolean;
233
+ }
234
+ | {
235
+ type: "ixo.claims.evaluate";
236
+ /** 1..256, ^[A-Za-z0-9:._/-]+$ */
237
+ claimId: string;
238
+ /** ^(0|[1-9][0-9]{0,19})$, ≤ 18446744073709551615 */
239
+ collectionId: string;
240
+ /** The evaluator DID recorded on the evaluation. */
241
+ oracle: string;
242
+ /**
243
+ * The EVALUATOR (the signer), not the claimant. The Hub requires
244
+ * `agentDid` to be the signer's own DID and `agentAddress` to equal
245
+ * `signer` (`invalid_message: messages[i].agentDid` / `.agentAddress`).
246
+ */
247
+ agentDid: string;
248
+ agentAddress: string;
249
+ adminAddress: string;
250
+ /** EvaluationStatus: 1 approved, 2 rejected, 3 disputed, 4 invalidated (0 pending, 5 flagged refused). */
251
+ status: 1 | 2 | 3 | 4;
252
+ /** uint32 code defined by the evaluator (the chain has no enum for it). */
253
+ reason?: number;
254
+ /** '' or 1..300 of ^[A-Za-z0-9:._/-]+$ (shown whole on the review). */
255
+ verificationProof?: string;
256
+ }
257
+ | {
258
+ type: "ixo.token.transfer";
259
+ recipient: string;
260
+ /** 1..32 lines; id 1..128 of ^[A-Za-z0-9:._/-]+$, amount ^[1-9][0-9]*$ */
261
+ tokens: Array<{ id: string; amount: string }>;
262
+ };
263
+ export type ChainTxOperation = {
264
+ kind: "ixo.chain.tx.v1";
265
+ /** Must equal the Hub RPC's chain id at prepare. */
266
+ chainId: string;
267
+ /** Must equal the Hub's `ixo ${CHAIN_NETWORK}`. */
268
+ network: "ixo mainnet" | "ixo testnet" | "ixo devnet";
269
+ /** 20-byte bech32 ixo address; must equal the person's Hub wallet address. */
270
+ signer: string;
271
+ /**
272
+ * 0..256 UTF-8 bytes, may be ''. No C0/C1 controls (so no newlines),
273
+ * zero-width, bidi or line/paragraph separator characters, no BOM.
274
+ */
275
+ memo: string;
276
+ /** 1..8, executed as ONE transaction (all or nothing). */
277
+ messages: ChainTxMessage[];
150
278
  };
279
+ export type ChainTxRiskLevel = "low" | "medium" | "high" | "critical";
280
+ export type ChainTxFact = { label: string; value: string; technical?: boolean };
281
+ export type ChainTxStep = {
282
+ /** 1-based */
283
+ index: number;
284
+ type: ChainTxMessageType;
285
+ /** ≤ 60, plain words. */
286
+ title: string;
287
+ /** One sentence, ≤ 160. */
288
+ whatItDoes: string;
289
+ /** `technical` facts go behind "Show technical details". */
290
+ facts: ChainTxFact[];
291
+ riskLevel: ChainTxRiskLevel;
292
+ cannotUndo: boolean;
293
+ /** cosmos.bank.send steps: the bank-send display (verified/unverified token rules). */
294
+ transfer?: TransferDisplay;
295
+ };
296
+ export type ChainTxDisplay = {
297
+ /** The highest step risk. */
298
+ riskLevel: ChainTxRiskLevel;
299
+ /** riskLevel is high or critical. */
300
+ confirmTwice: boolean;
301
+ steps: ChainTxStep[];
302
+ /** The checkbox text, ≤ 160. */
303
+ consent: string;
304
+ feeBaseUnits: string;
305
+ feeDenom: "uixo";
306
+ feeDisplay: string;
307
+ gasLimit: number;
308
+ feeGranter: string | null;
309
+ signer: string;
310
+ /** true when any step is wrapped in MsgExec. */
311
+ wrapped: boolean;
312
+ };
313
+ export type ChainTxFailureReason =
314
+ | "check_tx_rejected"
315
+ | "expired_not_included"
316
+ | "tx_failed";
317
+ export type ChainTxReceipt = {
318
+ kind: "ixo.chain.tx.v1";
319
+ actionId: string;
320
+ revision: number;
321
+ digest: string;
322
+ chainId: string;
323
+ txHash: string;
324
+ height: number | null;
325
+ /** Chain result code (0 = success) once included. */
326
+ code: number | null;
327
+ /**
328
+ * `check_tx_rejected`: never included, CheckTx `code` ≠ 0, height null;
329
+ * `expired_not_included`: never included, code null, height null;
330
+ * `tx_failed`: included (height set) with code ≠ 0.
331
+ */
332
+ reason?: ChainTxFailureReason;
333
+ /** ≤ 240, plain words for the person; only with a `reason`. */
334
+ message?: string;
335
+ /** The approved messages' types, in order. */
336
+ steps: Array<{ type: ChainTxMessageType }>;
337
+ };
338
+ export type ChainTxCapabilities = {
339
+ messageTypes: ChainTxMessageType[];
340
+ maxMessages: number;
341
+ };
342
+ export declare const CHAIN_TX_KIND: "ixo.chain.tx.v1";
343
+ export declare const CHAIN_TX_MESSAGE_TYPES: readonly [
344
+ "cosmos.bank.send",
345
+ "ixo.claims.submit",
346
+ "ixo.claims.evaluate",
347
+ "ixo.token.transfer",
348
+ ];
349
+ export declare const CHAIN_TX_MAX_MESSAGES: 8;
350
+ export declare const CHAIN_TX_MAX_TOKEN_LINES: 32;
351
+ export declare const CHAIN_TX_FAILURE_REASONS: readonly [
352
+ "check_tx_rejected",
353
+ "expired_not_included",
354
+ "tx_failed",
355
+ ];
356
+ export declare const CHAIN_TX_RISK_LEVELS: readonly [
357
+ "low",
358
+ "medium",
359
+ "high",
360
+ "critical",
361
+ ];
362
+ export declare const CHAIN_TX_EVALUATION_STATUSES: readonly [1, 2, 3, 4];
363
+ /**
364
+ * Why a proposed chain tx operation is malformed, as the Hub's 400 `reason`
365
+ * (`invalid_message: messages[1].toAddress`, 0-based; `invalid_operation: memo`),
366
+ * or null when it parses.
367
+ */
368
+ export declare function chainTxIssue(input: unknown): string | null;
369
+ export declare function parseChainTxDisplay(input: unknown): ChainTxDisplay;
370
+ export declare function parseChainTxCapabilities(
371
+ input: unknown,
372
+ ): ChainTxCapabilities;
151
373
  export declare function canonicalJson(value: unknown): string;
152
374
  export declare function digestOf(value: unknown): Promise<string>;
153
375
  export declare function parseOperation(value: unknown): ActionOperationV1;
@@ -387,7 +609,27 @@ export type HubActionOptionsV2 = Omit<
387
609
  scopes: string[];
388
610
  }[];
389
611
  };
390
- export type HubActionOptions = HubActionOptionsV1 | HubActionOptionsV2;
612
+ /** 0.5.0: one owner bank balance with the Hub's trusted display. */
613
+ export type OptionsToken = {
614
+ denom: string;
615
+ symbol: string;
616
+ decimals: number;
617
+ /** false: untrusted metadata (decimals 0, base units); name the full denom. */
618
+ verified: boolean;
619
+ balanceBaseUnits: string;
620
+ };
621
+ export type HubActionOptionsV3 = Omit<HubActionOptionsV2, "version"> & {
622
+ version: "ixo.auth-options/3";
623
+ /** null when bank sends are off for the account, the owner has no address, or the chain did not answer. */
624
+ transfer: { tokens: OptionsToken[] } | null;
625
+ };
626
+ export type HubActionOptions =
627
+ | HubActionOptionsV1
628
+ | HubActionOptionsV2
629
+ | HubActionOptionsV3;
630
+ export declare function parseOptionsTransfer(input: unknown): {
631
+ tokens: OptionsToken[];
632
+ };
391
633
  export type StatementProofBody = ReceiptTuple & {
392
634
  version: "ixo.statement-proof/1";
393
635
  accountId: string;
@@ -464,3 +706,43 @@ export declare const V1_OPERATION_KINDS: readonly [
464
706
  ];
465
707
  export declare const NETWORKS: readonly ["ixo mainnet", "ixo testnet", "ixo devnet"];
466
708
  export declare const SERVICE_NETWORKS: readonly ["mainnet", "testnet", "devnet"];
709
+ export declare const DENOM: RegExp;
710
+ export declare function parseTransferDisplay(value: unknown): TransferDisplay;
711
+ export declare const OUTCOME_SIGNATURE_HEADERS: Readonly<{
712
+ timestamp: "x-auth-hub-timestamp";
713
+ keyId: "x-auth-hub-key-id";
714
+ signature: "x-auth-hub-signature";
715
+ }>;
716
+ export declare const OUTCOME_SIGNATURE_MAX_SKEW_SECONDS: 300;
717
+ /** Validates an exact https origin (the receiver's audience) and returns it. */
718
+ export declare function outcomeAudience(value: string): string;
719
+ export declare function outcomeSigningPayload(
720
+ timestamp: number,
721
+ audience: string,
722
+ rawBody: string | Uint8Array,
723
+ ): Promise<Uint8Array>;
724
+ export declare function signOutcomeRequest(input: {
725
+ privateKey: CryptoKey;
726
+ keyId: string;
727
+ /** The receiving oracle's https origin. */
728
+ audience: string;
729
+ rawBody: string | Uint8Array;
730
+ timestamp?: number;
731
+ }): Promise<Record<string, string>>;
732
+ export declare function verifyOutcomeRequest(input: {
733
+ rawBody: string | Uint8Array;
734
+ headers: Headers | Record<string, string | undefined>;
735
+ publicKey: Uint8Array | CryptoKey;
736
+ expectedKeyId: string;
737
+ /** The receiver's own public https origin, from configuration (required). */
738
+ expectedAudience: string;
739
+ now?: number;
740
+ maxSkewSeconds?: number;
741
+ }): Promise<boolean>;
742
+ export declare function ed25519PublicKeyFromMultibase(multibase: string): Uint8Array;
743
+ export declare function publicKeyFromDidDocument(
744
+ document: unknown,
745
+ keyId: string,
746
+ ): Uint8Array;
747
+ /** The exact 0.1.0 receipt shape for v1 callers (drops the 0.3.0 bank fields). */
748
+ export declare function v1Receipt<T extends ActionReceiptV1 | null>(receipt: T): T;