@wowok/skills 1.2.4 → 1.2.6
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 +34 -16
- package/dist/cli.js +6 -2
- package/dist/cli.js.map +1 -1
- package/dist/skills.d.ts +32 -1
- package/dist/skills.d.ts.map +1 -1
- package/dist/skills.js +63 -0
- package/dist/skills.js.map +1 -1
- package/dist/types.d.ts +8 -0
- package/dist/types.d.ts.map +1 -1
- package/examples/Insurance/Insurance.md +543 -475
- package/examples/MyShop/MyShop.md +865 -746
- package/examples/MyShop_Advanced/MyShop_Advanced.md +1520 -1376
- package/examples/ThreeBody_Signature/ThreeBody_Signature.md +891 -651
- package/examples/Travel/Travel.md +952 -848
- package/package.json +2 -2
- package/scripts/install.js +3 -17
- package/wowok-arbitrator/SKILL.md +18 -57
- package/wowok-auditor/SKILL.md +16 -12
- package/wowok-distill/SKILL.md +237 -0
- package/wowok-guard/SKILL.md +40 -354
- package/wowok-machine/SKILL.md +21 -127
- package/wowok-messenger/SKILL.md +14 -59
- package/wowok-onboard/SKILL.md +42 -12
- package/wowok-order/SKILL.md +20 -169
- package/wowok-output/SKILL.md +0 -10
- package/wowok-planner/SKILL.md +29 -9
- package/wowok-provider/SKILL.md +72 -32
- package/wowok-safety/SKILL.md +8 -80
- package/wowok-scenario/SKILL.md +70 -102
- package/wowok-tools/SKILL.md +68 -107
- package/references/glossary.ts +0 -297
- package/references/guard-scenario-ledger.md +0 -353
- package/references/guard-template-library.md +0 -481
- package/references/machine-design-reference.md +0 -398
- package/references/machine-scenario-ledger.md +0 -227
- package/references/machine-template-library.md +0 -522
- package/references/merchant-scenario-coordination.md +0 -383
- package/references/object-collaboration.md +0 -362
- package/references/onchain-constants.md +0 -81
- package/wowok-arbitrator/APPENDIX.md +0 -545
- package/wowok-auditor/APPENDIX.md +0 -487
- package/wowok-guard/APPENDIX.md +0 -430
- package/wowok-machine/APPENDIX.md +0 -407
- package/wowok-messenger/APPENDIX.md +0 -550
- package/wowok-onboard/APPENDIX.md +0 -502
- package/wowok-order/APPENDIX.md +0 -777
- package/wowok-output/APPENDIX.md +0 -575
- package/wowok-planner/APPENDIX.md +0 -726
- package/wowok-provider/APPENDIX.md +0 -455
- package/wowok-safety/APPENDIX.md +0 -565
- package/wowok-scenario/APPENDIX.md +0 -97
- package/wowok-scenario/MODE-DETAILS.md +0 -275
- package/wowok-tools/APPENDIX.md +0 -394
|
@@ -1,362 +0,0 @@
|
|
|
1
|
-
# Object Collaboration Reference
|
|
2
|
-
|
|
3
|
-
> Single authoritative reference for skills needing object collaboration, constraints, and capacity limits.
|
|
4
|
-
> Covers the 22-object collaboration DAG and boundary conditions.
|
|
5
|
-
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
## 1. 22-Object Collaboration DAG
|
|
9
|
-
|
|
10
|
-
### 1.1 Mermaid Diagram
|
|
11
|
-
|
|
12
|
-
```mermaid
|
|
13
|
-
graph TB
|
|
14
|
-
%% ── Core Layer ──
|
|
15
|
-
PERM[Permission<br/>R1 Required]
|
|
16
|
-
TREAS[Treasury<br/>R2 Required]
|
|
17
|
-
ALLOC[Allocation<br/>R3 Required]
|
|
18
|
-
SERV[Service<br/>R4 Required]
|
|
19
|
-
ORDER[Order<br/>Runtime]
|
|
20
|
-
PROG[Progress<br/>Runtime]
|
|
21
|
-
ARB[Arbitration<br/>C6 Optional]
|
|
22
|
-
|
|
23
|
-
%% ── Trust Layer ──
|
|
24
|
-
GUARD[Guard<br/>R5 Required]
|
|
25
|
-
MACH[Machine<br/>R6 Required]
|
|
26
|
-
PASS[Passport<br/>Runtime]
|
|
27
|
-
PROOF[Proof<br/>Runtime]
|
|
28
|
-
|
|
29
|
-
%% ── Data Layer ──
|
|
30
|
-
REPO[Repository<br/>C7 Optional]
|
|
31
|
-
DEMAND[Demand<br/>Phase 0]
|
|
32
|
-
REWD[Reward<br/>C8 Optional]
|
|
33
|
-
CONT[Contact<br/>C1 Conditional]
|
|
34
|
-
PERS[Personal<br/>C5 Conditional]
|
|
35
|
-
|
|
36
|
-
%% ── User Layer ──
|
|
37
|
-
REG[Registrar+Entity<br/>E9]
|
|
38
|
-
RES[Resource<br/>Tool]
|
|
39
|
-
PAY[Payment<br/>Funds]
|
|
40
|
-
ARBN[Arb Node<br/>Arbitration Node]
|
|
41
|
-
UTIL[Util<br/>Tool]
|
|
42
|
-
BRIDGE[Bridge<br/>Cross-chain]
|
|
43
|
-
|
|
44
|
-
%% ── Core Layer Dependencies ──
|
|
45
|
-
PERM --> TREAS
|
|
46
|
-
PERM --> ALLOC
|
|
47
|
-
PERM --> SERV
|
|
48
|
-
PERM --> ARB
|
|
49
|
-
TREAS --> ALLOC
|
|
50
|
-
ALLOC --> SERV
|
|
51
|
-
SERV --> ORDER
|
|
52
|
-
MACH --> ORDER
|
|
53
|
-
ORDER --> PROG
|
|
54
|
-
ORDER --> ARB
|
|
55
|
-
PROG --> ALLOC
|
|
56
|
-
|
|
57
|
-
%% ── Trust Layer Dependencies ──
|
|
58
|
-
PERM --> GUARD
|
|
59
|
-
GUARD --> MACH
|
|
60
|
-
GUARD --> PASS
|
|
61
|
-
MACH --> SERV
|
|
62
|
-
MACH --> PROG
|
|
63
|
-
PASS --> PROOF
|
|
64
|
-
PROOF --> ARB
|
|
65
|
-
|
|
66
|
-
%% ── Data Layer Dependencies ──
|
|
67
|
-
PERM --> REPO
|
|
68
|
-
GUARD --> REPO
|
|
69
|
-
REPO --> REWD
|
|
70
|
-
PERM --> REWD
|
|
71
|
-
GUARD --> REWD
|
|
72
|
-
REWD --> DEMAND
|
|
73
|
-
PERM --> DEMAND
|
|
74
|
-
GUARD --> DEMAND
|
|
75
|
-
PERM --> CONT
|
|
76
|
-
REG --> CONT
|
|
77
|
-
SERV --> CONT
|
|
78
|
-
PERS --> SERV
|
|
79
|
-
|
|
80
|
-
%% ── User Layer Dependencies ──
|
|
81
|
-
REG --> PERS
|
|
82
|
-
RES --> REG
|
|
83
|
-
PAY --> TREAS
|
|
84
|
-
PAY --> ALLOC
|
|
85
|
-
ARB --> ARBN
|
|
86
|
-
UTIL --> ALL[All Objects]
|
|
87
|
-
BRIDGE -.->|mainnet only| TREAS
|
|
88
|
-
|
|
89
|
-
%% ── Styles ──
|
|
90
|
-
classDef required fill:#ffeb3b,stroke:#f57f17,stroke-width:2px
|
|
91
|
-
classDef runtime fill:#81c784,stroke:#1b5e20,stroke-width:1px
|
|
92
|
-
classDef optional fill:#bbdefb,stroke:#0d47a1,stroke-width:1px
|
|
93
|
-
classDef tool fill:#eeeeee,stroke:#424242,stroke-width:1px,stroke-dasharray: 5 5
|
|
94
|
-
|
|
95
|
-
class PERM,TREAS,ALLOC,SERV,GUARD,MACH required
|
|
96
|
-
class ORDER,PROG,PASS,PROOF,ARB runtime
|
|
97
|
-
class REPO,DEMAND,REWD,CONT,PERS,REG,ARBN optional
|
|
98
|
-
class RES,PAY,UTIL,BRIDGE tool
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
### 1.2 ASCII Overview
|
|
102
|
-
|
|
103
|
-
```
|
|
104
|
-
[CORE LAYER - Merchant Build Pipeline]
|
|
105
|
-
Permission(1) ──┬──► Treasury(2) ──► Allocation(3) ──┐
|
|
106
|
-
│ │
|
|
107
|
-
├──► Service(4) ◄──────────────────────┘
|
|
108
|
-
│ │
|
|
109
|
-
│ ▼
|
|
110
|
-
│ Order(5) ──► Progress(6)
|
|
111
|
-
│ │ │
|
|
112
|
-
│ ▼ ▼
|
|
113
|
-
└──► Arbitration(7) ◄──┘
|
|
114
|
-
│
|
|
115
|
-
▼
|
|
116
|
-
Arb Node(17)
|
|
117
|
-
|
|
118
|
-
[TRUST LAYER - Workflow & Evidence]
|
|
119
|
-
Permission(1) ──► Guard ──┬──► Machine ──► Service(4)
|
|
120
|
-
│ │ │
|
|
121
|
-
│ ▼ ▼
|
|
122
|
-
│ Order(5) Progress(6)
|
|
123
|
-
│
|
|
124
|
-
└──► Passport(9) ──► Proof(10) ──► Arbitration(7)
|
|
125
|
-
|
|
126
|
-
[DATA LAYER - Strategy & Incentives]
|
|
127
|
-
Permission(1) ─┬──► Repository(11) ──► Reward(8) ──► Demand(12)
|
|
128
|
-
│ ▲ │
|
|
129
|
-
└──► Reward(8) ────────────┘ │
|
|
130
|
-
└──► Demand(12) ◄──────────────────────────┘
|
|
131
|
-
Guard ──► Repository(11)
|
|
132
|
-
Guard ──► Reward(8)
|
|
133
|
-
Guard ──► Demand(12)
|
|
134
|
-
|
|
135
|
-
[USER LAYER - Contact & Personal]
|
|
136
|
-
Permission(1) ──► Contact(13) ──► Service(4).um
|
|
137
|
-
Registrar+Entity(14) ──► Contact(13)
|
|
138
|
-
Registrar+Entity(14) ──► Personal(18) ──► Service(4).customer_required
|
|
139
|
-
|
|
140
|
-
[TOOL LAYER - Auxiliary]
|
|
141
|
-
Resource(15) ──► Registrar(14)
|
|
142
|
-
Payment(16) ──► Treasury(2) / Allocation(3)
|
|
143
|
-
Util(19) ──► All Objects
|
|
144
|
-
Bridge(20) ──► Treasury(2) (mainnet only)
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
### 1.3 Object Distribution by Layer
|
|
148
|
-
|
|
149
|
-
| Layer | Objects | Count | Role |
|
|
150
|
-
|-------|---------|-------|------|
|
|
151
|
-
| Core | Permission, Treasury, Allocation, Service, Order, Progress, Arbitration | 7 | Business pipeline |
|
|
152
|
-
| Trust | Guard, Machine, Passport, Proof | 4 | Workflow & evidence |
|
|
153
|
-
| Data | Repository, Reward, Demand | 3 | Strategy & incentives |
|
|
154
|
-
| User | Contact, Personal, Registrar+Entity | 3 | Contact & personal |
|
|
155
|
-
| Tool | Resource, Payment, Util, Bridge, Arb Node | 5 | Auxiliary |
|
|
156
|
-
| **Total** | | **22** | (includes Guard + Machine) |
|
|
157
|
-
|
|
158
|
-
### 1.4 Collaboration Types (5 Categories)
|
|
159
|
-
|
|
160
|
-
| Type | Meaning | Count | Example |
|
|
161
|
-
|------|---------|-------|---------|
|
|
162
|
-
| **CREATE** | A creates B (B is child of A) | 18 | Permission creates Service |
|
|
163
|
-
| **BIND** | A references B (B is a field of A) | 35 | Service.machine = Machine |
|
|
164
|
-
| **TRIGGER** | A triggers an operation on B | 12 | Order triggers Progress |
|
|
165
|
-
| **VALIDATE** | A validates B's state | 10 | Guard validates Service |
|
|
166
|
-
| **CONSUME** | A consumes B's output | 8 | Proof consumes Passport |
|
|
167
|
-
| **Total** | | **83** | |
|
|
168
|
-
|
|
169
|
-
### 1.5 Top 5 High-Frequency Collaboration Objects
|
|
170
|
-
|
|
171
|
-
| Rank | Object | In-degree | Out-degree | Total |
|
|
172
|
-
|------|--------|-----------|------------|-------|
|
|
173
|
-
| 1 | Permission | 13 | 0 | 13 |
|
|
174
|
-
| 2 | Guard | 9 | 8 | 17 |
|
|
175
|
-
| 3 | Service | 6 | 8 | 14 |
|
|
176
|
-
| 4 | Machine | 4 | 3 | 7 |
|
|
177
|
-
| 5 | Treasury | 4 | 2 | 6 |
|
|
178
|
-
|
|
179
|
-
Key observations:
|
|
180
|
-
- **Permission** is the highest in-degree object (13), the "gatekeeper" of all writes
|
|
181
|
-
- **Guard** is the highest out-degree object (8), the "validator"
|
|
182
|
-
- **Service** is the "hub" connecting merchant-side and user-side
|
|
183
|
-
|
|
184
|
-
### 1.6 Permission Reverse Reference (9 Objects with BuiltinPermissionIndex)
|
|
185
|
-
|
|
186
|
-
| Object | Index Range | Count | Usage |
|
|
187
|
-
|--------|------------|-------|-------|
|
|
188
|
-
| Repository | 100-105 | 6 | Repository operations |
|
|
189
|
-
| Reward | 150-157 | 8 | Reward operations |
|
|
190
|
-
| Machine | 200-208 | 8 | Machine operations |
|
|
191
|
-
| Progress | 220-225 | 6 | Progress operations |
|
|
192
|
-
| Treasury | 250-258 | 9 | Treasury operations |
|
|
193
|
-
| Service | 300-320 | 21 | Service operations |
|
|
194
|
-
| Arbitration | 350-368 | 19 | Arbitration operations |
|
|
195
|
-
| Demand | 400-408 | 9 | Demand operations |
|
|
196
|
-
| Contact | 450-454 | 5 | Contact operations |
|
|
197
|
-
|
|
198
|
-
Note: Permission and Order do NOT hold BuiltinPermissionIndex entries. Permission is the carrier referenced by other objects; Order references Permission indirectly through Service snapshot.
|
|
199
|
-
|
|
200
|
-
---
|
|
201
|
-
|
|
202
|
-
## 2. 5-Dimension Boundary Condition Model
|
|
203
|
-
|
|
204
|
-
```
|
|
205
|
-
┌─────────────────────────────────────────────────────────────────────┐
|
|
206
|
-
│ Object Boundary Condition 5-Dimension Model │
|
|
207
|
-
└─────────────────────────────────────────────────────────────────────┘
|
|
208
|
-
|
|
209
|
-
[1. Mutability] [2. Prerequisites] [3. Capacity Limits] [4. Permissions] [5. Irreversibility]
|
|
210
|
-
│ │ │ │ │
|
|
211
|
-
▼ ▼ ▼ ▼ ▼
|
|
212
|
-
Fields modifiable? What must exist Quantity limits? Operation Operations
|
|
213
|
-
before create permissions? irreversible?
|
|
214
|
-
or publish?
|
|
215
|
-
```
|
|
216
|
-
|
|
217
|
-
| Dimension | Meaning | Values |
|
|
218
|
-
|-----------|---------|--------|
|
|
219
|
-
| 1. Mutability | Whether fields can be modified after creation | `MUTABLE` / `IMMUTABLE_AFTER_PUBLISH` / `IMMUTABLE_AFTER_CREATE` / `FROZEN` |
|
|
220
|
-
| 2. Prerequisites | Conditions that must be met before create/operation | Object list + stage requirements |
|
|
221
|
-
| 3. Capacity Limits | Quantity/size upper bounds | Numeric constants |
|
|
222
|
-
| 4. Permissions | Permission index required for operations | Index value or `owner_only` |
|
|
223
|
-
| 5. Irreversibility | Whether operations can be undone | `REVERSIBLE` / `IRREVERSIBLE` |
|
|
224
|
-
|
|
225
|
-
---
|
|
226
|
-
|
|
227
|
-
## 3. Main Boundary Condition Table (All 22 Objects)
|
|
228
|
-
|
|
229
|
-
| Object | Mutability | Prerequisites | Capacity Limits | Permissions | Irreversibility |
|
|
230
|
-
|--------|-----------|---------------|-----------------|-------------|-----------------|
|
|
231
|
-
| Permission | permission list mutable | None | MAX_PERM_FOR_ENTITY=1000, MAX_ADMIN_COUNT=500 | owner_only | Adding index reversible |
|
|
232
|
-
| Treasury | external_guard/owner_receive/um mutable | Permission | — | owner + 250-258 | deposit/withdraw reversible |
|
|
233
|
-
| Allocation | permission/sharing mutable | Treasury + Permission | MAX_SHARING_COUNT=100 | owner + allocation_guard | allocate irreversible |
|
|
234
|
-
| Service | machine immutable after publish | Permission | MAX_ARBITRATION_COUNT=20 | owner + 300-320 | publish irreversible |
|
|
235
|
-
| Order | service/machine immutable | Service(published) + Machine(published) | MAX_AGENT_COUNT=10 (actual 11), MAX_DISPUTE_COUNT=10 | owner (via Service snapshot) | create irreversible |
|
|
236
|
-
| Progress | machine/order immutable | Order + Machine | — | owner + 220-225 | forward irreversible |
|
|
237
|
-
| Arbitration | permission mutable | Order + Permission | MAX_VOTING_GUARD_COUNT=50 | owner + 350-368 | ruling irreversible |
|
|
238
|
-
| Reward | permission/guard mutable | Repository + Permission | — | owner + 150-157 | distribution irreversible |
|
|
239
|
-
| Passport | — | Guard | Time bound | gen_passport | expiry irreversible |
|
|
240
|
-
| Proof | — | Passport | — | submitter | submission irreversible |
|
|
241
|
-
| Repository | permission/guard mutable | Permission | MAX_POLICY_COUNT=50, MAX_ID_COUNT_ONCE=100 | owner + 100-105 | write reversible |
|
|
242
|
-
| Demand | permission/guard/service mutable | Permission | MAX_GUARD_COUNT_DEMAND=20, MAX_FEEDBACK_COUNT=20 (SDK) | owner + 400-408 | present irreversible |
|
|
243
|
-
| Contact | permission mutable | Permission + Registrar | — | owner + 450-454 | message irreversible |
|
|
244
|
-
| Registrar | — | — | MAX_RECORD_COUNT_REGISTRAR=1000 | owner | registration irreversible |
|
|
245
|
-
| Entity | — | Registrar | — | registrar owner | registration irreversible |
|
|
246
|
-
| Resource | — | — | — | owner | create reversible (delete) |
|
|
247
|
-
| Payment | FROZEN | — | — | — | create = freeze |
|
|
248
|
-
| Arb Node | can exit | Arbitration | — | owner | join reversible (exit) |
|
|
249
|
-
| Personal | registrar immutable | Registrar | — | owner | create reversible (delete) |
|
|
250
|
-
| Util | — | — | — | — | Tool module |
|
|
251
|
-
| Bridge | — | — | — | owner | cross-chain irreversible |
|
|
252
|
-
| Guard | named_operator mutable | Permission | MAX_GUARD_COUNT_PASSPORT=20 | owner | gen_passport regenerable |
|
|
253
|
-
| Machine | permission mutable, nodes immutable after publish | Permission | MAX_NODE_COUNT_SDK=100, MAX_FORWARD_COUNT=20, MAX_FORWARD_ORDER_COUNT=20, MAX_NODE_PAIR_COUNT=40 | owner + 200-208 | publish irreversible |
|
|
254
|
-
|
|
255
|
-
### Key Observations
|
|
256
|
-
|
|
257
|
-
1. **Payment** is the only FROZEN object (created in terminal state)
|
|
258
|
-
2. **Service/Machine** are the only two objects with IMMUTABLE_AFTER_PUBLISH semantics
|
|
259
|
-
3. **Order/Progress/Arbitration** are runtime-irreversible objects
|
|
260
|
-
4. **Permission** is the central node, depended on by 9 objects
|
|
261
|
-
5. **Guard** has 3 different MAX_GUARD_COUNT constants (Demand/Passport=20, Reward=200)
|
|
262
|
-
|
|
263
|
-
---
|
|
264
|
-
|
|
265
|
-
## 4. Capacity Limits (On-Chain Constants)
|
|
266
|
-
|
|
267
|
-
| Constant | Value | Source | Applies To | Notes |
|
|
268
|
-
|----------|-------|--------|-----------|-------|
|
|
269
|
-
| `MAX_NODE_COUNT_ONCHAIN` | 200 | machine.move | Machine | On-chain limit |
|
|
270
|
-
| `MAX_NODE_COUNT_SDK` | 100 | onchain-constants.ts | Machine | SDK/MCP stricter |
|
|
271
|
-
| `MAX_FORWARD_COUNT` | 20 | machine.move | Machine | Forwards per Pair |
|
|
272
|
-
| `MAX_FORWARD_ORDER_COUNT` | 20 | machine.move | Machine | Forward order count |
|
|
273
|
-
| `MAX_NODE_PAIR_COUNT` | 40 | machine.move | Machine | Pairs per node |
|
|
274
|
-
| `USER_DEFINED_PERM_INDEX_START` | 1000 | permission.move | Permission | Custom permission start |
|
|
275
|
-
| `MAX_PERM_FOR_ENTITY` | 1000 | permission.move | Permission | Permissions per Entity |
|
|
276
|
-
| `MAX_ADMIN_COUNT` | 500 | permission.move | Permission | Admin count limit |
|
|
277
|
-
| `MAX_AGENT_COUNT` | 10 | order.move | Order | Actual 11 (off-by-one bug) |
|
|
278
|
-
| `MAX_DISPUTE_COUNT` | 10 | order.move | Order | Dispute count limit |
|
|
279
|
-
| `MAX_SHARING_COUNT` | 100 | allocation.move | Allocation | Sharing count limit |
|
|
280
|
-
| `MAX_VOTING_GUARD_COUNT` | 50 | arbitration.move | Arbitration | Voting guard limit |
|
|
281
|
-
| `MAX_POLICY_COUNT` | 50 | repository.move | Repository | Policy count limit |
|
|
282
|
-
| `MAX_ID_COUNT_ONCE` | 100 | repository.move | Repository | Single ID batch limit |
|
|
283
|
-
| `MAX_GUARD_COUNT_DEMAND` | 20 | demand.move | Demand | Guard count for Demand |
|
|
284
|
-
| `MAX_GUARD_COUNT_PASSPORT` | 20 | passport.move | Passport | Guard count for Passport |
|
|
285
|
-
| `MAX_GUARD_COUNT_REWARD` | 200 | reward.move | Reward | Guard count for Reward |
|
|
286
|
-
| `MAX_RECORD_COUNT_REWARD` | 5200 | reward.move | Reward | Records per recipient |
|
|
287
|
-
| `MAX_RECORD_COUNT_REGISTRAR` | 1000 | registrar.move | Registrar | Registrar record count |
|
|
288
|
-
| `MAX_REWARD_COUNT` | 20 | demand.move | Demand | Rewards per Demand |
|
|
289
|
-
| `MAX_CONTEXT_REPOSITORY_COUNT` | 30 | progress.move | Progress | Context repository count |
|
|
290
|
-
| `MAX_ARBITRATION_COUNT` | 20 | service.move | Service | Arbitrations per Service |
|
|
291
|
-
| `MAX_FEEDBACK_COUNT` | 20 | demand.ts (SDK) | Demand | SDK-only, no Move check |
|
|
292
|
-
| `DEFAULT_SETTING_LOCK_DURATION` | 2592000000 | service.move | Service | 30 days (ms) |
|
|
293
|
-
|
|
294
|
-
### MAX_GUARD_COUNT Name Collision
|
|
295
|
-
|
|
296
|
-
| Object | Value | Constant Name |
|
|
297
|
-
|--------|-------|--------------|
|
|
298
|
-
| Demand | 20 | MAX_GUARD_COUNT_DEMAND |
|
|
299
|
-
| Passport | 20 | MAX_GUARD_COUNT_PASSPORT |
|
|
300
|
-
| Reward | 200 | MAX_GUARD_COUNT_REWARD |
|
|
301
|
-
|
|
302
|
-
---
|
|
303
|
-
|
|
304
|
-
## 5. Key Observations
|
|
305
|
-
|
|
306
|
-
### 5.1 Irreversibility Summary
|
|
307
|
-
|
|
308
|
-
| Object | Operation | Irreversibility Reason | Recovery |
|
|
309
|
-
|--------|-----------|----------------------|----------|
|
|
310
|
-
| Service | publish | On-chain state irreversible | New Service |
|
|
311
|
-
| Machine | publish | On-chain state irreversible | New Machine |
|
|
312
|
-
| Order | create | On-chain record cannot be deleted | Wait for TERMINATED |
|
|
313
|
-
| Payment | create | freeze_object | Unrecoverable |
|
|
314
|
-
| Progress | forward | Node flow irreversible | Wait for terminal |
|
|
315
|
-
| Arbitration | dispute/execute | Dispute/verdict irreversible | Unrecoverable |
|
|
316
|
-
| Allocation | allocate | Fund allocation irreversible | Unrecoverable |
|
|
317
|
-
| Reward | claim | Reward distribution irreversible | Unrecoverable |
|
|
318
|
-
|
|
319
|
-
### 5.2 Service Field Mutability (Critical)
|
|
320
|
-
|
|
321
|
-
| Field | CONFIGURED | PUBLISHED | ACTIVE |
|
|
322
|
-
|-------|------------|-----------|--------|
|
|
323
|
-
| permission | MUTABLE | MUTABLE | MUTABLE |
|
|
324
|
-
| machine | MUTABLE | **IMMUTABLE** | **IMMUTABLE** |
|
|
325
|
-
| order_allocators | MUTABLE | — | MUTABLE |
|
|
326
|
-
| arbitrations | MUTABLE | — | MUTABLE |
|
|
327
|
-
| buy_guard | MUTABLE | — | MUTABLE |
|
|
328
|
-
| price | MUTABLE | — | MUTABLE |
|
|
329
|
-
| publish_state | — | **SET ONCE** | — |
|
|
330
|
-
|
|
331
|
-
**Critical constraint**: `Service.machine` is the only core field that becomes immutable after publish.
|
|
332
|
-
|
|
333
|
-
### 5.3 Prerequisites Summary
|
|
334
|
-
|
|
335
|
-
| Object | Must Exist Before Create |
|
|
336
|
-
|--------|-------------------------|
|
|
337
|
-
| Treasury | Permission |
|
|
338
|
-
| Allocation | Treasury + Permission |
|
|
339
|
-
| Service | Permission |
|
|
340
|
-
| Machine | Permission |
|
|
341
|
-
| Guard | Permission |
|
|
342
|
-
| Order | Service (published) + Machine (published) |
|
|
343
|
-
| Progress | Order + Machine |
|
|
344
|
-
| Arbitration | Order + Permission |
|
|
345
|
-
| Reward | Repository + Permission |
|
|
346
|
-
| Passport | Guard |
|
|
347
|
-
| Proof | Passport |
|
|
348
|
-
| Repository | Permission |
|
|
349
|
-
| Demand | Permission |
|
|
350
|
-
| Contact | Permission + Registrar |
|
|
351
|
-
| Personal | Registrar |
|
|
352
|
-
| Arb Node | Arbitration |
|
|
353
|
-
|
|
354
|
-
### 5.4 Network Differences
|
|
355
|
-
|
|
356
|
-
| Aspect | testnet | mainnet |
|
|
357
|
-
|--------|---------|---------|
|
|
358
|
-
| CREATE | replaceExistName=true, repeatable | replaceExistName=false, no overwrite |
|
|
359
|
-
| BIND | Rebinding allowed | Locked after creation |
|
|
360
|
-
| TRIGGER | Repeatable | Irreversible |
|
|
361
|
-
| VALIDATE | Guard can be rebuilt | Guard rebuild requires updating all references |
|
|
362
|
-
| Bridge | ❌ Not supported | ✅ Supported |
|
|
@@ -1,81 +0,0 @@
|
|
|
1
|
-
# On-Chain Constants — Unified Management Reference
|
|
2
|
-
|
|
3
|
-
> **Status**: Unified management reference for on-chain numeric constants across three layers (Move contracts, SDK, MCP).
|
|
4
|
-
|
|
5
|
-
## Why Unified Management
|
|
6
|
-
|
|
7
|
-
Before GLM4, on-chain numeric constants were scattered across three layers:
|
|
8
|
-
|
|
9
|
-
- **Smart contract layer**: Each `.move` file has its own `const MAX_* = N;` (on-chain authority)
|
|
10
|
-
- **SDK layer**: Each `.ts` call file has its own `export const MAX_* = N;` (prone to drift from chain)
|
|
11
|
-
- **MCP layer**: Hardcoded magic numbers (`100`, `1000`, etc.) with no import links
|
|
12
|
-
|
|
13
|
-
This caused drift risk, magic numbers in MCP, and implicit differences between SDK and on-chain values.
|
|
14
|
-
|
|
15
|
-
**Solution**: SDK is the single authoritative TS definition; MCP imports from SDK; Move contracts remain unchanged.
|
|
16
|
-
|
|
17
|
-
## 3-Layer Sync Architecture
|
|
18
|
-
|
|
19
|
-
```
|
|
20
|
-
┌──────────────────────┐ import ┌──────────────────────┐
|
|
21
|
-
│ Move smart contracts │ ──────────► │ SDK onchain-constants │
|
|
22
|
-
│ (*.move const MAX_*) │ │ (canonical TS source) │
|
|
23
|
-
└──────────────────────┘ └──────────┬───────────┘
|
|
24
|
-
│ import
|
|
25
|
-
▼
|
|
26
|
-
┌──────────────────────┐
|
|
27
|
-
│ MCP onchain-constants │
|
|
28
|
-
│ (re-export from SDK) │
|
|
29
|
-
└──────────────────────┘
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
### Sync Guarantees
|
|
33
|
-
|
|
34
|
-
- **SDK ↔ Move**: A spec test parses `.move` files and asserts SDK values match Move `const` declarations
|
|
35
|
-
- **MCP ↔ SDK**: The same test asserts MCP import values equal SDK export values
|
|
36
|
-
- **CI Integration**: Sync tests run on every PR to prevent drift across all three layers
|
|
37
|
-
|
|
38
|
-
## 18 Constant Entries
|
|
39
|
-
|
|
40
|
-
| # | Name | Value | Move Source | Purpose |
|
|
41
|
-
|---|------|-------|-------------|---------|
|
|
42
|
-
| 1 | `MAX_NODE_COUNT_ONCHAIN` | 200 | `machine.move:23` | Max nodes on-chain (chain authority) |
|
|
43
|
-
| 2 | `MAX_NODE_COUNT_SDK` | 100 | (SDK custom) | Stricter limit for SDK/MCP (easier human review) |
|
|
44
|
-
| 3 | `MAX_FORWARD_COUNT` | 20 | `machine.move:26` | Max global forwards per Machine |
|
|
45
|
-
| 4 | `MAX_FORWARD_ORDER_COUNT` | 20 | `machine.move:21` | Max forwards per pair |
|
|
46
|
-
| 5 | `MAX_NODE_PAIR_COUNT` | 40 | `machine.move:22` | Max pairs per node |
|
|
47
|
-
| 6 | `USER_DEFINED_PERM_INDEX_START` | 1000 | (convention) | Custom permission_index start (0-999 reserved for built-in) |
|
|
48
|
-
| 7 | `MAX_PERM_FOR_ENTITY` | 1000 | `permission.move:15` | Max permissions per Entity |
|
|
49
|
-
| 8 | `MAX_ADMIN_COUNT` | 500 | `permission.move:17` | Max admins per Permission object |
|
|
50
|
-
| 9 | `MAX_AGENT_COUNT` | 10 | `order.move:12` | Max agents per Order |
|
|
51
|
-
| 10 | `MAX_DISPUTE_COUNT` | 10 | `order.move:13` | Max concurrent disputes per Order |
|
|
52
|
-
| 11 | `MAX_SHARING_COUNT` | 100 | `allocation.move:17` | Max sharing entries per allocator |
|
|
53
|
-
| 12 | `MAX_VOTING_GUARD_COUNT` | 50 | `arbitration.move:25` | Max voting guards per Arbitration |
|
|
54
|
-
| 13 | `MAX_POLICY_COUNT` | 50 | `repository.move:22` | Max policies per Repository |
|
|
55
|
-
| 14 | `MAX_ID_COUNT_ONCE` | 100 | `repository.move:25` | Max IDs per Repository operation |
|
|
56
|
-
| 15 | `MAX_REWARD_COUNT` | 20 | `demand.move:21` + `repository.move:26` | Max rewards per Demand/Repository (same name, same value, different scopes) |
|
|
57
|
-
| 16 | `MAX_CONTEXT_REPOSITORY_COUNT` | 30 | `progress.move:23` | Max context repositories per Progress |
|
|
58
|
-
| 17 | `MAX_NAMED_OPERATOR_COUNT` | 60 | `progress.move:24` | Max named operators per Forward |
|
|
59
|
-
| 18 | `MAX_NAMED_OPERATOR_ADDRESS_COUNT` | 80 | `progress.move:25` | Max addresses per named operator |
|
|
60
|
-
|
|
61
|
-
> Note: 18 entries total (including `MAX_NODE_COUNT_ONCHAIN` and `MAX_NODE_COUNT_SDK` as two variants), corresponding to 15 unique on-chain constant concepts.
|
|
62
|
-
|
|
63
|
-
## Naming Conventions
|
|
64
|
-
|
|
65
|
-
- Constant names match Move names exactly (e.g., `MAX_FORWARD_ORDER_COUNT`, not rewritten)
|
|
66
|
-
- When the SDK is intentionally stricter than on-chain: chain value uses `*_ONCHAIN` suffix, SDK value uses `*_SDK` suffix, bare name (e.g., `MAX_NODE_COUNT`) aliases the SDK value
|
|
67
|
-
- `USER_DEFINED_PERM_INDEX_START` is a **convention**, not a Move `const` (permission.move implicitly reserves 0-999)
|
|
68
|
-
|
|
69
|
-
## Special Case: `MAX_REWARD_COUNT`
|
|
70
|
-
|
|
71
|
-
`MAX_REWARD_COUNT = 20` is defined in both `demand.move:21` (Demand reward cap) and `repository.move:26` (Repository reward cap). Same name and value but semantically independent. If the chain ever diverges, split into `MAX_REWARD_COUNT_DEMAND` and `MAX_REWARD_COUNT_REPOSITORY`.
|
|
72
|
-
|
|
73
|
-
## Key Design Principles
|
|
74
|
-
|
|
75
|
-
1. **Move contracts are the ultimate source of truth**: SDK must always align with Move. When a discrepancy is found, **fix the SDK** (unless the Move contract itself has a bug requiring an on-chain upgrade).
|
|
76
|
-
2. **SDK is the single authoritative definition**: `onchain-constants.ts` in the SDK is the sole canonical source for the SDK/MCP layer; MCP does not redefine constants.
|
|
77
|
-
3. **Explicit imports**: MCP uses explicit imports (not `export *`) for auditability.
|
|
78
|
-
4. **Three-way sync**: SDK ↔ Move ↔ MCP are kept consistent via automated tests.
|
|
79
|
-
5. **On-chain vs SDK distinction**: When the SDK is stricter than on-chain, use `*_ONCHAIN` / `*_SDK` suffixes to make the difference explicit.
|
|
80
|
-
6. **JSDoc with Move source**: Every constant's JSDoc must annotate the source Move file location.
|
|
81
|
-
7. **Consumer mapping**: `ONCHAIN_CONSTANT_MCP_CONSUMERS` records where each constant is used in MCP for audit purposes.
|