@minca/core 0.1.17 → 0.2.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/README.md +2 -1
- package/dist/files/space-files.d.ts +2 -2
- package/dist/files/space-files.d.ts.map +1 -1
- package/dist/files/space-files.js +7 -5
- package/dist/files/space-files.js.map +1 -1
- package/dist/inbox/names.d.ts +1 -1
- package/dist/inbox/names.js +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/node/actions.d.ts +3 -0
- package/dist/node/actions.d.ts.map +1 -1
- package/dist/node/actions.js.map +1 -1
- package/dist/node/api.d.ts +1 -0
- package/dist/node/api.d.ts.map +1 -1
- package/dist/node/api.js +1 -0
- package/dist/node/api.js.map +1 -1
- package/dist/node/carrier.js +1 -1
- package/dist/node/carrier.js.map +1 -1
- package/dist/node/index.d.ts +1 -1
- package/dist/node/index.d.ts.map +1 -1
- package/dist/node/node-contacts.d.ts.map +1 -1
- package/dist/node/node-contacts.js +1 -0
- package/dist/node/node-contacts.js.map +1 -1
- package/dist/node/node-records.d.ts.map +1 -1
- package/dist/node/node-records.js +6 -1
- package/dist/node/node-records.js.map +1 -1
- package/dist/node/node.d.ts.map +1 -1
- package/dist/node/node.js +13 -1
- package/dist/node/node.js.map +1 -1
- package/dist/node/remote.d.ts.map +1 -1
- package/dist/node/remote.js +7 -1
- package/dist/node/remote.js.map +1 -1
- package/dist/node/space-runtime.d.ts +5 -3
- package/dist/node/space-runtime.d.ts.map +1 -1
- package/dist/node/space-runtime.js +3 -1
- package/dist/node/space-runtime.js.map +1 -1
- package/dist/node/types.d.ts +112 -36
- package/dist/node/types.d.ts.map +1 -1
- package/dist/node/watch-notifications.d.ts +6 -0
- package/dist/node/watch-notifications.d.ts.map +1 -1
- package/dist/node/watch-notifications.js +47 -9
- package/dist/node/watch-notifications.js.map +1 -1
- package/dist/query/types.d.ts +1 -0
- package/dist/query/types.d.ts.map +1 -1
- package/dist/query/types.js.map +1 -1
- package/dist/records/contract-builder.d.ts +22 -6
- package/dist/records/contract-builder.d.ts.map +1 -1
- package/dist/records/contract-builder.js.map +1 -1
- package/dist/schemas/automations.d.ts +6 -2
- package/dist/schemas/automations.d.ts.map +1 -1
- package/dist/schemas/automations.js.map +1 -1
- package/dist/schemas/connectors.d.ts +4 -3
- package/dist/schemas/connectors.d.ts.map +1 -1
- package/dist/schemas/connectors.js +4 -3
- package/dist/schemas/connectors.js.map +1 -1
- package/dist/schemas/library/media.js +1 -1
- package/dist/schemas/library/media.js.map +1 -1
- package/dist/session/account-hint.d.ts +2 -2
- package/dist/session/account-hint.d.ts.map +1 -1
- package/dist/session/account-hint.js +3 -3
- package/dist/session/account-hint.js.map +1 -1
- package/dist/session/auth.d.ts +7 -3
- package/dist/session/auth.d.ts.map +1 -1
- package/dist/session/auth.js.map +1 -1
- package/dist/session/connection.d.ts +18 -0
- package/dist/session/connection.d.ts.map +1 -1
- package/dist/session/connection.js +11 -0
- package/dist/session/connection.js.map +1 -1
- package/dist/session/index.d.ts +2 -2
- package/dist/session/index.d.ts.map +1 -1
- package/dist/session/index.js +2 -2
- package/dist/session/index.js.map +1 -1
- package/dist/storage/blob-store.d.ts +3 -0
- package/dist/storage/blob-store.d.ts.map +1 -1
- package/dist/types.d.ts +11 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/docs/README.md +86 -93
- package/docs/actions.md +213 -152
- package/docs/agents.md +198 -167
- package/docs/automations.md +296 -204
- package/docs/blueprints-and-guides.md +405 -311
- package/docs/bots.md +208 -134
- package/docs/building-an-app.md +86 -159
- package/docs/collections.md +248 -328
- package/docs/computed.md +112 -89
- package/docs/contacts.md +151 -112
- package/docs/contracts.md +299 -120
- package/docs/direct-messages.md +80 -65
- package/docs/inbox.md +138 -93
- package/docs/node.md +1081 -996
- package/docs/permissions.md +142 -0
- package/docs/proposing-collections.md +74 -55
- package/docs/query-format.md +150 -126
- package/docs/records-and-queries.md +205 -126
- package/docs/sign-in.md +487 -416
- package/docs/spaces.md +261 -246
- package/docs/standard-library.md +487 -526
- package/docs/storage.md +325 -348
- package/docs/usernames.md +164 -97
- package/docs/warrants.md +100 -67
- package/package.json +1 -6
- package/dist/elements/auth-styles.d.ts +0 -18
- package/dist/elements/auth-styles.d.ts.map +0 -1
- package/dist/elements/auth-styles.js +0 -206
- package/dist/elements/auth-styles.js.map +0 -1
- package/dist/elements/dom.d.ts +0 -29
- package/dist/elements/dom.d.ts.map +0 -1
- package/dist/elements/dom.js +0 -91
- package/dist/elements/dom.js.map +0 -1
- package/dist/elements/index.d.ts +0 -13
- package/dist/elements/index.d.ts.map +0 -1
- package/dist/elements/index.js +0 -11
- package/dist/elements/index.js.map +0 -1
- package/dist/elements/minca-auth.d.ts +0 -55
- package/dist/elements/minca-auth.d.ts.map +0 -1
- package/dist/elements/minca-auth.js +0 -768
- package/dist/elements/minca-auth.js.map +0 -1
package/docs/contracts.md
CHANGED
|
@@ -1,22 +1,92 @@
|
|
|
1
1
|
# Contracts
|
|
2
2
|
|
|
3
|
-
A
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
3
|
+
A contract says when a version of a record counts. Use one when every app
|
|
4
|
+
must agree on something no single writer can be trusted with: a proposal
|
|
5
|
+
that passes only with enough votes, a move that must be legal, points that
|
|
6
|
+
can't be spent twice.
|
|
7
|
+
|
|
8
|
+
Here is a counter anyone may add to, but nobody can skip ahead:
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
import * as z from 'zod';
|
|
12
|
+
import { collection } from '@minca/core';
|
|
13
|
+
|
|
14
|
+
export const counter = collection({
|
|
15
|
+
name: 'app.counter',
|
|
16
|
+
schema: z.object({ count: z.number() }),
|
|
17
|
+
contract: {
|
|
18
|
+
check: ({ body, prev, when }) => ({
|
|
19
|
+
'The count goes up by one at a time': body.count.eq(when(prev.eq(null), 0, prev.body.count).add(1)),
|
|
20
|
+
}),
|
|
21
|
+
},
|
|
22
|
+
});
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Anyone can still write a version with `count: 100`. It just doesn't count:
|
|
26
|
+
every app reading the space skips it and shows the version before.
|
|
27
|
+
|
|
28
|
+
When a value only needs to look the same in every app, like a to-do that is
|
|
29
|
+
done once two people react, a [computed field](computed.md) is simpler.
|
|
30
|
+
|
|
31
|
+
## How a contract is judged
|
|
32
|
+
|
|
33
|
+
Grants say who may write, and [rules](collections.md#rules) say what a record
|
|
34
|
+
must keep to. Every peer enforces both, and refuses what breaks them. A
|
|
35
|
+
contract is different: readers judge it, and peers don't enforce it.
|
|
36
|
+
|
|
37
|
+
A version that fails its contract is kept and synced like any other. But
|
|
38
|
+
`get`, `list` and queries count only a record's newest version that passes.
|
|
39
|
+
One that fails is skipped, and the version before shows instead.
|
|
40
|
+
|
|
41
|
+
Your own node refuses to sign a version that fails, with the condition's
|
|
42
|
+
reason as the error. Another implementation could still send one, and no
|
|
43
|
+
reader would count it.
|
|
44
|
+
|
|
45
|
+
## Citing evidence
|
|
46
|
+
|
|
47
|
+
A contract never searches, because no device holds everything. The writer
|
|
48
|
+
does the work instead: it finds the votes, adds up the balances or picks the
|
|
49
|
+
move, and cites the versions that prove it. Every reader then checks that
|
|
50
|
+
exactly what was cited proves it. The example in
|
|
51
|
+
[Contracts](collections.md#contracts) on the collections page finds a
|
|
52
|
+
proposal's votes and cites them by version id.
|
|
53
|
+
|
|
54
|
+
A version citing one that hasn't arrived yet is pending, and doesn't count
|
|
55
|
+
until it does.
|
|
56
|
+
|
|
57
|
+
### What can be cited
|
|
58
|
+
|
|
59
|
+
Only versions kept whole can be cited, so every device reads the same thing
|
|
60
|
+
however late it joins:
|
|
61
|
+
|
|
62
|
+
- any version in a collection with `history: 'all'`,
|
|
63
|
+
- any version in a collection with a contract of its own, since the node
|
|
64
|
+
keeps those whole,
|
|
65
|
+
- the first version of a record under `onePer` or `fixed`.
|
|
66
|
+
|
|
67
|
+
A cited version must also pass its own contract. Give a collection you mean
|
|
68
|
+
to cite `history: 'all'`, or the latest version of an edited vote can't be
|
|
69
|
+
cited.
|
|
70
|
+
|
|
71
|
+
A citation proves what was signed, not that it is still current. Make
|
|
72
|
+
evidence final where it matters: `final: true` on a vote, so nobody can
|
|
73
|
+
change or delete it once it is counted, or `fixed: ['choice']` to allow
|
|
74
|
+
other edits.
|
|
75
|
+
|
|
76
|
+
### A proof stays a proof
|
|
77
|
+
|
|
78
|
+
A cited version is judged as of what the citing version saw. Removing a
|
|
79
|
+
voter later, or revoking the device that voted, doesn't undo a decision that
|
|
80
|
+
already counted the vote. A decision written after seeing the removal can't
|
|
81
|
+
count it. Peers keep such withdrawn versions, and the library reads them for
|
|
82
|
+
this without showing them.
|
|
12
83
|
|
|
13
84
|
## Writing one in TypeScript
|
|
14
85
|
|
|
15
86
|
Write `check` as a function in the collection. It gets the version's names,
|
|
16
|
-
typed from the collection's
|
|
17
|
-
|
|
18
|
-
condition.
|
|
19
|
-
SQL.
|
|
87
|
+
typed from the collection's schema, and returns an object. Each key is the
|
|
88
|
+
reason a version failing that condition doesn't count, and each value is the
|
|
89
|
+
condition. `define` turns it into CEL, the way a query builder writes SQL.
|
|
20
90
|
|
|
21
91
|
```ts
|
|
22
92
|
import * as z from 'zod';
|
|
@@ -56,55 +126,74 @@ That stores:
|
|
|
56
126
|
]
|
|
57
127
|
```
|
|
58
128
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
129
|
+
`body.` completes the collection's fields. `body.amont`, `body.to.eq(1)` and
|
|
130
|
+
a condition that gives a number are all type errors.
|
|
131
|
+
|
|
132
|
+
### Cited versions
|
|
133
|
+
|
|
134
|
+
`cited(ids, collection)` reads the versions cited by `ids` that are in
|
|
135
|
+
`collection`, typed from its schema, so `r.body.emojii` is a type error too.
|
|
136
|
+
Versions of any other collection are left out, so nothing can be cited in
|
|
137
|
+
their place.
|
|
138
|
+
|
|
139
|
+
When citing anything else should fail the version instead, use
|
|
140
|
+
`versions(ids)`. It is untyped until `.of(collection)`, and you test
|
|
141
|
+
`collection` yourself.
|
|
142
|
+
|
|
143
|
+
### What it reads
|
|
144
|
+
|
|
145
|
+
`check` gets a [`ContractContext`](https://minca.dev/api/core/interfaces/ContractContext/):
|
|
146
|
+
the version's fields, like `body` and `prev`, and the functions it may call,
|
|
147
|
+
like `cited` and `member`.
|
|
148
|
+
|
|
149
|
+
Each value has the methods of its type:
|
|
150
|
+
[numbers](https://minca.dev/api/core/interfaces/NumExpr/),
|
|
151
|
+
[ints](https://minca.dev/api/core/interfaces/IntExpr/),
|
|
152
|
+
[bools](https://minca.dev/api/core/interfaces/BoolExpr/),
|
|
153
|
+
[strings](https://minca.dev/api/core/interfaces/StrExpr/),
|
|
154
|
+
[lists](https://minca.dev/api/core/interfaces/ListExpr/) and
|
|
155
|
+
[versions](https://minca.dev/api/core/interfaces/VersionExpr/).
|
|
156
|
+
|
|
157
|
+
Literals take the kind CEL needs. A body's numbers are doubles and a size is
|
|
158
|
+
an int, so `body.amount.gte(0)` writes `0.0` and `list.count().gte(5)` writes
|
|
159
|
+
`5`. A fraction where an int is needed throws.
|
|
160
|
+
|
|
161
|
+
### Writing CEL by hand inside the builder
|
|
162
|
+
|
|
163
|
+
`raw(cel)` covers what the builder can't express, like map literals,
|
|
164
|
+
indexing a map, and `.map` with a filter (`map(x, p, t)`). For a field of an
|
|
165
|
+
untyped value named like a method, use `.get('size')`.
|
|
166
|
+
|
|
167
|
+
### Each reason once
|
|
168
|
+
|
|
169
|
+
Two conditions under the same reason are one key, and the later replaces the
|
|
170
|
+
earlier. The contract silently loses a condition. Give each its own reason,
|
|
171
|
+
or join them with `and`.
|
|
172
|
+
|
|
173
|
+
`define` throws when what it builds isn't a condition it would accept, and
|
|
174
|
+
says why.
|
|
175
|
+
|
|
176
|
+
### One condition on its own
|
|
177
|
+
|
|
178
|
+
[`contract(schema, that, else)`](https://minca.dev/api/core/functions/contract/)
|
|
179
|
+
builds a single condition outside a collection, to share between several. It
|
|
180
|
+
gives the `{ that, else }` that a `check` list holds.
|
|
99
181
|
|
|
100
182
|
## Writing it by hand
|
|
101
183
|
|
|
102
|
-
A condition is a CEL string, and a hand-written
|
|
184
|
+
A condition is a CEL string, and a hand-written list is stored the same way:
|
|
103
185
|
|
|
104
186
|
```ts
|
|
105
|
-
|
|
187
|
+
import * as z from 'zod';
|
|
188
|
+
|
|
189
|
+
await node.collections.define(space.id, {
|
|
106
190
|
name: 'app.pay',
|
|
107
|
-
schema:
|
|
191
|
+
schema: z.object({
|
|
192
|
+
to: z.string(),
|
|
193
|
+
amount: z.number(),
|
|
194
|
+
balance: z.number(),
|
|
195
|
+
received: z.array(z.string()),
|
|
196
|
+
}),
|
|
108
197
|
contract: {
|
|
109
198
|
check: [
|
|
110
199
|
{
|
|
@@ -116,84 +205,174 @@ await node.collections.define(space, {
|
|
|
116
205
|
line: { once: ['received'] },
|
|
117
206
|
},
|
|
118
207
|
});
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
A contract sits in the definition's `contract`, apart from its `rules`. Peers
|
|
211
|
+
check `rules` and refuse `check` there. They never read `contract`. Its type
|
|
212
|
+
is [`CollectionContract`](https://minca.dev/api/core/interfaces/CollectionContract/).
|
|
213
|
+
|
|
214
|
+
## The language
|
|
215
|
+
|
|
216
|
+
A condition is a [CEL](https://cel.dev) expression. CEL is the Common
|
|
217
|
+
Expression Language that Kubernetes, Firebase and Envoy use for policies.
|
|
218
|
+
|
|
219
|
+
A condition reads `body`, `links`, `key`, `seq`, `collection`, `author` (the
|
|
220
|
+
account), `creator`, `createdAt` and `prev` (the version before, or `null`).
|
|
221
|
+
It has:
|
|
222
|
+
|
|
223
|
+
- CEL's operators, `has()`, and the macros `all`, `exists`, `exists_one`,
|
|
224
|
+
`filter` and `map`
|
|
225
|
+
- `size`, `contains`, `startsWith` and `endsWith`
|
|
226
|
+
- the conversions `int`, `uint`, `double`, `string` and `bool`
|
|
227
|
+
- from CEL's extensions, `distinct()`, `math.greatest` and `math.least`
|
|
228
|
+
- from Minca, `sum(list)`, `hash(x)`, `link("rel")` and `v.link("rel")`
|
|
229
|
+
- two that ask the space: `versions(ids)` reads cited versions by id, and
|
|
230
|
+
`member(did)`
|
|
231
|
+
|
|
232
|
+
Bytes, timestamps, durations, regular expressions and types as values are
|
|
233
|
+
left out.
|
|
234
|
+
|
|
235
|
+
### Things to know
|
|
236
|
+
|
|
237
|
+
- A body's numbers are doubles, as JSON's are, and a literal like `1` is an
|
|
238
|
+
int. They compare freely, but don't mix in arithmetic. Write
|
|
239
|
+
`body.n + 1.0`, or `int(body.n) + 1`.
|
|
240
|
+
- Reading a field that isn't there is an error, not `null`. Ask
|
|
241
|
+
`has(body.note)` first. `&&` and `||` let an error pass when the other side
|
|
242
|
+
decides.
|
|
243
|
+
- A condition holds only when it gives `true`.
|
|
244
|
+
- A condition always ends. Its only loops are over lists in hand, and there
|
|
245
|
+
is a step limit.
|
|
246
|
+
|
|
247
|
+
### Cost
|
|
248
|
+
|
|
249
|
+
A condition that goes over its limits is refused, so one that passes on
|
|
250
|
+
small records can fail on large ones.
|
|
251
|
+
[`contractCostHints(check)`](https://minca.dev/api/core/functions/contractCostHints/) flags what
|
|
252
|
+
makes a condition grow costly: macros nested three deep, or `versions()`
|
|
253
|
+
called inside a macro. It is advice only, and no verdict depends on it.
|
|
119
254
|
|
|
120
|
-
|
|
121
|
-
|
|
255
|
+
The exact subset and its limits are in [spec 09](../../../spec/09-contracts.md).
|
|
256
|
+
|
|
257
|
+
## Lines
|
|
258
|
+
|
|
259
|
+
A line is one account's sequence of versions in a collection. A collection
|
|
260
|
+
whose contract has `line: { once: [...] }` gives each account one line, at
|
|
261
|
+
`lineKey(account, collection)`. Each version names the account's previous
|
|
262
|
+
one, so a payment can carry a running balance its contract checks.
|
|
263
|
+
|
|
264
|
+
```ts
|
|
265
|
+
import { lineKey } from '@minca/core';
|
|
266
|
+
|
|
267
|
+
// The first payment starts this account's line, at its line key.
|
|
268
|
+
// Each one after is the line's next version.
|
|
122
269
|
const line = await lineKey(node.did, 'app.pay');
|
|
123
|
-
await node.records.put(
|
|
124
|
-
|
|
270
|
+
await node.records.put(
|
|
271
|
+
space.id,
|
|
272
|
+
'app.pay',
|
|
273
|
+
{ to: did, amount: 30, balance: -30, received: [] },
|
|
274
|
+
{ key: line },
|
|
275
|
+
);
|
|
276
|
+
await node.records.update(space.id, line, { to: did, amount: 20, balance: -50, received: [] });
|
|
125
277
|
```
|
|
126
278
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
279
|
+
Two versions after the same one are a double spend. Neither counts, and
|
|
280
|
+
nothing after either does. There is no way back, so keep a line on one
|
|
281
|
+
device at a time.
|
|
282
|
+
|
|
283
|
+
Each citation in a `once` field may appear only once along the line. That is
|
|
284
|
+
what stops one payment received from being counted twice.
|
|
285
|
+
|
|
286
|
+
The exact rule is in [spec 09 §7](../../../spec/09-contracts.md#7-lines).
|
|
131
287
|
|
|
132
288
|
## Checked against the schema when defined
|
|
133
289
|
|
|
134
290
|
`collections.define` reads every condition, built or hand-written, against
|
|
135
|
-
the collection's JSON Schema
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
- a field an object doesn't declare
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
291
|
+
the collection's JSON Schema. It refuses one it can show is a mistake, and
|
|
292
|
+
says where:
|
|
293
|
+
|
|
294
|
+
- a field an object doesn't declare, like `body.amont` or
|
|
295
|
+
`prev.body.balanse`
|
|
296
|
+
- a comparison that is never equal or always an error, like a string with a
|
|
297
|
+
number: `body.n > "1"`
|
|
298
|
+
- arithmetic that is always an error, like `body.n + 1`, since a body's
|
|
299
|
+
numbers are doubles (write `1.0`)
|
|
300
|
+
- a value used where it can't be: `versions(body.game)` on a string, `sum()`
|
|
301
|
+
of strings, `size()` of a number, `&&` or `||` with no bool side, a field
|
|
302
|
+
of a string, or a condition that gives anything but a bool
|
|
303
|
+
|
|
304
|
+
This is stricter than JSON Schema in one way. An object without
|
|
305
|
+
`additionalProperties` counts as closed, as a Zod object writes it. To read a
|
|
306
|
+
field the schema doesn't declare, say other fields may be there:
|
|
307
|
+
`additionalProperties: {}` or a schema, as `z.looseObject` and `.catchall()`
|
|
308
|
+
write it.
|
|
309
|
+
|
|
310
|
+
It can't catch:
|
|
311
|
+
|
|
312
|
+
- a missing optional field (ask `has()`)
|
|
313
|
+
- anything read from a cited version, since a cited body is untyped to it
|
|
314
|
+
- a cited version of the wrong collection
|
|
315
|
+
- values out of range
|
|
316
|
+
- whatever `dyn()`, or a schema it can't follow (no `type`, a mix of types),
|
|
317
|
+
hides
|
|
318
|
+
|
|
319
|
+
A number's `integer` type reads as a double, as CEL reads JSON. A sum of
|
|
320
|
+
ints is untyped, since `sum([])` is `0.0`.
|
|
321
|
+
|
|
322
|
+
This check is the library's care, not protocol. A definition from another
|
|
323
|
+
writer that it would refuse still stands, and readers judge it by spec 09.
|
|
324
|
+
|
|
325
|
+
## Patterns
|
|
326
|
+
|
|
327
|
+
- **Quorums and multisig.** "Three members approved": cite the approvals, and
|
|
328
|
+
check `distinct()` authors with `member(v.author)`. Who may approve at all
|
|
329
|
+
is the grant on the approvals' collection.
|
|
330
|
+
- **State machines.** Check each version against `prev`. A task moves from
|
|
331
|
+
`open` to `done` only, a counter goes up by one, a chess move is legal from
|
|
332
|
+
the board before. Each step is small, and there is no limit on steps.
|
|
333
|
+
- **Ledgers.** A transfer cites the balance records it spends, and checks
|
|
334
|
+
that they are the sender's and add up. Two spends of one balance are two
|
|
335
|
+
versions of it, which everyone sees.
|
|
336
|
+
- **Commit, then reveal.** A player first writes `hash` of a secret, then
|
|
337
|
+
reveals it: `hash(body.secret) == "<the commitment>"`. Shared dice,
|
|
338
|
+
lotteries and sealed bids need nothing else.
|
|
339
|
+
- **Closing a set.** A contract can prove that something exists, not that
|
|
340
|
+
nothing else does. For "a majority" or "nobody objected", someone granted
|
|
341
|
+
it signs a record that closes the vote and lists what counts, and the
|
|
342
|
+
result cites that.
|
|
343
|
+
- **Time.** There is no clock. "Before Friday" is a record from someone
|
|
344
|
+
trusted to say it, like a host or a witness, that the result cites.
|
|
345
|
+
|
|
346
|
+
The standard library has two ready-made: `std.decision`, a proposal decided
|
|
347
|
+
by a quorum of ballots, and `std.goal-reached`, a goal reached by pledges
|
|
348
|
+
([standard library](standard-library.md)).
|
|
159
349
|
|
|
160
350
|
## How the library reads them
|
|
161
351
|
|
|
162
|
-
- **Counted only when it passes.** `get`, `list`, `linked`, queries and
|
|
163
|
-
counts, automations and notifications count only versions that pass
|
|
164
|
-
lists every version and gives a failing one its reason.
|
|
165
|
-
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
contract before signing it, and throws with the condition's `else` when it
|
|
173
|
-
fails, when a version it cites hasn't arrived, or when it would be a double
|
|
174
|
-
spend. Another implementation, or a writer that signs anyway, can still
|
|
175
|
-
send one: every peer keeps it, and no reader counts it.
|
|
352
|
+
- **Counted only when it passes.** `get`, `list`, `linked`, queries and
|
|
353
|
+
their counts, automations and notifications count only versions that pass.
|
|
354
|
+
`history` lists every version, and gives a failing one its reason.
|
|
355
|
+
- **Asking how a version fares.**
|
|
356
|
+
[`node.records.contracts`](https://minca.dev/api/core/interfaces/NodeRecords/)
|
|
357
|
+
says how the record's newest standing version fares, or the version named.
|
|
358
|
+
- **The writer refuses its own failing version.** The node judges a
|
|
359
|
+
version's contract before signing it. It throws with the condition's `else`
|
|
360
|
+
when the version fails, when a version it cites hasn't arrived, or when it
|
|
361
|
+
would be a double spend.
|
|
176
362
|
- **Kept whole.** The node sets `retain` on every version of a collection
|
|
177
|
-
under a contract or a line
|
|
178
|
-
writers.
|
|
363
|
+
under a contract or a line, apart from deletes.
|
|
179
364
|
- **Pending, read again.** A version waiting on one it cites is judged again
|
|
180
|
-
whenever anything arrives, for up to **256** records at a time
|
|
181
|
-
that,
|
|
182
|
-
cached.
|
|
365
|
+
whenever anything arrives, for up to **256** records at a time. Beyond
|
|
366
|
+
that, it waits until the space's index is next rebuilt. Only a pass or a
|
|
367
|
+
fail is cached.
|
|
183
368
|
- **Double spends undo verdicts.** A version arriving in a line collection
|
|
184
|
-
throws away every cached verdict in the space
|
|
185
|
-
payment a double spend, and every version citing
|
|
369
|
+
throws away every cached verdict in the space. It can make a counted
|
|
370
|
+
payment a double spend, and every version citing that payment fails with
|
|
371
|
+
it.
|
|
186
372
|
- **Defining.** `collections.define` refuses a contract outside the subset,
|
|
187
373
|
one that misreads its schema ([above](#checked-against-the-schema-when-defined)),
|
|
188
374
|
a `contract` with any key but `check` and `line`, and a `line` with any key
|
|
189
|
-
but `once
|
|
190
|
-
- **
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
large ones. Advice only: no verdict depends on it.
|
|
194
|
-
|
|
195
|
-
A line is checked by walking its counted chain for each version judged, so a
|
|
196
|
-
very long line costs time in proportion to its length squared, once; the
|
|
197
|
-
verdicts are cached.
|
|
198
|
-
|
|
199
|
-
_Source: `packages/core/src/records/contract-builder.ts` (`contract`, `buildChecks`, `storedContract`), `packages/core/src/records/cel-types.ts` (`typeCheckCel`, `typeOfSchema`), `packages/core/src/records/contracts.ts` (`checkContracts`, `checkContractShape`, `checkContractTypes`, `runContracts`, `contractCostHints`, `checkLine`), `packages/core/src/node/space-checks.ts` (`checksOf`, `lineBreak`, `counts`), `packages/core/src/node/space-writing.ts` (`contractsFor`, `after`, `write`), `packages/core/src/node/space-runtime.ts` (`recordsChanged`, `define`), `packages/core/src/node/node-records.ts` (`contracts`). Tests: `packages/core/tests/contract-builder.test.ts`, `packages/core/tests/contracts.test.ts`, `packages/core/tests/contracts-shape.test.ts`, `packages/core/tests/contracts-line.test.ts`, `packages/core/tests/contracts-pending.test.ts`, `packages/core/tests/contracts-reads.test.ts`, `scenarios/tests/fame.test.ts` and `scenarios/tests/credit.test.ts` (each case with the built contract and the hand-written one)._
|
|
375
|
+
but `once`.
|
|
376
|
+
- **Long lines.** A line is checked by walking its counted chain for each
|
|
377
|
+
version judged. A very long line costs time in proportion to its length
|
|
378
|
+
squared, once, and then the verdicts are cached.
|