@ixo/action-protocol 0.7.0 → 0.9.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,420 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.9.0
4
+
5
+ Four `ixo.chain.tx.v1` message types for groups (DAO DAO v2.0.3 groups with
6
+ single-choice proposals). Every existing shape is unchanged. The Hub offers
7
+ and accepts them only from callers that declare `?version=7` (wire level 7 =
8
+ level 6 + these 4 types; the envelope tags stay `ixo.auth-capabilities/2` /
9
+ `ixo.auth-outcome/2`), because every 0.6.0-0.8.0 parser refuses a
10
+ capabilities document, review step or receipt that names a type it does not
11
+ know. Design record: `docs/dao-actions-design.md`.
12
+
13
+ - `CHAIN_TX_MESSAGE_TYPES` (frozen) appends the four below (37). New
14
+ `CHAIN_TX_LEVEL6_MESSAGE_TYPES` (frozen, exactly the 33 of 0.8.0),
15
+ `CHAIN_TX_GROUP_MESSAGE_TYPES` (the four) and `CHAIN_TX_LEVEL7 = 7`.
16
+ `chainTxMessageTypesForLevel(level)`: none below 4, the four 0.6.0 types
17
+ at 4 and 5, the 33 at 6, all 37 from 7. The Hub must refuse a create whose
18
+ messages are not in the caller's list with `400 protocol_version_required`,
19
+ before `chainTxIssue` (which accepts all 37).
20
+ - The person signs each of them directly. `dao` is the group's own contract
21
+ and `proposalModule` the group's proposal list the step acts on (a group
22
+ may have several; the Hub proves it is an enabled part of `dao` and works
23
+ out where new proposals are handed in from it):
24
+ - `daodao.proposal.vote` (`dao`, `proposalModule`, `proposalId`, `vote`
25
+ `yes` | `no` | `abstain`, `rationale?`): casts the person's vote on a
26
+ group proposal, with an optional reason published alongside it.
27
+ - `daodao.proposal.execute` (`dao`, `proposalModule`, `proposalId`):
28
+ carries out a proposal that passed: the group's own account then does
29
+ what the proposal says.
30
+ - `daodao.proposal.close` (`dao`, `proposalModule`, `proposalId`): closes
31
+ a proposal that did not pass (its deposit may go to the group rather than
32
+ back to the person who proposed it; the review says which).
33
+ - `daodao.proposal.create` (`dao`, `proposalModule`, `title`,
34
+ `description`, `actions`): asks the group to vote on a new proposal. The
35
+ Hub adds the group's deposit, if it has one, from the person's wallet.
36
+ `actions` (0..4, `CHAIN_TX_MAX_GROUP_ACTIONS`; `[]` = asks for
37
+ agreement only) is what the group's own account does if it passes. Each
38
+ action is exactly a top-level message of one of
39
+ `CHAIN_TX_GROUP_ACTION_TYPES` (frozen, 14): `cosmos.bank.send`,
40
+ `ixo.token.transfer`, `ixo.token.retire`, the four staking and rewards
41
+ types, `cosmos.gov.vote`, `ixo.claims.update-collection-state`,
42
+ `ixo.claims.update-collection-dates`,
43
+ `ixo.claims.update-collection-quota`, `ixo.claims.create-collection`,
44
+ `ixo.entity.create-account` and `ixo.entity.revoke-account-authz`, with
45
+ the same keys and field rules. None of them has a field naming the
46
+ person: the Hub makes the group the actor of each. A dates change in a
47
+ proposal must give both `startDate` and `endDate` (`null` = no end): a
48
+ date left out would be read now and be stale when the group carries it
49
+ out. Everything else is refused by type (claims and disputes need the
50
+ person's own identity, entity create a relayer, identity document links
51
+ the document's own keys, and payments, grants and entity updates are
52
+ written whole from what the Hub reads now).
53
+ - Field rules (`chainTxIssue` names the first bad field, nested ones by path,
54
+ e.g. `invalid_message: messages[0].actions[2].toAddress`):
55
+ - `dao`, `proposalModule`: a 32-byte contract address, `ixo1` + 58 bech32
56
+ characters (the Hub checks the checksum);
57
+ - `proposalId`: decimal text without leading zeros, 1..9007199254740991
58
+ (the Hub writes it as a JSON number, so nothing beyond the safe integer
59
+ range);
60
+ - `title` 1..100, `description` 1..300, `rationale` 1..300: plain text
61
+ and SHOWN_AS_IS (the 0.8.0 rule: exactly what the review page shows, no
62
+ links, no hidden characters, single spaces, one line).
63
+ - One card, one group step: an operation holding a group step holds no
64
+ other message. Otherwise `invalid_operation: messages` (the shape refusal
65
+ used for 0 or 9 messages). Each group step depends on a chain of reads and
66
+ a new proposal's id must be unambiguous on the receipt.
67
+ - Review display (`parseChainTxDisplay`): `daodao.proposal.create` and
68
+ `daodao.proposal.execute` steps carry `actions` (required, `[]` for none;
69
+ refused on every other step): the group's actions in plain words, each
70
+ `{type, title (≤ 60), whatItDoes (≤ 160), facts (≤ 12, the step fact
71
+ shape), riskLevel, cannotUndo}`. On create: the operation's own actions, in
72
+ order and of the same types (`parseReviewView` checks). On carry-out: the
73
+ passed proposal's stored actions, at most 10
74
+ (`CHAIN_TX_MAX_SHOWN_GROUP_ACTIONS`), each of a level-6 type or `type:
75
+ null` for one the page cannot explain. A step's `riskLevel` is at least
76
+ each of its actions'. A `daodao.proposal.create` step may carry
77
+ `proposalPrefix` (1-4 capital letters; refused on every other step): the
78
+ proposal list's prefix, so a result names the new proposal as the cards
79
+ do ("proposal A4" from the receipt's `proposalId` "4").
80
+ - Receipts (`parseChainTxReceipt`): on a succeeded receipt (included, code
81
+ 0) a `daodao.proposal.create` step is `{type, proposalId}` (the new
82
+ proposal's id, or `null` when the Hub could not read it from the
83
+ transaction; never guessed) and a `daodao.proposal.execute` step is `{type,
84
+ groupActions}` (`"done"`, `"failed"`, or `"unknown"` when the Hub found no
85
+ proof either way in the transaction's events; the transaction succeeds
86
+ even when the group's actions fail, so code 0 alone does not say they
87
+ happened, and nothing reads `"unknown"` as done).
88
+ Every other step, and every step of a receipt that did not succeed, stays
89
+ `{type}`; `receiptFitsStatus` refuses either key outside `succeeded`.
90
+ - Capabilities accept the 37 types; the shape and `maxMessages` are
91
+ unchanged. The action types a proposal may hold are this package's
92
+ constant, not a capability.
93
+ - Refusal codes (`CHAIN_TX_REFUSAL_CODES`, appended; `parseChainTxRefusal`
94
+ also reads nested fields such as `actions[1].validatorAddress`). Reused:
95
+ `proposal_not_found`, `proposal_not_open` (voting has ended),
96
+ `chain_data_too_large` (the stored proposal is too large to show). New:
97
+ `group_not_supported` (`dao` / `proposalModule`: a group set up in a way a
98
+ card does not support yet: other contract versions, multiple choice, an
99
+ approval step), `not_in_group` (that proposal list is not an active part
100
+ of the group), `group_paused` (carrying out a proposal with actions while
101
+ the group is paused), `no_voting_power` (the person had no vote
102
+ when the proposal started), `already_voted` (and the group does not allow
103
+ changing votes), `same_vote` (field `vote`), `not_a_member` (`proposalId`
104
+ on carry-out, `dao` on create), `proposal_not_passed`,
105
+ `proposal_not_rejected` (only proposals that did not pass can be closed),
106
+ `group_actions_would_fail` (carried out now, the group's actions would fail
107
+ and the proposal would be marked failed for good), `deposit_not_supported`
108
+ (the deposit is in a token a card cannot pay), `proposal_too_large` (field
109
+ `description`), `not_for_groups` (`actions[<j>].type`), `not_group_owned`
110
+ (`actions[<j>].entityId`: the group does not own that entity),
111
+ `group_not_found` (`dao` / `proposalModule`: no contract at that address,
112
+ or another kind of group contract, e.g. the two addresses swapped),
113
+ `list_disabled` (`proposalModule`: the group switched that proposal list
114
+ off, so nothing in it can be carried out), `closes_too_soon`
115
+ (`proposalId`: voting closes before the card could be signed),
116
+ `group_inactive` (`dao`: the group is not taking new proposals right
117
+ now), `deposit_changed` (`dao`: the group's deposit changed while the
118
+ card was being made; ask again). A nested
119
+ action's own refusals keep their codes under its path, e.g.
120
+ `messages[0].actions[1].validatorAddress: validator_not_found`.
121
+ `chainTxIssue` itself still never adds a code: a type a group cannot use is
122
+ the shape refusal `messages[0].actions[<j>].type`.
123
+ - Bounds this package chose where the design left them open: `dao` and
124
+ `proposalModule` must differ (field `proposalModule`); `rationale` may be
125
+ left out but not `null`.
126
+ - New exports: `CHAIN_TX_LEVEL6_MESSAGE_TYPES`, `CHAIN_TX_GROUP_MESSAGE_TYPES`,
127
+ `CHAIN_TX_LEVEL7`, `CHAIN_TX_GROUP_ACTION_TYPES`,
128
+ `CHAIN_TX_MAX_GROUP_ACTIONS`, `CHAIN_TX_MAX_SHOWN_GROUP_ACTIONS`,
129
+ `CHAIN_TX_GROUP_VOTE_OPTIONS`, `CHAIN_TX_GROUP_ACTION_RESULTS`; types
130
+ `ChainTxGroupMessageType`, `ChainTxGroupMessage`, `ChainTxLevel6Message`
131
+ (the 0.8.0 `ChainTxMessage`, which now also holds the group members),
132
+ `ChainTxGroupActionType`, `ChainTxGroupAction`, `ChainTxGroupVoteOption`,
133
+ `ChainTxGroupActionResult`, `ChainTxGroupActionDisplay`,
134
+ `ChainTxReceiptStep`.
135
+ - The operation JSON schema has one branch per group type, a nested action
136
+ schema built from the 14 allowed branches (dates with both keys
137
+ required), and `messages` is either one group step or 1..8 other
138
+ messages. The `ixo.chain.tx.v1` branch grows from 29 711 to 41 872
139
+ characters of JSON (the whole operation schema from 38 829 to 50 990).
140
+ The numeric proposal id maximum, SHOWN_AS_IS and `dao` ≠ `proposalModule`
141
+ are the field parser's.
142
+ - Rollout order (as 0.8.0): Hub and website on 0.9.0 (nothing changes for
143
+ callers at levels 1-6; a Hub before 0.9.0 answers `?version=7` with
144
+ `400 invalid_request`; an oracle reading a group card at level 4-6 gets
145
+ `receipt: null` and `outcome: null`), then gateways on 0.9.0 (a 0.8.0
146
+ gateway cannot parse a receipt with a group step and drops the outcome),
147
+ then runtimes on `?version=7`.
148
+
149
+ ## 0.8.0
150
+
151
+ 29 more message types for `ixo.chain.tx.v1` cards. Every existing shape is
152
+ unchanged. The Hub offers and accepts them only from callers that declare
153
+ `?version=6` (wire level 6 = level 5 + these 29 types; the envelope tags stay
154
+ `ixo.auth-capabilities/2` / `ixo.auth-outcome/2`), because every 0.6.0/0.7.0
155
+ parser refuses a capabilities document, review step or receipt that names a
156
+ type it does not know.
157
+
158
+ - `CHAIN_TX_MESSAGE_TYPES` (now frozen): the four 0.6.0 types, then the 29
159
+ below in this order (33). New `CHAIN_TX_LEVEL4_MESSAGE_TYPES` (frozen,
160
+ exactly the four) and `chainTxMessageTypesForLevel(level)`: none below 4,
161
+ the four at levels 4 and 5, all 33 from 6 (`CHAIN_TX_LEVEL6 = 6`). The Hub
162
+ uses it for capabilities and must refuse a create whose messages are not in
163
+ the caller's list with `400 protocol_version_required`, before
164
+ `chainTxIssue` (which accepts all 33). A Hub may still leave a type out of
165
+ what it offers.
166
+ - Tokens, staking and voting (the person signs directly):
167
+ - `ixo.token.retire` (`tokens`, `jurisdiction`, `reason`): uses up impact
168
+ tokens the person holds, for good (for example to offset). Token lines as
169
+ `ixo.token.transfer`; `jurisdiction` is `Global` or a country code with an
170
+ optional region and postal code (`KE`, `KE-30`, `ZA-WC 7700`); `reason`
171
+ is plain text up to 200, shown as is (below).
172
+ - `cosmos.staking.delegate` (`validatorAddress`, `amountBaseUnits`): stakes
173
+ IXO (always `uixo`) with a validator so it earns rewards. Takes the
174
+ amount from the wallet.
175
+ - `cosmos.staking.undelegate` (same keys): stops staking; the IXO comes back
176
+ after the unbonding period.
177
+ - `cosmos.staking.redelegate` (`fromValidatorAddress`,
178
+ `toValidatorAddress`, `amountBaseUnits`): moves stake to another
179
+ validator at once. The two validators must differ.
180
+ - `cosmos.distribution.withdraw-rewards` (`validatorAddress`): claims the
181
+ staking rewards earned with one validator.
182
+ - `cosmos.gov.vote` (`proposalId` ≥ 1, `option` `yes` | `no` | `abstain` |
183
+ `no_with_veto`): votes on a network proposal (gov v1); a later vote
184
+ replaces it.
185
+ - Claims:
186
+ - `ixo.claims.claim-intent` (`collectionId`, `agentDid`): sets a
187
+ collection's payment aside for a claim the person is about to file.
188
+ - `ixo.claims.dispute` (`claimId`, `collectionId`, `agentDid`, `reason`
189
+ `not_as_asked` | `not_delivered` | `check_wrong` | `other`, `evidence`
190
+ `{uri, type, proof, encrypted?}`): opens a dispute about a claim, or about
191
+ how it was checked (`check_wrong`). May take the collection's dispute
192
+ deposit. The evidence must already be stored (no storage tool yet).
193
+ - Collection changes, run under a permission from the collection's admin
194
+ account (MsgExec), each with `collectionId` and `adminAddress` (the Hub
195
+ checks it against the collection):
196
+ `ixo.claims.update-collection-state` (`state` `open` | `paused` |
197
+ `closed`): opens, pauses or closes a collection;
198
+ `ixo.claims.update-collection-dates` (`startDate?`, `endDate?` or `null`
199
+ for no end; at least one): changes when it takes claims;
200
+ `ixo.claims.update-collection-quota` (`maxClaims`, `"0"` = no limit):
201
+ changes how many claims it takes in total;
202
+ `ixo.claims.create-claim-authorization` (`granteeAddress`, `role`
203
+ `file-claims` | `check-claims`, `maxClaims` 1..10^9, `expiresAt?`,
204
+ `reservationSeconds?` for `file-claims`, `decideBefore?` for
205
+ `check-claims`, `creatorDid`): lets an account file or check claims in
206
+ it; `ixo.claims.update-collection-payments` (`payments`): changes what
207
+ it pays (legs left out keep what they pay).
208
+ - `ixo.claims.create-collection` (`entityId`, `protocolId`, `startDate`,
209
+ `endDate` or `null` (the key is required), `maxClaims`, `state`,
210
+ `reservations` `allow` | `deny` | `required`, `payments`): creates a
211
+ claim collection for an entity the person owns.
212
+ - `payments`: `{submission?, evaluation?, approval?, rejection?}`; a leg is
213
+ `{amount: [{denom, amountBaseUnits}] (0..4, distinct denoms),
214
+ payAfterSeconds? (0..31536000)}` and the approval leg may add
215
+ `networkSplit` (left out on an update: kept). On `create-collection` a
216
+ missing leg pays nothing. On `update-collection-payments` a missing leg
217
+ keeps exactly what it pays now (amounts, delay, paying account, any
218
+ CW20/CW1155 payments) and `{amount: []}` makes it pay nothing; the Hub
219
+ refuses to replace a leg that pays CW20/CW1155 tokens
220
+ (`token_payments_present`), which a card can neither show nor keep. No
221
+ CW20/CW1155 payments, deposits, penalties or adjudicators can be set.
222
+ - Entities (the person signs directly):
223
+ - `ixo.entity.create-account` (`entityId`, `name`): adds a named account
224
+ to an entity the person owns.
225
+ - `ixo.entity.update` (`entityId`, `startDate?`, `endDate?` or `null` to
226
+ clear it, at least one; `controllerDid`): changes when an entity is
227
+ active. There is no `status` (its meaning is defined by each app); the
228
+ Hub keeps status and credentials as they are.
229
+ - `ixo.entity.revoke-account-authz` / `ixo.entity.grant-account-authz`
230
+ (`entityId`, `granteeAddress`, `permission`; grant adds `collectionId`
231
+ and `maxClaims` (required for `file-claims`/`check-claims`, refused
232
+ otherwise), `reservationSeconds?`, `decideBefore?`, `expiresAt?`):
233
+ removes or gives a permission from the entity's admin account.
234
+ `permission` (`CHAIN_TX_ENTITY_PERMISSIONS`): `change-collection-state`,
235
+ `change-collection-dates`, `change-collection-quota`,
236
+ `change-collection-payments`, `authorize-claim-agents`, `file-claims`,
237
+ `check-claims`; nothing else can be granted through a card.
238
+ - `ixo.entity.create` (`entityType`, `profile?` `{serviceEndpoint (https),
239
+ proof}`, `protocolId?`, `startDate?`, `endDate?`, `ownerDid`): creates an
240
+ entity the person owns. The profile must already be stored.
241
+ - Identity document links (`did` is the document changed; the person's key
242
+ must be one of its authentication keys): `ixo.iid.add-service` /
243
+ `delete-service` (`service {id, type, serviceEndpoint}` / `serviceId`),
244
+ `add-linked-resource` / `delete-linked-resource` (`resource {id, type,
245
+ description, mediaType, serviceEndpoint, proof, encrypted, right?}` /
246
+ `resourceId`), `add-linked-claim` / `delete-linked-claim` (`claim {id,
247
+ type, description, serviceEndpoint, proof, encrypted, right?}` /
248
+ `claimId`), `add-linked-entity` / `delete-linked-entity` (`entity {id,
249
+ type, relationship, service?}` / `entityId`), `add-context` /
250
+ `delete-context` (`context {key, val}` / `key`): add or remove one link of
251
+ an entity's (or the person's own) identity document. What is already on
252
+ chain is accepted (checked against Portal and the live devnet documents):
253
+ - the id of an item to remove (`serviceId`, `resourceId`, `claimId`,
254
+ `entityId`, `key`; `ChainTxIidRemoveId`) is exactly what the document
255
+ holds, any 1..300 characters without whitespace or control characters
256
+ (Portal stored `#api` with no prefix, `{id}#ixo1…`, ids without `#`); the
257
+ Hub reads the document and refuses an id that is not there;
258
+ - a linked entity `id` is an IXO DID, an ixo account (20-byte) or contract
259
+ (32-byte) address, or Portal's `{id}#<address>`; `relationship` is
260
+ `^[A-Za-z][A-Za-z0-9_-]{0,63}$` (Portal writes `Governs`); `service` may
261
+ be `""` (none) or hold `:` (`did:cosmos:ixo`);
262
+ - an item id to add may hold `:` after `#` (Portal's `#app:<id>`), and an
263
+ item `type` may hold `+` (`application/vnd.ixo.design-pod+json`);
264
+ - a linked resource or claim may have an empty `proof`, `description`
265
+ (up to 300) or `right`, as Portal's app links and form templates do.
266
+ - Shared rules (`chainTxIssue` names the first bad field, nested ones by
267
+ path, e.g. `invalid_message: messages[0].payments.approval.amount[1].denom`):
268
+ validator addresses `ixovaloper1` + 38 bech32 characters; entity ids
269
+ `did:ixo:entity:` + 32 lowercase hex; dates RFC 3339 with `Z` or an
270
+ offset; uint64 numbers as decimal text without leading zeros; plain text
271
+ without control, zero-width or bidi characters; links `https://` or
272
+ `ipfs://` up to 300 characters.
273
+ - Free text published on chain is exactly what the review page shows
274
+ (SHOWN_AS_IS): a retirement `reason` and a linked resource's or claim's
275
+ `description` and `right` must satisfy `sanitizePublishedText(value) ===
276
+ value`: no control or invisible characters (soft hyphen, word joiners and
277
+ invisible operators, variation selectors, zero-width, bidi and tag
278
+ characters), no real link (a URL with a scheme, `www.`, an email address,
279
+ or a host followed by a path such as `pay.example/now`), single spaces and
280
+ no space at either end. A plain file name ("Annual Report.pdf") or a
281
+ version ("v2.0.1") is fine. Parser-only (the JSON schema does not express
282
+ it). Removes name an id only and are unaffected. New export
283
+ `sanitizePublishedText` (the same as `sanitizeSubmissionText` except that
284
+ only real links become `[link]`); the Hub shows these fields with it.
285
+ - `sanitizeSubmissionText` (and `stripHiddenCharacters`) also drop the
286
+ Unicode tag characters (U+E0000-E007F, which can carry text no one sees)
287
+ and the musical-symbol format characters (U+1D173-1D17A). The 0.7.0
288
+ receipt and view fields checked against the sanitizer (`receipt.message`,
289
+ `receipt.detail`, `view.collectionName`) are still checked against the
290
+ 0.7.0 rule, so receipts, outcomes and views stored before 0.8.0 keep
291
+ parsing; everything the 0.8.0 sanitizer makes passes that rule too. Signer-derived chain fields (owner,
292
+ delegator, voter, signer, agent/creator/controller/owner address) are never
293
+ wire keys; the Hub fills them from `signer`.
294
+ - Bounds this package chose where the design left them open (stricter, never
295
+ looser than the chain):
296
+ - dates must be real calendar dates and, in UTC, between
297
+ 1970-01-01T00:00:00Z and the end of year 9999 (what a protobuf Timestamp
298
+ holds the way the Hub encodes it);
299
+ - when both dates are on the wire, `endDate` must be after `startDate`
300
+ (collection dates, create collection, entity update, entity create);
301
+ with neither date on an update, the reason names `startDate`;
302
+ - plain text may not be blank;
303
+ - an `https://` link has a host and no user info (`https://a@b`), and no
304
+ link may contain whitespace, a backslash or a control character;
305
+ - an entity account `name` may not be `admin` in any letter case;
306
+ - `mediaType` is at most 128 characters;
307
+ - a linked entity's `service` (the design left it open) is `""`, a service
308
+ name or a reference to one: `^(?:(?:\{id\}|did:ixo:…)#)?[A-Za-z0-9._~:-]{1,64}$`
309
+ (Portal writes names such as `svc1` or `matrix`);
310
+ - every `collectionId` keeps the 0.6.0 rule (uint64, `"0"` allowed: the
311
+ Hub's collection read refuses a collection that does not exist).
312
+ - Review display (`parseChainTxDisplay`), receipts (`parseChainTxReceipt`)
313
+ and capabilities (`parseChainTxCapabilities`) accept the 33 types.
314
+ `step.transfer` stays for `cosmos.bank.send` only. `CHAIN_TX_MAX_MESSAGES`
315
+ stays 8 and the display limits are unchanged.
316
+ - Refusal codes (`CHAIN_TX_REFUSAL_CODES`, `ChainTxRefusalCode`,
317
+ `parseChainTxRefusal`): when the Hub will not make a card from what it read
318
+ on chain, or the node's simulation names one message, the 400 (`error`
319
+ `operation_not_registered` for a Hub read, `simulation_failed` for the
320
+ simulation) has `reason: "invalid_message: messages[<i>].<field>: <code>"`.
321
+ The prefix is the 0.6.0 shape, so a caller that matches
322
+ `^invalid_message: messages\[<i>\]\.` or shows the reason as quoted text
323
+ keeps working; a reason without `: <code>` is a shape the parser refused.
324
+ Map the code to your own words; treat an unknown code like none. Codes:
325
+ - staking and rewards: `validator_not_found` (no such validator),
326
+ `no_stake` (nothing staked with that validator), `stake_too_small` (more
327
+ than is staked), `same_validator`, `invalid_amount`,
328
+ `nothing_to_collect` (no rewards to collect);
329
+ - voting: `proposal_not_found`, `proposal_not_open` (not in its voting
330
+ period), `invalid_vote_option`;
331
+ - impact tokens: `token_not_found`;
332
+ - claims and collections: `collection_not_found`, `reservations_off` (the
333
+ collection takes no reservations), `reservation_exists` (one is already
334
+ held), `claim_not_found`, `claim_in_other_collection`, `wrong_admin` (not
335
+ the collection's admin account), `already_in_state` (the collection
336
+ already has that state), `start_date_missing` (no start date given or
337
+ set), `end_before_start`, `quota_below_count` (fewer than already
338
+ filed), `token_payments_present` (that leg pays CW20/CW1155 tokens);
339
+ - permissions: `ends_too_soon` (`expiresAt` before the link expires),
340
+ `deadline_too_soon` (`decideBefore` likewise), `current_permission_ends_too_soon`
341
+ (no `expiresAt` was given and the permission already there, whose end
342
+ would be kept, ends before the link expires: give an end date),
343
+ `unlimited_permission_exists` (an unlimited permission of this kind is
344
+ there; it has to be removed first), `other_permission_exists` (a
345
+ permission of another kind or from another admin is under that key),
346
+ `too_many_constraints` (the permission would hold more than 50
347
+ collection entries, the most a card keeps), `no_such_permission`
348
+ (nothing to remove),
349
+ `collection_of_other_entity`;
350
+ - entities and identity documents: `entity_not_found`,
351
+ `account_name_taken`, `document_not_found`, `nothing_to_remove`,
352
+ `already_exists`, `invalid_did` (an identifier the chain says is not a
353
+ valid DID; also on the 0.6.0 claim types);
354
+ - the card as a whole: `not_available` (this Hub does not offer this
355
+ message type here, e.g. `ixo.entity.create` on a deployment without a
356
+ relayer node; field `type`), `chain_data_too_large` (what the step must
357
+ keep from the chain, such as an entity's credentials or a collection's
358
+ payments, is too large to seal with a card).
359
+ - A grant that has expired (its end at or before now) counts as absent, as
360
+ the chain's own merge treats it (`GetAuthorization`): nothing of it is
361
+ kept, nothing is "already allowed", and removing it is `no_such_permission`.
362
+ - No new failure reason. A value the Hub read to build a message that changed
363
+ between review and signing (collection dates or payments, an entity, the
364
+ constraints a grant keeps or its end date, the dispute deposit, the item
365
+ being removed) is refused at `/sign` with the existing `409
366
+ review_changed`, now with `reason: "chain_changed"` (Hub to website; a
367
+ website that does not know it shows "The details changed"): the card is
368
+ withdrawn, nothing is sent, and the review page says that something it
369
+ depends on changed after the review and to ask for a fresh link. A read
370
+ that fails during that check is a retryable 503 (and the cron tries again
371
+ later; it never withdraws the card for it). The oracle gets `cancelled`,
372
+ as for any other withdrawn card. `CHAIN_TX_FAILURE_REASONS` is unchanged.
373
+ - An oracle reading `GET /operations/:id` at level 4/5 (a runtime rolled
374
+ back after it made a level-6 card) gets `receipt: null` and `outcome:
375
+ null` (the whole outcome, since a finished outcome must carry its receipt)
376
+ when the receipt names a new step type. Gateway reads are unchanged.
377
+ - Known limits (the chain decides at execution; the Hub cannot close them):
378
+ - between signing and inclusion (seconds) a claim filed under a permission
379
+ an entity grant keeps can have its used quota restored, because the
380
+ grant is written whole; the re-check before signing refuses any change
381
+ made earlier. Claim permissions added with
382
+ `ixo.claims.create-claim-authorization` are merged by the chain itself
383
+ and are not affected;
384
+ - collection payments and dates, and entity dates, are written whole: a
385
+ change someone else makes after the re-check and before inclusion is
386
+ overwritten;
387
+ - a dispute takes the collection's deposit as it is when the dispute is
388
+ recorded: the collection's owner can change the deposit, its token and
389
+ who decides after the re-check (`MsgDisputeClaim` has no cap). The review
390
+ says so;
391
+ - a permission that ends between the review and signing changes what an
392
+ entity grant keeps (an expired grant counts as absent): the card is
393
+ withdrawn as `chain_changed` and the person asks for a fresh link.
394
+ - New exports: `CHAIN_TX_VOTE_OPTIONS`, `CHAIN_TX_DISPUTE_REASONS`,
395
+ `CHAIN_TX_COLLECTION_STATES`, `CHAIN_TX_RESERVATION_MODES`,
396
+ `CHAIN_TX_CLAIM_ROLES`, `CHAIN_TX_ENTITY_PERMISSIONS`,
397
+ `CHAIN_TX_PAYMENT_LEGS`, `CHAIN_TX_MAX_PAYMENT_COINS`,
398
+ `CHAIN_TX_MAX_SECONDS`, `CHAIN_TX_MAX_CLAIM_PERMISSION`,
399
+ `CHAIN_TX_REFUSAL_CODES`, `parseChainTxRefusal`, `stripHiddenCharacters`
400
+ (a raw id without control or invisible characters, the sanitizer's sets,
401
+ for technical facts), `sanitizePublishedText`; types
402
+ `ChainTxRefusalCode`, `ChainTxRefusal`,
403
+ `ChainTxLevel4MessageType`, `ChainTxLevel6MessageType`, one precise
404
+ `ChainTxMessage` member per type (role- and permission-dependent fields
405
+ narrow by `role` / `permission`), `ChainTxPayments` and the enum types.
406
+ - The operation JSON schema has one branch per type (33). The
407
+ `ixo.chain.tx.v1` branch grows from 3 366 to 29 711 characters of JSON
408
+ (the whole operation schema from 12 484 to 38 829). Runtimes should build
409
+ the model-facing schema only from the types the Hub offers. Cross-field
410
+ rules (dates, role-only options, distinct denoms, numeric maxima) are the
411
+ field parser's (`chainTxIssue`).
412
+ - Rollout order: Hub and website on 0.8.0 (nothing changes for callers at
413
+ levels 1-5; a Hub before 0.8.0 answers `?version=6` with
414
+ `400 invalid_request`), then gateways on 0.8.0 (a 0.7.0 gateway cannot
415
+ parse a receipt with a new step type and drops the outcome), then runtimes
416
+ on `?version=6`.
417
+
3
418
  ## 0.7.0
4
419
 
5
420
  Two operation kinds for reviewed submissions the person makes on a claim
package/README.md CHANGED
@@ -28,6 +28,14 @@ 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`.
35
+ - `?version=7` (0.9.0): level 6 plus the four group types
36
+ (`CHAIN_TX_GROUP_MESSAGE_TYPES`, `chainTxMessageTypesForLevel(7)`).
37
+ Callers at level 6 see the 33 (`CHAIN_TX_LEVEL6_MESSAGE_TYPES`) and get
38
+ `400 protocol_version_required` for a group type.
31
39
 
32
40
  ## Applications and claims (`ixo.bid.submit.v1`, `ixo.claim.submit.v1`, 0.7.0)
33
41
 
@@ -97,10 +105,32 @@ plain words, ticks a box, and signs once; the steps run as one transaction
97
105
  | `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
106
  | `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
107
 
100
- - Authorization: the Hub wraps each claims message in
108
+ Level 6 (0.8.0) adds 29 types: impact token retirement, staking (stake,
109
+ unstake, move stake, claim rewards), governance votes, claim reservations
110
+ and disputes, collection management (create; open/pause/close; dates; claim
111
+ limit; payments; authorize an agent or evaluator), entities (create, update
112
+ dates, add an account, grant or revoke an admin-account permission) and
113
+ identity document links (add or remove a service, linked resource, linked
114
+ claim, linked entity or context). `CHANGELOG.md` 0.8.0 lists each type and
115
+ its keys; `index.d.ts` `ChainTxMessage` has the exact shapes and rules.
116
+
117
+ Level 7 (0.9.0) adds four group types (DAO DAO v2.0.3 groups, single-choice
118
+ proposals): `daodao.proposal.vote`, `daodao.proposal.execute` (carry out a
119
+ passed proposal), `daodao.proposal.close` (close one that did not pass) and
120
+ `daodao.proposal.create` (a new proposal with 0..4 `actions` the group's
121
+ own account does if it passes, each a top-level message of one of
122
+ `CHAIN_TX_GROUP_ACTION_TYPES`). A card with a group step holds only that
123
+ step. Create and carry-out steps show the group's `actions` on the review
124
+ display; a succeeded receipt names a new proposal's `proposalId` and says
125
+ whether a carry-out's `groupActions` were `done` or `failed` (the
126
+ transaction succeeds either way). `CHANGELOG.md` 0.9.0 has the rules.
127
+
128
+ - Authorization: the Hub wraps each message that runs under the collection
129
+ admin's authorization in
101
130
  `/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
131
+ MsgExec per such message): `ixo.claims.submit`, `ixo.claims.evaluate`
132
+ and, from 0.8.0, the five collection changes (state, dates, quota,
133
+ payments, create-claim-authorization). Every other message is signed
104
134
  directly.
105
135
  - Validation: `chainTxIssue(operation)` names the first bad field the way
106
136
  the Hub's `400 operation_not_registered` `reason` does
@@ -136,7 +166,8 @@ plain words, ticks a box, and signs once; the steps run as one transaction
136
166
  `expired_not_included` (never included), plus a plain `message` for the
137
167
  first two.
138
168
  - Receipt `ixo.chain.tx.v1`: `chainId`, `txHash`, `height`, `code`, `steps`
139
- (`[{type}]` in order). A `failed` receipt always has a `reason`:
169
+ (`[{type}]` in order; on a succeeded receipt a group create step adds
170
+ `proposalId` and a carry-out step `groupActions`). A `failed` receipt always has a `reason`:
140
171
  `check_tx_rejected` (never included; CheckTx code), `expired_not_included`
141
172
  (never included; code null) or `tx_failed` (included with code != 0), and
142
173
  may carry a plain `message` (≤ 240) to show the person.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ixo/action-protocol",
3
- "version": "0.7.0",
3
+ "version": "0.9.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": {