@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 +415 -0
- package/README.md +35 -4
- package/package.json +1 -1
- package/src/index.d.ts +810 -4
- package/src/index.js +1101 -39
- package/src/operation-schema.js +392 -2
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
|
-
|
|
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
|
|
103
|
-
|
|
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
|
|
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.
|
|
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": {
|