@ixo/action-protocol 0.7.0 → 0.8.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,274 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.8.0
4
+
5
+ 29 more message types for `ixo.chain.tx.v1` cards. Every existing shape is
6
+ unchanged. The Hub offers and accepts them only from callers that declare
7
+ `?version=6` (wire level 6 = level 5 + these 29 types; the envelope tags stay
8
+ `ixo.auth-capabilities/2` / `ixo.auth-outcome/2`), because every 0.6.0/0.7.0
9
+ parser refuses a capabilities document, review step or receipt that names a
10
+ type it does not know.
11
+
12
+ - `CHAIN_TX_MESSAGE_TYPES` (now frozen): the four 0.6.0 types, then the 29
13
+ below in this order (33). New `CHAIN_TX_LEVEL4_MESSAGE_TYPES` (frozen,
14
+ exactly the four) and `chainTxMessageTypesForLevel(level)`: none below 4,
15
+ the four at levels 4 and 5, all 33 from 6 (`CHAIN_TX_LEVEL6 = 6`). The Hub
16
+ uses it for capabilities and must refuse a create whose messages are not in
17
+ the caller's list with `400 protocol_version_required`, before
18
+ `chainTxIssue` (which accepts all 33). A Hub may still leave a type out of
19
+ what it offers.
20
+ - Tokens, staking and voting (the person signs directly):
21
+ - `ixo.token.retire` (`tokens`, `jurisdiction`, `reason`): uses up impact
22
+ tokens the person holds, for good (for example to offset). Token lines as
23
+ `ixo.token.transfer`; `jurisdiction` is `Global` or a country code with an
24
+ optional region and postal code (`KE`, `KE-30`, `ZA-WC 7700`); `reason`
25
+ is plain text up to 200, shown as is (below).
26
+ - `cosmos.staking.delegate` (`validatorAddress`, `amountBaseUnits`): stakes
27
+ IXO (always `uixo`) with a validator so it earns rewards. Takes the
28
+ amount from the wallet.
29
+ - `cosmos.staking.undelegate` (same keys): stops staking; the IXO comes back
30
+ after the unbonding period.
31
+ - `cosmos.staking.redelegate` (`fromValidatorAddress`,
32
+ `toValidatorAddress`, `amountBaseUnits`): moves stake to another
33
+ validator at once. The two validators must differ.
34
+ - `cosmos.distribution.withdraw-rewards` (`validatorAddress`): claims the
35
+ staking rewards earned with one validator.
36
+ - `cosmos.gov.vote` (`proposalId` ≥ 1, `option` `yes` | `no` | `abstain` |
37
+ `no_with_veto`): votes on a network proposal (gov v1); a later vote
38
+ replaces it.
39
+ - Claims:
40
+ - `ixo.claims.claim-intent` (`collectionId`, `agentDid`): sets a
41
+ collection's payment aside for a claim the person is about to file.
42
+ - `ixo.claims.dispute` (`claimId`, `collectionId`, `agentDid`, `reason`
43
+ `not_as_asked` | `not_delivered` | `check_wrong` | `other`, `evidence`
44
+ `{uri, type, proof, encrypted?}`): opens a dispute about a claim, or about
45
+ how it was checked (`check_wrong`). May take the collection's dispute
46
+ deposit. The evidence must already be stored (no storage tool yet).
47
+ - Collection changes, run under a permission from the collection's admin
48
+ account (MsgExec), each with `collectionId` and `adminAddress` (the Hub
49
+ checks it against the collection):
50
+ `ixo.claims.update-collection-state` (`state` `open` | `paused` |
51
+ `closed`): opens, pauses or closes a collection;
52
+ `ixo.claims.update-collection-dates` (`startDate?`, `endDate?` or `null`
53
+ for no end; at least one): changes when it takes claims;
54
+ `ixo.claims.update-collection-quota` (`maxClaims`, `"0"` = no limit):
55
+ changes how many claims it takes in total;
56
+ `ixo.claims.create-claim-authorization` (`granteeAddress`, `role`
57
+ `file-claims` | `check-claims`, `maxClaims` 1..10^9, `expiresAt?`,
58
+ `reservationSeconds?` for `file-claims`, `decideBefore?` for
59
+ `check-claims`, `creatorDid`): lets an account file or check claims in
60
+ it; `ixo.claims.update-collection-payments` (`payments`): changes what
61
+ it pays (legs left out keep what they pay).
62
+ - `ixo.claims.create-collection` (`entityId`, `protocolId`, `startDate`,
63
+ `endDate` or `null` (the key is required), `maxClaims`, `state`,
64
+ `reservations` `allow` | `deny` | `required`, `payments`): creates a
65
+ claim collection for an entity the person owns.
66
+ - `payments`: `{submission?, evaluation?, approval?, rejection?}`; a leg is
67
+ `{amount: [{denom, amountBaseUnits}] (0..4, distinct denoms),
68
+ payAfterSeconds? (0..31536000)}` and the approval leg may add
69
+ `networkSplit` (left out on an update: kept). On `create-collection` a
70
+ missing leg pays nothing. On `update-collection-payments` a missing leg
71
+ keeps exactly what it pays now (amounts, delay, paying account, any
72
+ CW20/CW1155 payments) and `{amount: []}` makes it pay nothing; the Hub
73
+ refuses to replace a leg that pays CW20/CW1155 tokens
74
+ (`token_payments_present`), which a card can neither show nor keep. No
75
+ CW20/CW1155 payments, deposits, penalties or adjudicators can be set.
76
+ - Entities (the person signs directly):
77
+ - `ixo.entity.create-account` (`entityId`, `name`): adds a named account
78
+ to an entity the person owns.
79
+ - `ixo.entity.update` (`entityId`, `startDate?`, `endDate?` or `null` to
80
+ clear it, at least one; `controllerDid`): changes when an entity is
81
+ active. There is no `status` (its meaning is defined by each app); the
82
+ Hub keeps status and credentials as they are.
83
+ - `ixo.entity.revoke-account-authz` / `ixo.entity.grant-account-authz`
84
+ (`entityId`, `granteeAddress`, `permission`; grant adds `collectionId`
85
+ and `maxClaims` (required for `file-claims`/`check-claims`, refused
86
+ otherwise), `reservationSeconds?`, `decideBefore?`, `expiresAt?`):
87
+ removes or gives a permission from the entity's admin account.
88
+ `permission` (`CHAIN_TX_ENTITY_PERMISSIONS`): `change-collection-state`,
89
+ `change-collection-dates`, `change-collection-quota`,
90
+ `change-collection-payments`, `authorize-claim-agents`, `file-claims`,
91
+ `check-claims`; nothing else can be granted through a card.
92
+ - `ixo.entity.create` (`entityType`, `profile?` `{serviceEndpoint (https),
93
+ proof}`, `protocolId?`, `startDate?`, `endDate?`, `ownerDid`): creates an
94
+ entity the person owns. The profile must already be stored.
95
+ - Identity document links (`did` is the document changed; the person's key
96
+ must be one of its authentication keys): `ixo.iid.add-service` /
97
+ `delete-service` (`service {id, type, serviceEndpoint}` / `serviceId`),
98
+ `add-linked-resource` / `delete-linked-resource` (`resource {id, type,
99
+ description, mediaType, serviceEndpoint, proof, encrypted, right?}` /
100
+ `resourceId`), `add-linked-claim` / `delete-linked-claim` (`claim {id,
101
+ type, description, serviceEndpoint, proof, encrypted, right?}` /
102
+ `claimId`), `add-linked-entity` / `delete-linked-entity` (`entity {id,
103
+ type, relationship, service?}` / `entityId`), `add-context` /
104
+ `delete-context` (`context {key, val}` / `key`): add or remove one link of
105
+ an entity's (or the person's own) identity document. What is already on
106
+ chain is accepted (checked against Portal and the live devnet documents):
107
+ - the id of an item to remove (`serviceId`, `resourceId`, `claimId`,
108
+ `entityId`, `key`; `ChainTxIidRemoveId`) is exactly what the document
109
+ holds, any 1..300 characters without whitespace or control characters
110
+ (Portal stored `#api` with no prefix, `{id}#ixo1…`, ids without `#`); the
111
+ Hub reads the document and refuses an id that is not there;
112
+ - a linked entity `id` is an IXO DID, an ixo account (20-byte) or contract
113
+ (32-byte) address, or Portal's `{id}#<address>`; `relationship` is
114
+ `^[A-Za-z][A-Za-z0-9_-]{0,63}$` (Portal writes `Governs`); `service` may
115
+ be `""` (none) or hold `:` (`did:cosmos:ixo`);
116
+ - an item id to add may hold `:` after `#` (Portal's `#app:<id>`), and an
117
+ item `type` may hold `+` (`application/vnd.ixo.design-pod+json`);
118
+ - a linked resource or claim may have an empty `proof`, `description`
119
+ (up to 300) or `right`, as Portal's app links and form templates do.
120
+ - Shared rules (`chainTxIssue` names the first bad field, nested ones by
121
+ path, e.g. `invalid_message: messages[0].payments.approval.amount[1].denom`):
122
+ validator addresses `ixovaloper1` + 38 bech32 characters; entity ids
123
+ `did:ixo:entity:` + 32 lowercase hex; dates RFC 3339 with `Z` or an
124
+ offset; uint64 numbers as decimal text without leading zeros; plain text
125
+ without control, zero-width or bidi characters; links `https://` or
126
+ `ipfs://` up to 300 characters.
127
+ - Free text published on chain is exactly what the review page shows
128
+ (SHOWN_AS_IS): a retirement `reason` and a linked resource's or claim's
129
+ `description` and `right` must satisfy `sanitizePublishedText(value) ===
130
+ value`: no control or invisible characters (soft hyphen, word joiners and
131
+ invisible operators, variation selectors, zero-width, bidi and tag
132
+ characters), no real link (a URL with a scheme, `www.`, an email address,
133
+ or a host followed by a path such as `pay.example/now`), single spaces and
134
+ no space at either end. A plain file name ("Annual Report.pdf") or a
135
+ version ("v2.0.1") is fine. Parser-only (the JSON schema does not express
136
+ it). Removes name an id only and are unaffected. New export
137
+ `sanitizePublishedText` (the same as `sanitizeSubmissionText` except that
138
+ only real links become `[link]`); the Hub shows these fields with it.
139
+ - `sanitizeSubmissionText` (and `stripHiddenCharacters`) also drop the
140
+ Unicode tag characters (U+E0000-E007F, which can carry text no one sees)
141
+ and the musical-symbol format characters (U+1D173-1D17A). The 0.7.0
142
+ receipt and view fields checked against the sanitizer (`receipt.message`,
143
+ `receipt.detail`, `view.collectionName`) are still checked against the
144
+ 0.7.0 rule, so receipts, outcomes and views stored before 0.8.0 keep
145
+ parsing; everything the 0.8.0 sanitizer makes passes that rule too. Signer-derived chain fields (owner,
146
+ delegator, voter, signer, agent/creator/controller/owner address) are never
147
+ wire keys; the Hub fills them from `signer`.
148
+ - Bounds this package chose where the design left them open (stricter, never
149
+ looser than the chain):
150
+ - dates must be real calendar dates and, in UTC, between
151
+ 1970-01-01T00:00:00Z and the end of year 9999 (what a protobuf Timestamp
152
+ holds the way the Hub encodes it);
153
+ - when both dates are on the wire, `endDate` must be after `startDate`
154
+ (collection dates, create collection, entity update, entity create);
155
+ with neither date on an update, the reason names `startDate`;
156
+ - plain text may not be blank;
157
+ - an `https://` link has a host and no user info (`https://a@b`), and no
158
+ link may contain whitespace, a backslash or a control character;
159
+ - an entity account `name` may not be `admin` in any letter case;
160
+ - `mediaType` is at most 128 characters;
161
+ - a linked entity's `service` (the design left it open) is `""`, a service
162
+ name or a reference to one: `^(?:(?:\{id\}|did:ixo:…)#)?[A-Za-z0-9._~:-]{1,64}$`
163
+ (Portal writes names such as `svc1` or `matrix`);
164
+ - every `collectionId` keeps the 0.6.0 rule (uint64, `"0"` allowed: the
165
+ Hub's collection read refuses a collection that does not exist).
166
+ - Review display (`parseChainTxDisplay`), receipts (`parseChainTxReceipt`)
167
+ and capabilities (`parseChainTxCapabilities`) accept the 33 types.
168
+ `step.transfer` stays for `cosmos.bank.send` only. `CHAIN_TX_MAX_MESSAGES`
169
+ stays 8 and the display limits are unchanged.
170
+ - Refusal codes (`CHAIN_TX_REFUSAL_CODES`, `ChainTxRefusalCode`,
171
+ `parseChainTxRefusal`): when the Hub will not make a card from what it read
172
+ on chain, or the node's simulation names one message, the 400 (`error`
173
+ `operation_not_registered` for a Hub read, `simulation_failed` for the
174
+ simulation) has `reason: "invalid_message: messages[<i>].<field>: <code>"`.
175
+ The prefix is the 0.6.0 shape, so a caller that matches
176
+ `^invalid_message: messages\[<i>\]\.` or shows the reason as quoted text
177
+ keeps working; a reason without `: <code>` is a shape the parser refused.
178
+ Map the code to your own words; treat an unknown code like none. Codes:
179
+ - staking and rewards: `validator_not_found` (no such validator),
180
+ `no_stake` (nothing staked with that validator), `stake_too_small` (more
181
+ than is staked), `same_validator`, `invalid_amount`,
182
+ `nothing_to_collect` (no rewards to collect);
183
+ - voting: `proposal_not_found`, `proposal_not_open` (not in its voting
184
+ period), `invalid_vote_option`;
185
+ - impact tokens: `token_not_found`;
186
+ - claims and collections: `collection_not_found`, `reservations_off` (the
187
+ collection takes no reservations), `reservation_exists` (one is already
188
+ held), `claim_not_found`, `claim_in_other_collection`, `wrong_admin` (not
189
+ the collection's admin account), `already_in_state` (the collection
190
+ already has that state), `start_date_missing` (no start date given or
191
+ set), `end_before_start`, `quota_below_count` (fewer than already
192
+ filed), `token_payments_present` (that leg pays CW20/CW1155 tokens);
193
+ - permissions: `ends_too_soon` (`expiresAt` before the link expires),
194
+ `deadline_too_soon` (`decideBefore` likewise), `current_permission_ends_too_soon`
195
+ (no `expiresAt` was given and the permission already there, whose end
196
+ would be kept, ends before the link expires: give an end date),
197
+ `unlimited_permission_exists` (an unlimited permission of this kind is
198
+ there; it has to be removed first), `other_permission_exists` (a
199
+ permission of another kind or from another admin is under that key),
200
+ `too_many_constraints` (the permission would hold more than 50
201
+ collection entries, the most a card keeps), `no_such_permission`
202
+ (nothing to remove),
203
+ `collection_of_other_entity`;
204
+ - entities and identity documents: `entity_not_found`,
205
+ `account_name_taken`, `document_not_found`, `nothing_to_remove`,
206
+ `already_exists`, `invalid_did` (an identifier the chain says is not a
207
+ valid DID; also on the 0.6.0 claim types);
208
+ - the card as a whole: `not_available` (this Hub does not offer this
209
+ message type here, e.g. `ixo.entity.create` on a deployment without a
210
+ relayer node; field `type`), `chain_data_too_large` (what the step must
211
+ keep from the chain, such as an entity's credentials or a collection's
212
+ payments, is too large to seal with a card).
213
+ - A grant that has expired (its end at or before now) counts as absent, as
214
+ the chain's own merge treats it (`GetAuthorization`): nothing of it is
215
+ kept, nothing is "already allowed", and removing it is `no_such_permission`.
216
+ - No new failure reason. A value the Hub read to build a message that changed
217
+ between review and signing (collection dates or payments, an entity, the
218
+ constraints a grant keeps or its end date, the dispute deposit, the item
219
+ being removed) is refused at `/sign` with the existing `409
220
+ review_changed`, now with `reason: "chain_changed"` (Hub to website; a
221
+ website that does not know it shows "The details changed"): the card is
222
+ withdrawn, nothing is sent, and the review page says that something it
223
+ depends on changed after the review and to ask for a fresh link. A read
224
+ that fails during that check is a retryable 503 (and the cron tries again
225
+ later; it never withdraws the card for it). The oracle gets `cancelled`,
226
+ as for any other withdrawn card. `CHAIN_TX_FAILURE_REASONS` is unchanged.
227
+ - An oracle reading `GET /operations/:id` at level 4/5 (a runtime rolled
228
+ back after it made a level-6 card) gets `receipt: null` and `outcome:
229
+ null` (the whole outcome, since a finished outcome must carry its receipt)
230
+ when the receipt names a new step type. Gateway reads are unchanged.
231
+ - Known limits (the chain decides at execution; the Hub cannot close them):
232
+ - between signing and inclusion (seconds) a claim filed under a permission
233
+ an entity grant keeps can have its used quota restored, because the
234
+ grant is written whole; the re-check before signing refuses any change
235
+ made earlier. Claim permissions added with
236
+ `ixo.claims.create-claim-authorization` are merged by the chain itself
237
+ and are not affected;
238
+ - collection payments and dates, and entity dates, are written whole: a
239
+ change someone else makes after the re-check and before inclusion is
240
+ overwritten;
241
+ - a dispute takes the collection's deposit as it is when the dispute is
242
+ recorded: the collection's owner can change the deposit, its token and
243
+ who decides after the re-check (`MsgDisputeClaim` has no cap). The review
244
+ says so;
245
+ - a permission that ends between the review and signing changes what an
246
+ entity grant keeps (an expired grant counts as absent): the card is
247
+ withdrawn as `chain_changed` and the person asks for a fresh link.
248
+ - New exports: `CHAIN_TX_VOTE_OPTIONS`, `CHAIN_TX_DISPUTE_REASONS`,
249
+ `CHAIN_TX_COLLECTION_STATES`, `CHAIN_TX_RESERVATION_MODES`,
250
+ `CHAIN_TX_CLAIM_ROLES`, `CHAIN_TX_ENTITY_PERMISSIONS`,
251
+ `CHAIN_TX_PAYMENT_LEGS`, `CHAIN_TX_MAX_PAYMENT_COINS`,
252
+ `CHAIN_TX_MAX_SECONDS`, `CHAIN_TX_MAX_CLAIM_PERMISSION`,
253
+ `CHAIN_TX_REFUSAL_CODES`, `parseChainTxRefusal`, `stripHiddenCharacters`
254
+ (a raw id without control or invisible characters, the sanitizer's sets,
255
+ for technical facts), `sanitizePublishedText`; types
256
+ `ChainTxRefusalCode`, `ChainTxRefusal`,
257
+ `ChainTxLevel4MessageType`, `ChainTxLevel6MessageType`, one precise
258
+ `ChainTxMessage` member per type (role- and permission-dependent fields
259
+ narrow by `role` / `permission`), `ChainTxPayments` and the enum types.
260
+ - The operation JSON schema has one branch per type (33). The
261
+ `ixo.chain.tx.v1` branch grows from 3 366 to 29 711 characters of JSON
262
+ (the whole operation schema from 12 484 to 38 829). Runtimes should build
263
+ the model-facing schema only from the types the Hub offers. Cross-field
264
+ rules (dates, role-only options, distinct denoms, numeric maxima) are the
265
+ field parser's (`chainTxIssue`).
266
+ - Rollout order: Hub and website on 0.8.0 (nothing changes for callers at
267
+ levels 1-5; a Hub before 0.8.0 answers `?version=6` with
268
+ `400 invalid_request`), then gateways on 0.8.0 (a 0.7.0 gateway cannot
269
+ parse a receipt with a new step type and drops the outcome), then runtimes
270
+ on `?version=6`.
271
+
3
272
  ## 0.7.0
4
273
 
5
274
  Two operation kinds for reviewed submissions the person makes on a claim
package/README.md CHANGED
@@ -28,6 +28,10 @@ Callers declare the envelope version they parse with `?version=2` on
28
28
  (`ixo.bid.submit.v1`, `ixo.claim.submit.v1`) and their receipts. Callers
29
29
  below 5 never see the kinds and get `400 protocol_version_required` for
30
30
  them.
31
+ - `?version=6` (0.8.0): level 5 plus 29 more `ixo.chain.tx.v1` message types
32
+ (`chainTxMessageTypesForLevel(6)`). Callers at levels 4 and 5 see and may
33
+ create only the four 0.6.0 types (`CHAIN_TX_LEVEL4_MESSAGE_TYPES`); a
34
+ `POST` naming a newer type answers `400 protocol_version_required`.
31
35
 
32
36
  ## Applications and claims (`ixo.bid.submit.v1`, `ixo.claim.submit.v1`, 0.7.0)
33
37
 
@@ -97,10 +101,21 @@ plain words, ticks a box, and signs once; the steps run as one transaction
97
101
  | `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
102
  | `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
103
 
100
- - Authorization: the Hub wraps each claims message in
104
+ Level 6 (0.8.0) adds 29 types: impact token retirement, staking (stake,
105
+ unstake, move stake, claim rewards), governance votes, claim reservations
106
+ and disputes, collection management (create; open/pause/close; dates; claim
107
+ limit; payments; authorize an agent or evaluator), entities (create, update
108
+ dates, add an account, grant or revoke an admin-account permission) and
109
+ identity document links (add or remove a service, linked resource, linked
110
+ claim, linked entity or context). `CHANGELOG.md` 0.8.0 lists each type and
111
+ its keys; `index.d.ts` `ChainTxMessage` has the exact shapes and rules.
112
+
113
+ - Authorization: the Hub wraps each message that runs under the collection
114
+ admin's authorization in
101
115
  `/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
116
+ MsgExec per such message): `ixo.claims.submit`, `ixo.claims.evaluate`
117
+ and, from 0.8.0, the five collection changes (state, dates, quota,
118
+ payments, create-claim-authorization). Every other message is signed
104
119
  directly.
105
120
  - Validation: `chainTxIssue(operation)` names the first bad field the way
106
121
  the Hub's `400 operation_not_registered` `reason` does
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ixo/action-protocol",
3
- "version": "0.7.0",
3
+ "version": "0.8.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": {