@wowok/agent-mcp 2.2.13 → 2.2.14

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.
Files changed (126) hide show
  1. package/dist/index.js +42 -98
  2. package/dist/schema-query/index.d.ts +29 -0
  3. package/dist/schema-query/index.js +149 -0
  4. package/dist/schemas/account_operation.schema.json +255 -0
  5. package/dist/schemas/guard2file.schema.json +71 -0
  6. package/dist/schemas/index.json +139 -0
  7. package/dist/schemas/local_info_operation.schema.json +142 -0
  8. package/dist/schemas/local_mark_operation.schema.json +119 -0
  9. package/dist/schemas/machineNode2file.schema.json +71 -0
  10. package/dist/schemas/messenger_operation.schema.json +1393 -0
  11. package/dist/schemas/onchain_events.schema.json +113 -0
  12. package/dist/schemas/onchain_operations.schema.json +376 -0
  13. package/dist/schemas/onchain_operations_allocation.schema.json +914 -0
  14. package/dist/schemas/onchain_operations_arbitration.schema.json +1166 -0
  15. package/dist/schemas/onchain_operations_contact.schema.json +853 -0
  16. package/dist/schemas/onchain_operations_demand.schema.json +984 -0
  17. package/dist/schemas/onchain_operations_gen_passport.schema.json +1141 -0
  18. package/dist/schemas/onchain_operations_guard.schema.json +713 -0
  19. package/dist/schemas/onchain_operations_machine.schema.json +1347 -0
  20. package/dist/schemas/onchain_operations_order.schema.json +830 -0
  21. package/dist/schemas/onchain_operations_payment.schema.json +717 -0
  22. package/dist/schemas/onchain_operations_permission.schema.json +1088 -0
  23. package/dist/schemas/onchain_operations_personal.schema.json +1282 -0
  24. package/dist/schemas/onchain_operations_progress.schema.json +751 -0
  25. package/dist/schemas/onchain_operations_repository.schema.json +1572 -0
  26. package/dist/schemas/onchain_operations_reward.schema.json +955 -0
  27. package/dist/schemas/onchain_operations_service.schema.json +1411 -0
  28. package/dist/schemas/onchain_operations_treasury.schema.json +1155 -0
  29. package/dist/schemas/onchain_table_data.schema.json +35 -0
  30. package/dist/schemas/operations/guard.json +163 -0
  31. package/dist/schemas/operations/permission.json +22 -0
  32. package/dist/schemas/query_toolkit.schema.json +32 -0
  33. package/dist/schemas/schema_query.schema.json +33 -0
  34. package/dist/schemas/wip_file.schema.json +27 -0
  35. package/dist/schemas/wowok_buildin_info.schema.json +487 -0
  36. package/package.json +7 -5
  37. package/dist/docs/index.d.ts +0 -3
  38. package/dist/docs/index.js +0 -2
  39. package/dist/docs/loader.d.ts +0 -12
  40. package/dist/docs/loader.js +0 -177
  41. package/dist/docs/search.d.ts +0 -17
  42. package/dist/docs/search.js +0 -325
  43. package/dist/docs/types.d.ts +0 -55
  44. package/dist/docs/types.js +0 -1
  45. package/docs/README.md +0 -249
  46. package/docs/WIP.md +0 -388
  47. package/docs/WTS.md +0 -536
  48. package/docs/docs/account.md +0 -914
  49. package/docs/docs/allocation.md +0 -635
  50. package/docs/docs/arbitration.md +0 -1804
  51. package/docs/docs/arbitration_state_machine.md +0 -270
  52. package/docs/docs/contact.md +0 -709
  53. package/docs/docs/demand.md +0 -948
  54. package/docs/docs/guard.md +0 -1465
  55. package/docs/docs/localinfo.md +0 -432
  56. package/docs/docs/localmark.md +0 -583
  57. package/docs/docs/machine.md +0 -2490
  58. package/docs/docs/messenger.md +0 -2098
  59. package/docs/docs/onchain_events.md +0 -267
  60. package/docs/docs/order.md +0 -1001
  61. package/docs/docs/payment.md +0 -512
  62. package/docs/docs/permission.md +0 -1438
  63. package/docs/docs/personal.md +0 -742
  64. package/docs/docs/progress.md +0 -1748
  65. package/docs/docs/query.md +0 -467
  66. package/docs/docs/repository.md +0 -1043
  67. package/docs/docs/reward.md +0 -833
  68. package/docs/docs/service.md +0 -2130
  69. package/docs/docs/stage-01-introduction.md +0 -243
  70. package/docs/docs/stage-02-trust.md +0 -302
  71. package/docs/docs/stage-03-collaboration.md +0 -337
  72. package/docs/docs/stage-04-transaction.md +0 -277
  73. package/docs/docs/stage-05-business.md +0 -151
  74. package/docs/docs/stage-06-personal.md +0 -203
  75. package/docs/docs/stage-07-query.md +0 -572
  76. package/docs/docs/stage-08-examples.md +0 -184
  77. package/docs/docs/treasury.md +0 -1149
  78. package/docs/docs/wowok_buildin_info.md +0 -740
  79. package/docs/examples/Insurance/Insurance.md +0 -594
  80. package/docs/examples/Insurance/Insurance_TestResults.md +0 -481
  81. package/docs/examples/Insurance/insurance_complete_guard_v1.json +0 -50
  82. package/docs/examples/MyShop/MyShop.md +0 -1353
  83. package/docs/examples/MyShop/MyShop_TestResults.md +0 -1003
  84. package/docs/examples/MyShop_Advanced/MyShop_Advanced.md +0 -1898
  85. package/docs/examples/MyShop_Advanced/MyShop_Advanced_MerchantSystem_TestResults.md +0 -1297
  86. package/docs/examples/MyShop_Advanced/MyShop_Advanced_OrderFlow_TestResults.md +0 -743
  87. package/docs/examples/MyShop_Advanced/machine_nodes.json +0 -222
  88. package/docs/examples/ThreeBody_Signature/ThreeBody_Signature.md +0 -776
  89. package/docs/examples/ThreeBody_Signature/ThreeBody_Signature_TestResults.md +0 -599
  90. package/docs/examples/Travel/Travel.md +0 -1157
  91. package/docs/examples/Travel/Travel_TestResults.md +0 -743
  92. package/docs/examples/Travel/calc-weather-timestamps.js +0 -8
  93. package/docs/examples/Travel/travel_machine_v2_export.json +0 -104
  94. package/docs/examples/Travel/weather_check_guard_v1.json +0 -51
  95. package/docs/skills/WOWOK.md +0 -650
  96. package/docs/skills/onchain_operations/_common.md +0 -406
  97. package/docs/skills/onchain_operations/_index.md +0 -196
  98. package/docs/skills/onchain_operations/allocation.md +0 -28
  99. package/docs/skills/onchain_operations/arbitration.md +0 -106
  100. package/docs/skills/onchain_operations/contact.md +0 -40
  101. package/docs/skills/onchain_operations/demand.md +0 -53
  102. package/docs/skills/onchain_operations/gen_passport.md +0 -23
  103. package/docs/skills/onchain_operations/guard.md +0 -56
  104. package/docs/skills/onchain_operations/machine.md +0 -89
  105. package/docs/skills/onchain_operations/order.md +0 -56
  106. package/docs/skills/onchain_operations/payment.md +0 -24
  107. package/docs/skills/onchain_operations/permission.md +0 -68
  108. package/docs/skills/onchain_operations/personal.md +0 -58
  109. package/docs/skills/onchain_operations/progress.md +0 -38
  110. package/docs/skills/onchain_operations/repository.md +0 -70
  111. package/docs/skills/onchain_operations/reward.md +0 -38
  112. package/docs/skills/onchain_operations/service.md +0 -78
  113. package/docs/skills/onchain_operations/treasury.md +0 -68
  114. package/docs/skills/schema-account_operation.md +0 -402
  115. package/docs/skills/schema-guard2file.md +0 -153
  116. package/docs/skills/schema-local_info_operation.md +0 -160
  117. package/docs/skills/schema-local_mark_operation.md +0 -148
  118. package/docs/skills/schema-machineNode2file.md +0 -155
  119. package/docs/skills/schema-messenger_operation.md +0 -547
  120. package/docs/skills/schema-onchain_events.md +0 -201
  121. package/docs/skills/schema-onchain_table_data.md +0 -334
  122. package/docs/skills/schema-query_toolkit.md +0 -395
  123. package/docs/skills/schema-wip_file.md +0 -240
  124. package/docs/skills/schema-wowok_buildin_info.md +0 -296
  125. package/docs/wip-examples/three_body.html +0 -57
  126. package/docs/wip-examples/three_body.wip +0 -30
@@ -1,1157 +0,0 @@
1
- # Iceland Travel Service Example
2
-
3
- A complete example demonstrating how to create an Iceland travel service using WoWok protocol. This service integrates weather-dependent activities, insurance sub-orders, and multi-node workflow management.
4
-
5
- > **View Actual Execution Results**: See [Travel_TestResults.md](Travel_TestResults.md) for real testnet execution results with actual object addresses and transaction outputs.
6
-
7
- ---
8
-
9
- ## Core Requirements & Features
10
-
11
- | Requirement | Description | Implementation |
12
- |-------------|-------------|----------------|
13
- | **Weather-Dependent Activities** | Ice scooting requires sunny weather | Guard queries weather Repository for the activity date |
14
- | **Insurance Sub-Order** | Travel provider purchases insurance as supply chain sub-order | Machine forward creates insurance Order via Progress |
15
- | **Multi-Node Workflow** | Start -> Buy Insurance -> SPA -> Ice Scooting -> Complete | Machine with 5 nodes and conditional paths |
16
- | **Time-Lock Completion** | Prevent premature order completion | Guard using Order + convert_witness(TypeOrderProgress) |
17
- | **Cancellation Support** | Allow order cancellation before completion | Cancel forward with permission-based access |
18
- | **Arbitration** | Dispute resolution for order conflicts | Arbitration object bound to Service |
19
-
20
- ### Key Design Decisions
21
-
22
- 1. **Weather Data via Repository**: Weather conditions are stored in a Repository object with policy "Condition". Each day's weather is keyed by UTC timestamp (converted to Address via `convert_number_address`).
23
- 2. **Insurance as Sub-Order**: The "Buy Insurance" node creates a sub-order on the insurance service, linking the two workflows.
24
- 3. **Time-Lock via Witness Conversion**: The Complete node Guard uses `convert_witness: 100` (TypeOrderProgress) to access Progress data from the submitted Order.
25
- 4. **Dynamic Time Calculation**: Weather data timestamps are calculated dynamically based on current time, ensuring the example is always testable.
26
-
27
- ---
28
-
29
- ## Overview
30
-
31
- This example demonstrates:
32
-
33
- - **Travel Service Setup**: Permission, Arbitration, Guards, Machine, and Service creation
34
- - **Weather Data Management**: Repository with weather conditions for activity validation
35
- - **Insurance Integration**: Supply chain sub-order for insurance purchase
36
- - **Multi-Node Workflow**: Complex workflow with weather-dependent paths
37
- - **Time-Lock Guards**: Using Order + convert_witness for Progress data access
38
-
39
- ---
40
-
41
- ## Architecture
42
-
43
- ### System Components
44
-
45
- ```
46
- +--------------------------------------------------------------------------+
47
- | Iceland Travel Service System |
48
- +--------------------------------------------------------------------------+
49
- | |
50
- | +--------------+ +--------------+ +--------------+ +--------------+ |
51
- | | Permission | | Arbitration | | Guards | | Repository | |
52
- | | (travel_ | | (travel_ | | (weather_ | | (weather_ | |
53
- | | permission)| | arbitration)| | check, | | repo) | |
54
- | +------+-------+ +------+-------+ | complete, | +------+-------+ |
55
- | | | | cancel) | | |
56
- | v v +------+-------+ | |
57
- | +--------------+ +--------------+ | | |
58
- | | Machine | | Service | | | |
59
- | | (travel_ |<-| (travel_ | | | |
60
- | | machine) | | service) | | | |
61
- | +--------------+ +--------------+ | | |
62
- | | | |
63
- | Workflow: | | |
64
- | Start -> Buy Insurance -> SPA -> Ice Scooting | | |
65
- | | | | |
66
- | +----------+---------+----------+ | |
67
- | | | | |
68
- | v v | |
69
- | +----------+ +----------+ | |
70
- | | Complete | | Cancel | | |
71
- | |(TimeLock)| | | | |
72
- | +----------+ +----------+ | |
73
- | |
74
- +--------------------------------------------------------------------------+
75
- ```
76
-
77
- ### Workflow Diagram
78
-
79
- ```
80
- +-------------+
81
- | Start |
82
- +------+------+
83
- |
84
- v
85
- +-------------+
86
- |Buy Insurance| ---> Creates sub-order on insurance service
87
- +------+------+
88
- |
89
- v
90
- +-------------+
91
- | SPA |
92
- +------+------+
93
- |
94
- v
95
- +-------------+
96
- |Ice Scooting | ---> Weather check Guard (sunny required)
97
- +------+------+
98
- |
99
- +-----------+-----------+
100
- | |
101
- v v
102
- +-------------+ +-------------+
103
- | Complete | | Cancel |
104
- | (Time-Lock) | | |
105
- +-------------+ +-------------+
106
- ```
107
-
108
- ---
109
-
110
- ## Prerequisites
111
-
112
- Before running this example, ensure you have:
113
-
114
- 1. An account named `travel_provider_v1` with sufficient WOW tokens
115
- 2. An account named `weather_provider_v1` with sufficient WOW tokens
116
- 3. An account named `alice_v1` (test customer) with sufficient WOW tokens
117
- 4. The Insurance service from [Insurance/Insurance.md](../Insurance/Insurance.md) already deployed
118
- 5. Access to the WoWok MCP server
119
-
120
- ### Create Accounts
121
-
122
- **Prompt**: Create accounts for travel provider, weather provider, and test customer.
123
-
124
- ```json
125
- {
126
- "gen": {
127
- "name": "travel_provider_v1",
128
- "replaceExistName": true
129
- }
130
- }
131
- ```
132
-
133
- ```json
134
- {
135
- "gen": {
136
- "name": "weather_provider_v1",
137
- "replaceExistName": true
138
- }
139
- }
140
- ```
141
-
142
- ```json
143
- {
144
- "gen": {
145
- "name": "alice_v1",
146
- "replaceExistName": true
147
- }
148
- }
149
- ```
150
-
151
- ### Get Test Tokens
152
-
153
- **Prompt**: Request testnet WOW tokens for all accounts.
154
-
155
- ```json
156
- {
157
- "faucet": {
158
- "network": "testnet",
159
- "name_or_address": "travel_provider_v1"
160
- }
161
- }
162
- ```
163
-
164
- ```json
165
- {
166
- "faucet": {
167
- "network": "testnet",
168
- "name_or_address": "weather_provider_v1"
169
- }
170
- }
171
- ```
172
-
173
- ```json
174
- {
175
- "faucet": {
176
- "network": "testnet",
177
- "name_or_address": "alice_v1"
178
- }
179
- }
180
- ```
181
-
182
- ---
183
-
184
- ## Step 0: Setup Weather Data
185
-
186
- Before creating the travel service, set up the weather Repository with recent 5-day weather data.
187
-
188
- ### 0.1 Calculate Weather Timestamps
189
-
190
- Use the following JavaScript to calculate recent 5-day UTC timestamps:
191
-
192
- ```js
193
- const DAY_MS = 86400000;
194
- const now = Date.now();
195
- const todayStart = Math.floor(now / DAY_MS) * DAY_MS;
196
- // Recent 5 days UTC day start timestamps (from 4 days ago to today)
197
- for (let i = 4; i >= 0; i--) {
198
- const ts = todayStart - i * DAY_MS;
199
- console.log(`Day ${5-i}: ${ts} (${new Date(ts).toISOString()})`);
200
- }
201
- ```
202
-
203
- ### 0.2 Create Weather Permission
204
-
205
- First, create a Permission object for the weather repository.
206
-
207
- **Prompt**: Create a Permission object named "weather_permission_v1".
208
-
209
- ```json
210
- {
211
- "operation_type": "permission",
212
- "data": {
213
- "object": {
214
- "name": "weather_permission_v1",
215
- "replaceExistName": true
216
- },
217
- "description": "Weather repository permission"
218
- },
219
- "env": {
220
- "account": "weather_provider_v1",
221
- "network": "testnet"
222
- }
223
- }
224
- ```
225
-
226
- ### 0.3 Create Weather Repository with Policies
227
-
228
- Create the weather repository with the "Condition" policy included during creation (this avoids the need to add policies later, which had issues in testing).
229
-
230
- **Prompt**: Create a Repository named "weather_repo_v2" with "Condition" policy.
231
-
232
- ```json
233
- {
234
- "operation_type": "repository",
235
- "data": {
236
- "object": {
237
- "name": "weather_repo_v2",
238
- "permission": "weather_permission_v1",
239
- "replaceExistName": true
240
- },
241
- "description": "Weather data repository for Iceland travel activities",
242
- "policies": {
243
- "op": "add",
244
- "policy": [
245
- {
246
- "name": "Condition",
247
- "description": "Weather condition policy for activity dates",
248
- "write_guard": [],
249
- "id_from": "None",
250
- "value_type": "String"
251
- }
252
- ]
253
- }
254
- },
255
- "env": {
256
- "account": "weather_provider_v1",
257
- "network": "testnet"
258
- }
259
- }
260
- ```
261
-
262
- ### 0.4 Add Weather Data
263
-
264
- Add 5 days of weather data. The last day is "rainy" to test the weather check Guard's rejection behavior.
265
-
266
- **Prompt**: Add weather data to "weather_repo_v2" with policy "Condition". Use the timestamps calculated in step 0.1.
267
-
268
- ```json
269
- {
270
- "operation_type": "repository",
271
- "data": {
272
- "object": "weather_repo_v2",
273
- "data_add": {
274
- "name": "Condition",
275
- "items": [
276
- {
277
- "data": [
278
- {"id": 1777334400000, "data": "sunny"},
279
- {"id": 1777420800000, "data": "sunny"},
280
- {"id": 1777507200000, "data": "sunny"},
281
- {"id": 1777593600000, "data": "sunny"},
282
- {"id": 1777680000000, "data": "rainy"}
283
- ]
284
- }
285
- ]
286
- }
287
- },
288
- "env": {
289
- "account": "weather_provider_v1",
290
- "network": "testnet"
291
- }
292
- }
293
- ```
294
-
295
- > **Note**: Replace the timestamps with actual values from step 0.1. The last day is "rainy" to demonstrate weather-dependent activity rejection.
296
-
297
- ---
298
-
299
- ## Step 1: Create Permission Object
300
-
301
- Create a Permission object to manage access control for the travel service.
302
-
303
- **Prompt**: Create a Permission object named "travel_permission_v1" for the travel service.
304
-
305
- ```json
306
- {
307
- "operation_type": "permission",
308
- "data": {
309
- "object": {
310
- "name": "travel_permission_v1",
311
- "replaceExistName": true
312
- },
313
- "description": "Permission for Iceland travel service",
314
- "table": {
315
- "op": "add perm by entity",
316
- "entity": {"name_or_address": "travel_provider_v1"},
317
- "index": [1000, 1001, 1002, 1003, 1004, 1005]
318
- }
319
- },
320
- "env": {
321
- "account": "travel_provider_v1",
322
- "network": "testnet"
323
- }
324
- }
325
- ```
326
-
327
- ---
328
-
329
- ## Step 2: Create Arbitration Object
330
-
331
- Create an Arbitration object for dispute resolution.
332
-
333
- **Prompt**: Create an Arbitration named "travel_arbitration_v1".
334
-
335
- ```json
336
- {
337
- "operation_type": "arbitration",
338
- "data": {
339
- "object": {
340
- "name": "travel_arbitration_v1",
341
- "permission": "travel_permission_v1",
342
- "replaceExistName": true
343
- },
344
- "description": "Arbitration for Iceland travel service disputes"
345
- },
346
- "env": {
347
- "account": "travel_provider_v1",
348
- "network": "testnet"
349
- }
350
- }
351
- ```
352
-
353
- ---
354
-
355
- ## Step 3: Create Guards
356
-
357
- ### 3.1 Weather Check Guard
358
-
359
- > **Note**: This guard demonstrates how to query repository data using a timestamp converted to an address. You can test it using `gen_passport` with a timestamp from step 0.1.
360
-
361
- **Prompt**: Create a Guard named "weather_check_guard_v1" for weather condition verification.
362
-
363
- Creates a Guard that verifies weather conditions for a given date. Queries the weather Repository for the specified date and checks if the condition matches the expected value.
364
-
365
- **Guard Logic**:
366
- ```
367
- repository.data("Condition", convert_number_address(activity_date)) == expected_weather
368
- ```
369
-
370
- **Prompt**: Create a Guard named "weather_check_guard" for weather condition verification.
371
-
372
- ```json
373
- {
374
- "operation_type": "guard",
375
- "data": {
376
- "namedNew": {
377
- "name": "weather_check_guard_v1",
378
- "tags": ["weather", "check", "travel"],
379
- "replaceExistName": true
380
- },
381
- "description": "Weather check guard for ice scooting activity. Queries weather Repository for the activity date and verifies the condition is 'sunny'. The activity date is submitted at runtime.",
382
- "table": [
383
- {
384
- "identifier": 0,
385
- "b_submission": false,
386
- "value_type": "Address",
387
- "value": "weather_repo_v2",
388
- "name": "Weather Repository address"
389
- },
390
- {
391
- "identifier": 1,
392
- "b_submission": false,
393
- "value_type": "String",
394
- "value": "Condition",
395
- "name": "Repository policy name"
396
- },
397
- {
398
- "identifier": 2,
399
- "b_submission": true,
400
- "value_type": "U64",
401
- "value": 0,
402
- "name": "Activity date timestamp (submitted at runtime)"
403
- },
404
- {
405
- "identifier": 3,
406
- "b_submission": false,
407
- "value_type": "String",
408
- "value": "sunny",
409
- "name": "Expected weather condition"
410
- }
411
- ],
412
- "root": {
413
- "type": "node",
414
- "node": {
415
- "type": "logic_equal",
416
- "nodes": [
417
- {
418
- "type": "query",
419
- "query": "repository.data",
420
- "object": {
421
- "identifier": 0
422
- },
423
- "parameters": [
424
- {
425
- "type": "identifier",
426
- "identifier": 1
427
- },
428
- {
429
- "type": "convert_number_address",
430
- "node": {
431
- "type": "identifier",
432
- "identifier": 2
433
- }
434
- }
435
- ]
436
- },
437
- {
438
- "type": "identifier",
439
- "identifier": 3
440
- }
441
- ]
442
- }
443
- }
444
- },
445
- "env": {
446
- "account": "travel_provider_v1",
447
- "network": "testnet"
448
- }
449
- }
450
- ```
451
-
452
- > **Note**: We use the repository name "weather_repo_v2" directly (the MCP server resolves names to addresses automatically). If you need the raw address, you can query it using `onchain_objects` with the name.
453
-
454
- **Guard Table**:
455
-
456
- | identifier | b_submission | value_type | value | Purpose |
457
- |------------|-------------|-----------|-------|---------|
458
- | 0 | false | Address | weather_repo address | Weather Repository to query |
459
- | 1 | false | String | "Condition" | Repository policy name |
460
- | 2 | **true** | U64 | 0 (placeholder) | Activity date timestamp, submitted at runtime |
461
- | 3 | false | String | "sunny" | Expected weather condition |
462
-
463
- ### 3.2 Travel Complete Guard (Time-Lock)
464
-
465
- Creates a Guard that verifies the time-lock condition for order completion.
466
-
467
- **Guard Logic**:
468
- ```
469
- clock > progress.current_time + 1000
470
- (progress accessed via Order + convert_witness=TypeOrderProgress)
471
- ```
472
-
473
- **Prompt**: Create a Guard named "travel_complete_guard" for time-lock verification.
474
-
475
- ```json
476
- {
477
- "operation_type": "guard",
478
- "data": {
479
- "namedNew": {
480
- "name": "travel_complete_guard_v1",
481
- "tags": ["travel", "time-lock", "complete"],
482
- "replaceExistName": true
483
- },
484
- "description": "Time-lock guard for travel order completion. Requires current clock > progress.current_time + 1000ms (1 second for TESTING; in production set to reasonable duration like 8 hours). Progress is accessed via Order with convert_witness=TypeOrderProgress(100).",
485
- "table": [
486
- {
487
- "identifier": 0,
488
- "b_submission": true,
489
- "value_type": "Address",
490
- "value": "0x0000000000000000000000000000000000000000000000000000000000000000",
491
- "name": "Order ID (submitted at runtime)"
492
- },
493
- {
494
- "identifier": 1,
495
- "b_submission": false,
496
- "value_type": "U64",
497
- "value": 1000
498
- }
499
- ],
500
- "root": {
501
- "type": "node",
502
- "node": {
503
- "type": "logic_as_u256_greater",
504
- "nodes": [
505
- {
506
- "type": "context",
507
- "context": "Clock"
508
- },
509
- {
510
- "type": "calc_number_add",
511
- "nodes": [
512
- {
513
- "type": "query",
514
- "query": "progress.current_time",
515
- "object": {
516
- "identifier": 0,
517
- "convert_witness": 100
518
- },
519
- "parameters": []
520
- },
521
- {
522
- "type": "identifier",
523
- "identifier": 1
524
- }
525
- ]
526
- }
527
- ]
528
- }
529
- }
530
- },
531
- "env": {
532
- "account": "travel_provider_v1",
533
- "network": "testnet"
534
- }
535
- }
536
- ```
537
-
538
- **Guard Table**:
539
-
540
- | identifier | b_submission | value_type | value | Purpose |
541
- |------------|-------------|-----------|-------|---------|
542
- | 0 | **true** | Address | 0x0...0 (placeholder) | Order ID submitted at runtime, converted to Progress via convert_witness |
543
- | 1 | false | U64 | 1000 | Time-lock duration in ms (1 second for testing) |
544
-
545
- > **Important**: `1000` ms (1 second) is for testing only. In production, set to a reasonable duration (e.g., 8 hours = 28800000 ms).
546
-
547
- ### 3.3 Travel Cancel Guard
548
-
549
- Creates a Guard that allows order cancellation. This Guard always passes (returns true), as cancellation is controlled by permission-based access.
550
-
551
- **Prompt**: Create a Guard named "travel_cancel_guard" for order cancellation.
552
-
553
- ```json
554
- {
555
- "operation_type": "guard",
556
- "data": {
557
- "namedNew": {
558
- "name": "travel_cancel_guard_v1",
559
- "tags": ["travel", "cancel"],
560
- "replaceExistName": true
561
- },
562
- "description": "Cancel guard for travel orders. Always passes - cancellation is controlled by permission-based access (only authorized operators can execute the cancel forward).",
563
- "table": [
564
- {
565
- "identifier": 0,
566
- "b_submission": false,
567
- "value_type": "Bool",
568
- "value": true,
569
- "name": "Always true"
570
- }
571
- ],
572
- "root": {
573
- "type": "node",
574
- "node": {
575
- "type": "identifier",
576
- "identifier": 0
577
- }
578
- }
579
- },
580
- "env": {
581
- "account": "travel_provider_v1",
582
- "network": "testnet"
583
- }
584
- }
585
- ```
586
-
587
- ---
588
-
589
- ## Step 4: Create Machine with Workflow
590
-
591
- Create a Machine to define the travel service workflow with all nodes and forwards.
592
-
593
- **Prompt**: Create a Machine named "travel_machine" with the complete travel workflow.
594
-
595
- ```json
596
- {
597
- "operation_type": "machine",
598
- "data": {
599
- "object": {
600
- "name": "travel_machine_v1",
601
- "permission": "travel_permission_v1",
602
- "replaceExistName": true
603
- },
604
- "description": "Iceland travel service workflow: Start -> Buy Insurance -> SPA -> Ice Scooting -> Complete/Cancel",
605
- "node": {
606
- "op": "add",
607
- "nodes": [
608
- {
609
- "name": "Start",
610
- "pairs": [
611
- {
612
- "prev_node": "",
613
- "threshold": 0,
614
- "forwards": [
615
- {
616
- "name": "buy_insurance",
617
- "permissionIndex": 1000,
618
- "weight": 1
619
- }
620
- ]
621
- }
622
- ]
623
- },
624
- {
625
- "name": "Buy Insurance",
626
- "pairs": [
627
- {
628
- "prev_node": "Start",
629
- "threshold": 1,
630
- "forwards": [
631
- {
632
- "name": "go_ice_scooting",
633
- "permissionIndex": 1001,
634
- "weight": 1
635
- }
636
- ]
637
- }
638
- ]
639
- },
640
- {
641
- "name": "SPA",
642
- "pairs": [
643
- {
644
- "prev_node": "Buy Insurance",
645
- "threshold": 1,
646
- "forwards": [
647
- {
648
- "name": "go_ice_scooting",
649
- "permissionIndex": 1002,
650
- "weight": 1
651
- }
652
- ]
653
- }
654
- ]
655
- },
656
- {
657
- "name": "Ice Scooting",
658
- "pairs": [
659
- {
660
- "prev_node": "SPA",
661
- "threshold": 1,
662
- "forwards": [
663
- {
664
- "name": "complete_trip",
665
- "permissionIndex": 1003,
666
- "weight": 1,
667
- "guard": {
668
- "guard": "travel_complete_guard_v1"
669
- }
670
- },
671
- {
672
- "name": "cancel_trip",
673
- "permissionIndex": 1004,
674
- "weight": 1,
675
- "guard": {
676
- "guard": "travel_cancel_guard_v1"
677
- }
678
- }
679
- ]
680
- }
681
- ]
682
- },
683
- {
684
- "name": "Complete",
685
- "pairs": [
686
- {
687
- "prev_node": "Ice Scooting",
688
- "threshold": 1,
689
- "forwards": []
690
- }
691
- ]
692
- },
693
- {
694
- "name": "Cancel",
695
- "pairs": [
696
- {
697
- "prev_node": "Ice Scooting",
698
- "threshold": 1,
699
- "forwards": []
700
- }
701
- ]
702
- }
703
- ]
704
- },
705
- "publish": true
706
- },
707
- "env": {
708
- "account": "travel_provider_v1",
709
- "network": "testnet"
710
- }
711
- }
712
- ```
713
-
714
- **Workflow Nodes**:
715
-
716
- | Node | Forward | Guard | PermissionIndex | Description |
717
- |------|---------|-------|-----------------|-------------|
718
- | Start | buy_insurance -> Buy Insurance | - | 1000 | Enter Start node from initial state |
719
- | Buy Insurance | go_ice_scooting -> SPA | - | 1001 | Proceed to SPA |
720
- | SPA | go_ice_scooting -> Ice Scooting | - | 1002 | Proceed to ice scooting |
721
- | Ice Scooting | complete_trip -> Complete | travel_complete_guard_v1 | 1003 | Complete trip (time-lock) |
722
- | Ice Scooting | cancel_trip -> Cancel | travel_cancel_guard_v1 | 1004 | Cancel trip |
723
- | Complete | (endpoint) | - | - | Final state |
724
- | Cancel | (endpoint) | - | - | Cancelled state |
725
-
726
- ---
727
-
728
- ## Step 5: Create and Publish Service
729
-
730
- Create the travel service with Machine, Arbitration, sales, and order_allocators, then publish in a single transaction.
731
-
732
- **Prompt**: Create and publish "travel_service" with all bindings and sales.
733
-
734
- ```json
735
- {
736
- "operation_type": "service",
737
- "data": {
738
- "object": {
739
- "name": "travel_service_v1",
740
- "type_parameter": "0x2::wow::WOW",
741
- "permission": "travel_permission_v1",
742
- "replaceExistName": true
743
- },
744
- "description": "Iceland travel service: Blue Lagoon SPA + Glacier Ice Scooting. Includes outdoor accident insurance.",
745
- "machine": "travel_machine_v1",
746
- "arbitrations": {
747
- "op": "add",
748
- "objects": ["travel_arbitration_v1"]
749
- },
750
- "sales": {
751
- "op": "add",
752
- "sales": [
753
- {
754
- "name": "Iceland Travel Package",
755
- "price": 500000000,
756
- "stock": 100,
757
- "suspension": false,
758
- "wip": "",
759
- "wip_hash": ""
760
- }
761
- ]
762
- },
763
- "order_allocators": {
764
- "description": "Travel order revenue allocation",
765
- "threshold": 0,
766
- "allocators": [
767
- {
768
- "guard": "travel_complete_guard_v1",
769
- "sharing": [
770
- {
771
- "who": {"Signer": "signer"},
772
- "sharing": 10000,
773
- "mode": "Rate"
774
- }
775
- ]
776
- }
777
- ]
778
- },
779
- "publish": true
780
- },
781
- "env": {
782
- "account": "travel_provider_v1",
783
- "network": "testnet"
784
- }
785
- }
786
- ```
787
-
788
- > **Note**: The `order_allocators` field is required for publishing a Service. It defines how order revenue is allocated. In this example, we use a simple allocator with the travel_complete_guard.
789
-
790
- ---
791
-
792
- ## Step 6: Unpause Service
793
-
794
- Unpause the service to allow order creation.
795
-
796
- **Prompt**: Unpause "travel_service".
797
-
798
- ```json
799
- {
800
- "operation_type": "service",
801
- "data": {
802
- "object": "travel_service",
803
- "pause": false
804
- },
805
- "env": {
806
- "account": "travel_provider_v1",
807
- "network": "testnet"
808
- }
809
- }
810
- ```
811
-
812
- ---
813
-
814
- ## Step 7: Verify Service Configuration
815
-
816
- Query the service to verify all configurations are correct.
817
-
818
- **Prompt**: Query "travel_service" to verify configuration.
819
-
820
- ```json
821
- {
822
- "query_type": "onchain_objects",
823
- "objects": ["travel_service"],
824
- "no_cache": true,
825
- "network": "testnet"
826
- }
827
- ```
828
-
829
- ---
830
-
831
- ## Step 8: Test Order Creation and Progress
832
-
833
- ### 8.1 Create Travel Order (as Customer Alice)
834
-
835
- Create an order on the travel service as the test customer.
836
-
837
- **Prompt**: Create an order on "travel_service" using account "alice".
838
-
839
- ```json
840
- {
841
- "operation_type": "service",
842
- "data": {
843
- "object": "travel_service",
844
- "order_new": {
845
- "buy": {
846
- "items": [
847
- {
848
- "name": "Iceland Travel Package",
849
- "stock": 1,
850
- "wip_hash": ""
851
- }
852
- ],
853
- "total_pay": {
854
- "balance": 500000000
855
- }
856
- },
857
- "namedNewOrder": {
858
- "name": "test_travel_order_v1",
859
- "replaceExistName": true
860
- }
861
- }
862
- },
863
- "env": {
864
- "account": "alice_v1",
865
- "network": "testnet"
866
- }
867
- }
868
- ```
869
-
870
- > **Note**: This creates an Order, Progress, and Allocation. Save the returned object IDs for the next steps.
871
-
872
- ### 8.2 Advance Progress: Initial -> Start
873
-
874
- First, advance the progress from initial state to Start node.
875
-
876
- **Prompt**: Advance progress to Start node.
877
-
878
- ```json
879
- {
880
- "operation_type": "progress",
881
- "data": {
882
- "object": "<travel_progress_id>",
883
- "operate": {
884
- "operation": {
885
- "next_node_name": "Start",
886
- "forward": "buy_insurance"
887
- }
888
- }
889
- },
890
- "env": {
891
- "account": "travel_provider_v1",
892
- "network": "testnet"
893
- }
894
- }
895
- ```
896
-
897
- ### 8.3 Advance Progress: Start -> Buy Insurance
898
-
899
- **Prompt**: Advance progress from Start to Buy Insurance.
900
-
901
- ```json
902
- {
903
- "operation_type": "progress",
904
- "data": {
905
- "object": "<travel_progress_id>",
906
- "operate": {
907
- "operation": {
908
- "next_node_name": "Buy Insurance",
909
- "forward": "buy_insurance"
910
- }
911
- }
912
- },
913
- "env": {
914
- "account": "travel_provider_v1",
915
- "network": "testnet"
916
- }
917
- }
918
- ```
919
-
920
- ### 8.4 Advance Progress: Buy Insurance -> SPA
921
-
922
- **Prompt**: Advance progress from Buy Insurance to SPA.
923
-
924
- ```json
925
- {
926
- "operation_type": "progress",
927
- "data": {
928
- "object": "<travel_progress_id>",
929
- "operate": {
930
- "operation": {
931
- "next_node_name": "SPA",
932
- "forward": "go_ice_scooting"
933
- }
934
- }
935
- },
936
- "env": {
937
- "account": "travel_provider_v1",
938
- "network": "testnet"
939
- }
940
- }
941
- ```
942
-
943
- ### 8.5 Advance Progress: SPA -> Ice Scooting
944
-
945
- **Prompt**: Advance progress from SPA to Ice Scooting.
946
-
947
- ```json
948
- {
949
- "operation_type": "progress",
950
- "data": {
951
- "object": "<travel_progress_id>",
952
- "operate": {
953
- "operation": {
954
- "next_node_name": "Ice Scooting",
955
- "forward": "go_ice_scooting"
956
- }
957
- }
958
- },
959
- "env": {
960
- "account": "travel_provider_v1",
961
- "network": "testnet"
962
- }
963
- }
964
- ```
965
-
966
- ### 8.6 Advance Progress: Ice Scooting -> Complete (Time-Lock)
967
-
968
- Wait at least 1 second after the last progress update, then advance to Complete with the Order ID as submission.
969
-
970
- **Prompt**: Advance progress to Complete, submitting the Order ID. Wait 1 second before executing.
971
-
972
- ```json
973
- {
974
- "operation_type": "progress",
975
- "data": {
976
- "object": "<travel_progress_id>",
977
- "operate": {
978
- "operation": {
979
- "next_node_name": "Complete",
980
- "forward": "complete_trip"
981
- }
982
- }
983
- },
984
- "env": {
985
- "account": "travel_provider_v1",
986
- "network": "testnet"
987
- },
988
- "submission": {
989
- "type": "submission",
990
- "guard": [
991
- {
992
- "object": "travel_complete_guard_v1",
993
- "impack": true
994
- }
995
- ],
996
- "submission": [
997
- {
998
- "guard": "travel_complete_guard_v1",
999
- "submission": [
1000
- {
1001
- "identifier": 0,
1002
- "b_submission": true,
1003
- "value_type": "Address",
1004
- "value": "<travel_order_id>"
1005
- }
1006
- ]
1007
- }
1008
- ]
1009
- }
1010
- }
1011
- ```
1012
-
1013
- > **Note**: Replace `<travel_progress_id>` and `<travel_order_id>` with actual values from step 8.1.
1014
-
1015
- ---
1016
-
1017
- ## Step 9: Test Weather Check Guard (Optional)
1018
-
1019
- Test the weather check Guard independently to verify weather data is correctly stored.
1020
-
1021
- **Prompt**: Test "weather_check_guard" with a sunny day timestamp.
1022
-
1023
- ```json
1024
- {
1025
- "operation_type": "gen_passport",
1026
- "data": {
1027
- "guard": "weather_check_guard",
1028
- "info": {
1029
- "type": "submission",
1030
- "guard": [
1031
- {
1032
- "object": "weather_check_guard",
1033
- "impack": true
1034
- }
1035
- ],
1036
- "submission": [
1037
- {
1038
- "guard": "weather_check_guard",
1039
- "submission": [
1040
- {
1041
- "identifier": 2,
1042
- "b_submission": true,
1043
- "value_type": "U64",
1044
- "value": 1745884800000
1045
- }
1046
- ]
1047
- }
1048
- ]
1049
- }
1050
- },
1051
- "env": {
1052
- "account": "travel_provider_v1",
1053
- "network": "testnet"
1054
- }
1055
- }
1056
- ```
1057
-
1058
- > **Note**: Replace the timestamp with one of the sunny day timestamps from step 0.1 (DAY1-DAY4). This should pass.
1059
-
1060
- Test with a rainy day to verify rejection:
1061
-
1062
- **Prompt**: Test "weather_check_guard" with a rainy day timestamp.
1063
-
1064
- ```json
1065
- {
1066
- "operation_type": "gen_passport",
1067
- "data": {
1068
- "guard": "weather_check_guard",
1069
- "info": {
1070
- "type": "submission",
1071
- "guard": [
1072
- {
1073
- "object": "weather_check_guard",
1074
- "impack": true
1075
- }
1076
- ],
1077
- "submission": [
1078
- {
1079
- "guard": "weather_check_guard",
1080
- "submission": [
1081
- {
1082
- "identifier": 2,
1083
- "b_submission": true,
1084
- "value_type": "U64",
1085
- "value": 1746230400000
1086
- }
1087
- ]
1088
- }
1089
- ]
1090
- }
1091
- },
1092
- "env": {
1093
- "account": "travel_provider_v1",
1094
- "network": "testnet"
1095
- }
1096
- }
1097
- ```
1098
-
1099
- > **Note**: Replace the timestamp with the rainy day timestamp (DAY5). This should fail because the weather is "rainy", not "sunny".
1100
-
1101
- ---
1102
-
1103
- ## Execution Checklist
1104
-
1105
- - [ ] Create `travel_provider`, `weather_provider`, `alice` accounts
1106
- - [ ] Get test tokens for all accounts
1107
- - [ ] Step 0.1: Calculate weather timestamps
1108
- - [ ] Step 0.2: Create `weather_repo` Repository
1109
- - [ ] Step 0.3: Add "Condition" policy to repository
1110
- - [ ] Step 0.4: Add weather data (5 days)
1111
- - [ ] Step 1: Create `travel_permission`
1112
- - [ ] Step 2: Create `travel_arbitration`
1113
- - [ ] Step 3.1: Create `weather_check_guard` (update weather_repo address)
1114
- - [ ] Step 3.2: Create `travel_complete_guard`
1115
- - [ ] Step 3.3: Create `travel_cancel_guard`
1116
- - [ ] Step 4: Create `travel_machine` (with nodes including Complete/Cancel, published)
1117
- - [ ] Step 5: Create and publish `travel_service` (with machine, arbitration, sales, order_allocators)
1118
- - [ ] Step 6: Unpause Service
1119
- - [ ] Step 7: Verify Service configuration
1120
- - [ ] Step 8.1: Create test travel order (as alice)
1121
- - [ ] Step 8.2: Advance Initial -> Start
1122
- - [ ] Step 8.3: Advance Start -> Buy Insurance
1123
- - [ ] Step 8.4: Advance Buy Insurance -> SPA
1124
- - [ ] Step 8.5: Advance SPA -> Ice Scooting
1125
- - [ ] Step 8.6: Wait 1s, advance Ice Scooting -> Complete
1126
- - [ ] Step 9: Test weather check Guard (sunny passes, rainy fails)
1127
-
1128
- ---
1129
-
1130
- ## Best Practices
1131
-
1132
- ### 1. Machine Node Configuration
1133
-
1134
- Ensure at least one node has a pair with `prev_node: ""` (empty string). This defines the entry point from the initial state where Progress starts with `current: ""`.
1135
-
1136
- ### 2. Service Publish Requires order_allocators
1137
-
1138
- Always include the `order_allocators` field when publishing a Service. This defines how order revenue is distributed.
1139
-
1140
- ### 3. Progress Operation Format
1141
-
1142
- Use the `operate` field with `operation` object containing `next_node_name` and `forward`, not the `task` field.
1143
-
1144
- ### 4. Repository Data Policy
1145
-
1146
- When creating a Repository, include policies in the initial `policies` field instead of adding them later (this avoids "Invalid policy name" errors).
1147
-
1148
- ### 5. Submission Format
1149
-
1150
- Ensure submission items include `b_submission: true` for values submitted at runtime during progress advancement.
1151
-
1152
- ---
1153
-
1154
- ## See Also
1155
-
1156
- - [Insurance Example](../Insurance/Insurance.md) - The insurance service used as sub-order
1157
- - [WOWOK Documentation](../../skills/WOWOK.md) - Core WoWok protocol documentation