@wowok/skills 1.1.8 → 1.1.10
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/LICENSE +36 -0
- package/README.md +1 -8
- package/examples/Insurance/Insurance.md +218 -90
- package/examples/MyShop/MyShop.md +513 -245
- package/examples/MyShop/myshop_machine_nodes.json +87 -0
- package/examples/MyShop_Advanced/MyShop_Advanced.md +633 -228
- package/examples/ThreeBody_Signature/ThreeBody_Signature.md +195 -202
- package/examples/Travel/Travel.md +775 -487
- package/examples/Travel/calc-weather-timestamps.js +9 -5
- package/package.json +4 -3
- package/wowok-tools/SKILL.md +85 -0
- package/examples/Insurance/Insurance_TestResults.md +0 -481
- package/examples/Insurance/insurance_complete_guard_v1.json +0 -50
- package/examples/MyShop/MyShop_TestResults.md +0 -1003
- package/examples/MyShop_Advanced/MyShop_Advanced_MerchantSystem_TestResults.md +0 -1297
- package/examples/MyShop_Advanced/MyShop_Advanced_OrderFlow_TestResults.md +0 -743
- package/examples/MyShop_Advanced/machine_nodes.json +0 -222
- package/examples/MyShop_Advanced/three_body_signature.wip +0 -30
- package/examples/ThreeBody_Signature/ThreeBody_Signature_TestResults.md +0 -599
- package/examples/Travel/Travel_TestResults.md +0 -743
- package/examples/Travel/travel_machine_v2_export.json +0 -104
- package/examples/Travel/weather_check_guard_v1.json +0 -51
|
@@ -2,8 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
A complete e-commerce example demonstrating how to build an online store using WoWok protocol. This guide covers both merchant setup and customer order workflows.
|
|
4
4
|
|
|
5
|
-
> 📋 **View Actual Execution Results**: See [MyShop_TestResults.md](MyShop_TestResults.md) for real testnet execution results with actual object addresses and transaction outputs.
|
|
6
|
-
|
|
7
5
|
---
|
|
8
6
|
|
|
9
7
|
## Core Requirements & Features
|
|
@@ -15,7 +13,6 @@ A complete e-commerce example demonstrating how to build an online store using W
|
|
|
15
13
|
| **Permission Control** | Role-based access for merchant and customer operations | Permission object with custom indexes for merchant operations |
|
|
16
14
|
| **Arbitration Support** | Dispute resolution mechanism | Arbitration object for handling order conflicts |
|
|
17
15
|
| **WIP Verification** | Product authenticity verification via WIP files | WIP hash stored in Service for customer verification |
|
|
18
|
-
| **Discount System** | Coupon and promotional code support | Discount object with time-limited offers |
|
|
19
16
|
| **Customer Communication** | Secure messaging between merchant and customer | Contact objects for pre-sales and after-sales support |
|
|
20
17
|
|
|
21
18
|
### Key Design Decisions
|
|
@@ -54,8 +51,7 @@ This example demonstrates a toy store e-commerce system with the following featu
|
|
|
54
51
|
│ │ • Machine (Workflow) │ │ • Create Order │ │
|
|
55
52
|
│ │ • Service (Products) │◄──►│ • Send Private Info(*) │ │
|
|
56
53
|
│ │ • Allocation (Payment) │ │ • Track Progress │ │
|
|
57
|
-
│ │ •
|
|
58
|
-
│ │ • Contact (Messaging) │ │ • Receive Goods │ │
|
|
54
|
+
│ │ • Contact (Messaging) │ │ • Order Complete │ │
|
|
59
55
|
│ └─────────────────────────┘ └─────────────────────────┘ │
|
|
60
56
|
│ │
|
|
61
57
|
│ Optional: Arbitration (Dispute Resolution) │
|
|
@@ -73,13 +69,13 @@ This example demonstrates a toy store e-commerce system with the following featu
|
|
|
73
69
|
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
|
|
74
70
|
│ │
|
|
75
71
|
│ ┌──────────────┐ │
|
|
76
|
-
└───────────────────►│
|
|
72
|
+
└───────────────────►│ Cancelled │◄───────────────────────┘
|
|
77
73
|
(Cancel Order) │(Final State) │ (Complete Order)
|
|
78
74
|
└──────────────┘
|
|
79
75
|
```
|
|
80
76
|
|
|
81
|
-
**Normal Flow**: Order Confirmation → Shipping → In Transit → Completed
|
|
82
|
-
**Alternative**: Order Confirmation →
|
|
77
|
+
**Normal Flow**: Order Confirmation → Shipping → In Transit → Completed
|
|
78
|
+
**Alternative**: Order Confirmation → Cancelled (if customer cancels before shipping)
|
|
83
79
|
|
|
84
80
|
---
|
|
85
81
|
|
|
@@ -100,7 +96,8 @@ Before starting, ensure you have:
|
|
|
100
96
|
```json
|
|
101
97
|
{
|
|
102
98
|
"gen": {
|
|
103
|
-
"name": "myshop_merchant"
|
|
99
|
+
"name": "myshop_merchant",
|
|
100
|
+
"replaceExistName": true
|
|
104
101
|
}
|
|
105
102
|
}
|
|
106
103
|
```
|
|
@@ -133,7 +130,8 @@ First, create a Permission object to manage access control for your store operat
|
|
|
133
130
|
"object": {
|
|
134
131
|
"name": "myshop_permission_v2",
|
|
135
132
|
"tags": ["ecommerce", "toys", "shop"],
|
|
136
|
-
"onChain": false
|
|
133
|
+
"onChain": false,
|
|
134
|
+
"replaceExistName": true
|
|
137
135
|
},
|
|
138
136
|
"description": "Permission management for MyShop toy store"
|
|
139
137
|
},
|
|
@@ -158,7 +156,8 @@ Create a Machine to define the order processing workflow. This includes nodes fo
|
|
|
158
156
|
"data": {
|
|
159
157
|
"object": {
|
|
160
158
|
"name": "myshop_machine_v2",
|
|
161
|
-
"permission": "myshop_permission_v2"
|
|
159
|
+
"permission": "myshop_permission_v2",
|
|
160
|
+
"replaceExistName": true
|
|
162
161
|
},
|
|
163
162
|
"description": "Order processing workflow for MyShop toy store"
|
|
164
163
|
},
|
|
@@ -171,7 +170,7 @@ Create a Machine to define the order processing workflow. This includes nodes fo
|
|
|
171
170
|
|
|
172
171
|
---
|
|
173
172
|
|
|
174
|
-
### Step 3
|
|
173
|
+
### Step 3: Machine Workflow Design
|
|
175
174
|
|
|
176
175
|
Before adding nodes, let's understand the order processing workflow:
|
|
177
176
|
|
|
@@ -246,10 +245,10 @@ Before adding nodes, let's understand the order processing workflow:
|
|
|
246
245
|
│ │ │ │ │
|
|
247
246
|
│ │ ▼ │ │
|
|
248
247
|
│ │ ┌──────────────┐ │ │
|
|
249
|
-
│ │ │
|
|
250
|
-
│ │ │
|
|
248
|
+
│ │ │ Cancelled │ │ │
|
|
249
|
+
│ │ │ (Final State)│ │ │
|
|
251
250
|
│ │ └──────────────┘ │ │
|
|
252
|
-
│ │ │
|
|
251
|
+
│ │ │ │
|
|
253
252
|
│ └───────────────────────────────────────────────────────────────────────┘
|
|
254
253
|
│ │
|
|
255
254
|
│ Legend: │
|
|
@@ -263,10 +262,11 @@ Before adding nodes, let's understand the order processing workflow:
|
|
|
263
262
|
|
|
264
263
|
| Node | Name | Description | Threshold | Forwards |
|
|
265
264
|
|------|------|-------------|-----------|----------|
|
|
266
|
-
| 1 | Order Confirmation | Initial state after order creation | 0 | Confirm Order (Merchant)
|
|
265
|
+
| 1 | Order Confirmation | Initial state after order creation | 0 | Confirm Order (Merchant) |
|
|
267
266
|
| 2 | Shipping | Merchant prepares and ships goods | 1 | Ship Goods (Merchant) |
|
|
268
267
|
| 3 | In Transit | Goods are being delivered | 1 | Confirm Delivery (Merchant) |
|
|
269
268
|
| 4 | Completed | Order successfully completed | 1 | Complete Order (Customer) |
|
|
269
|
+
| 5 | Cancelled | Order cancelled by customer (from Order Confirmation) | 0 | Cancel Order (Customer) |
|
|
270
270
|
|
|
271
271
|
**Permission Index Mapping:**
|
|
272
272
|
- `1000` - Merchant confirms order
|
|
@@ -281,9 +281,9 @@ Before adding nodes, let's understand the order processing workflow:
|
|
|
281
281
|
|
|
282
282
|
### Step 4: Add Workflow Nodes
|
|
283
283
|
|
|
284
|
-
Add the workflow nodes to the Machine for order processing.
|
|
284
|
+
Add the workflow nodes to the Machine for order processing. The initial pair (prev_node: "") defines transitions from the empty starting state.
|
|
285
285
|
|
|
286
|
-
**Prompt**: Add workflow nodes to "myshop_machine_v2" including Order Confirmation, Shipping, In Transit, and
|
|
286
|
+
**Prompt**: Add workflow nodes to "myshop_machine_v2" including Order Confirmation, Shipping, In Transit, Completed, and Cancelled nodes.
|
|
287
287
|
|
|
288
288
|
```json
|
|
289
289
|
{
|
|
@@ -304,10 +304,16 @@ Add the workflow nodes to the Machine for order processing.
|
|
|
304
304
|
"name": "Confirm Order",
|
|
305
305
|
"permissionIndex": 1000,
|
|
306
306
|
"weight": 1
|
|
307
|
-
}
|
|
307
|
+
}
|
|
308
|
+
]
|
|
309
|
+
},
|
|
310
|
+
{
|
|
311
|
+
"prev_node": "Order Confirmation",
|
|
312
|
+
"threshold": 1,
|
|
313
|
+
"forwards": [
|
|
308
314
|
{
|
|
309
|
-
"name": "
|
|
310
|
-
"
|
|
315
|
+
"name": "Ship Goods",
|
|
316
|
+
"permissionIndex": 1001,
|
|
311
317
|
"weight": 1
|
|
312
318
|
}
|
|
313
319
|
]
|
|
@@ -361,6 +367,22 @@ Add the workflow nodes to the Machine for order processing.
|
|
|
361
367
|
]
|
|
362
368
|
}
|
|
363
369
|
]
|
|
370
|
+
},
|
|
371
|
+
{
|
|
372
|
+
"name": "Cancelled",
|
|
373
|
+
"pairs": [
|
|
374
|
+
{
|
|
375
|
+
"prev_node": "Order Confirmation",
|
|
376
|
+
"threshold": 0,
|
|
377
|
+
"forwards": [
|
|
378
|
+
{
|
|
379
|
+
"name": "Cancel Order",
|
|
380
|
+
"namedOperator": "",
|
|
381
|
+
"weight": 1
|
|
382
|
+
}
|
|
383
|
+
]
|
|
384
|
+
}
|
|
385
|
+
]
|
|
364
386
|
}
|
|
365
387
|
]
|
|
366
388
|
}
|
|
@@ -372,6 +394,8 @@ Add the workflow nodes to the Machine for order processing.
|
|
|
372
394
|
}
|
|
373
395
|
```
|
|
374
396
|
|
|
397
|
+
> **Note**: The "Cancel Order" forward is defined on the "Cancelled" node with `prev_node: "Order Confirmation"`. This means cancellation can only happen AFTER the merchant confirms the order (transitions from "Order Confirmation" to "Cancelled"). The "Cancelled" node is a terminal state with no further forwards.
|
|
398
|
+
|
|
375
399
|
---
|
|
376
400
|
|
|
377
401
|
### Step 5: Publish the Machine
|
|
@@ -393,13 +417,14 @@ Publish the Machine to make it available for creating orders.
|
|
|
393
417
|
}
|
|
394
418
|
}
|
|
395
419
|
```
|
|
420
|
+
|
|
396
421
|
---
|
|
397
422
|
|
|
398
|
-
### Step
|
|
423
|
+
### Step 6: Create Contact Object for Customer Service
|
|
399
424
|
|
|
400
425
|
Create a Contact object to enable encrypted communication between customers and the store for after-sales support.
|
|
401
426
|
|
|
402
|
-
####
|
|
427
|
+
#### 6.1 Enable Merchant Messenger
|
|
403
428
|
|
|
404
429
|
**Prompt**: Enable messenger for the merchant account.
|
|
405
430
|
|
|
@@ -412,7 +437,7 @@ Create a Contact object to enable encrypted communication between customers and
|
|
|
412
437
|
}
|
|
413
438
|
```
|
|
414
439
|
|
|
415
|
-
####
|
|
440
|
+
#### 6.2 Create After-Sales Contact Object
|
|
416
441
|
|
|
417
442
|
**Prompt**: Create a Contact object named "myshop_aftersales_contact_v2" with permission "myshop_permission_v2" for after-sales support.
|
|
418
443
|
|
|
@@ -422,7 +447,8 @@ Create a Contact object to enable encrypted communication between customers and
|
|
|
422
447
|
"data": {
|
|
423
448
|
"object": {
|
|
424
449
|
"name": "myshop_aftersales_contact_v2",
|
|
425
|
-
"permission": "myshop_permission_v2"
|
|
450
|
+
"permission": "myshop_permission_v2",
|
|
451
|
+
"replaceExistName": true
|
|
426
452
|
},
|
|
427
453
|
"description": "MyShop after-sales support contact - we're here to help with orders, shipping, and returns",
|
|
428
454
|
"ims": {
|
|
@@ -442,17 +468,19 @@ Create a Contact object to enable encrypted communication between customers and
|
|
|
442
468
|
}
|
|
443
469
|
```
|
|
444
470
|
|
|
471
|
+
> **Note**: The `at` field accepts an **account name** (not messenger name). It will be resolved to the account's address. Alternatively, use the full address directly.
|
|
472
|
+
|
|
445
473
|
---
|
|
446
474
|
|
|
447
|
-
### Step
|
|
475
|
+
### Step 7: Create Guards for Fund Allocation
|
|
448
476
|
|
|
449
|
-
Before creating the Service,
|
|
477
|
+
Before creating the Service, create Guards that validate fund allocation conditions. These Guards ensure funds are only released when specific conditions are met.
|
|
450
478
|
|
|
451
|
-
####
|
|
479
|
+
#### 7.1 Create Withdraw Guard (Merchant Withdrawal)
|
|
452
480
|
|
|
453
|
-
|
|
481
|
+
Create a Guard that validates the order's Progress has reached the "Completed" node. This Guard uses `convert_witness: 100` (TypeOrderProgress) to query the Order's associated Progress object.
|
|
454
482
|
|
|
455
|
-
**Prompt**: Create a Guard named "myshop_withdraw_guard_v2" that verifies the order is
|
|
483
|
+
**Prompt**: Create a Guard named "myshop_withdraw_guard_v2" that verifies the order is completed before allowing merchant withdrawal.
|
|
456
484
|
|
|
457
485
|
```json
|
|
458
486
|
{
|
|
@@ -460,15 +488,17 @@ This Guard checks if the order has reached "Completed" status before allowing th
|
|
|
460
488
|
"data": {
|
|
461
489
|
"namedNew": {
|
|
462
490
|
"name": "myshop_withdraw_guard_v2",
|
|
463
|
-
"tags": ["
|
|
491
|
+
"tags": ["order", "completed", "withdraw"],
|
|
492
|
+
"onChain": false,
|
|
493
|
+
"replaceExistName": true
|
|
464
494
|
},
|
|
465
|
-
"description": "Verify order is
|
|
495
|
+
"description": "Verify order progress is at Completed node for merchant withdrawal",
|
|
466
496
|
"table": [
|
|
467
497
|
{
|
|
468
498
|
"identifier": 0,
|
|
469
499
|
"b_submission": true,
|
|
470
500
|
"value_type": "Address",
|
|
471
|
-
"name": "
|
|
501
|
+
"name": "order_address"
|
|
472
502
|
},
|
|
473
503
|
{
|
|
474
504
|
"identifier": 1,
|
|
@@ -479,25 +509,22 @@ This Guard checks if the order has reached "Completed" status before allowing th
|
|
|
479
509
|
}
|
|
480
510
|
],
|
|
481
511
|
"root": {
|
|
482
|
-
"type": "
|
|
483
|
-
"
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
"
|
|
489
|
-
"
|
|
490
|
-
"identifier": 0,
|
|
491
|
-
"convert_witness": 100
|
|
492
|
-
},
|
|
493
|
-
"parameters": []
|
|
512
|
+
"type": "logic_equal",
|
|
513
|
+
"nodes": [
|
|
514
|
+
{
|
|
515
|
+
"type": "query",
|
|
516
|
+
"query": 1253,
|
|
517
|
+
"object": {
|
|
518
|
+
"identifier": 0,
|
|
519
|
+
"convert_witness": 100
|
|
494
520
|
},
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
521
|
+
"parameters": []
|
|
522
|
+
},
|
|
523
|
+
{
|
|
524
|
+
"type": "identifier",
|
|
525
|
+
"identifier": 1
|
|
526
|
+
}
|
|
527
|
+
]
|
|
501
528
|
}
|
|
502
529
|
},
|
|
503
530
|
"env": {
|
|
@@ -507,16 +534,20 @@ This Guard checks if the order has reached "Completed" status before allowing th
|
|
|
507
534
|
}
|
|
508
535
|
```
|
|
509
536
|
|
|
510
|
-
**
|
|
511
|
-
-
|
|
512
|
-
-
|
|
513
|
-
-
|
|
537
|
+
**Guard Explanation:**
|
|
538
|
+
- **Table Item 0**: Order address (submitted when activating allocation)
|
|
539
|
+
- **Table Item 1**: Constant string "Completed" (the target node name)
|
|
540
|
+
- **convert_witness: 100**: TypeOrderProgress - converts Order to its associated Progress
|
|
541
|
+
- **Query "progress.current"**: Returns the current node name of the Progress
|
|
542
|
+
- **logic_equal**: Verifies current node equals "Completed"
|
|
514
543
|
|
|
515
|
-
|
|
544
|
+
> **Note**: The Guard `root` field directly specifies the GuardNode (e.g., `type: "logic_equal"`), not wrapped in a `type: "node"` object.
|
|
516
545
|
|
|
517
|
-
|
|
546
|
+
#### 7.2 Create Refund Guard (Customer Refund)
|
|
518
547
|
|
|
519
|
-
|
|
548
|
+
Create a Guard for customer refunds when order is cancelled.
|
|
549
|
+
|
|
550
|
+
**Prompt**: Create a Guard named "myshop_refund_guard_v2" for customer refund validation.
|
|
520
551
|
|
|
521
552
|
```json
|
|
522
553
|
{
|
|
@@ -524,44 +555,43 @@ For scenarios where customers need refunds before order completion.
|
|
|
524
555
|
"data": {
|
|
525
556
|
"namedNew": {
|
|
526
557
|
"name": "myshop_refund_guard_v2",
|
|
527
|
-
"tags": ["
|
|
558
|
+
"tags": ["order", "cancelled", "refund"],
|
|
559
|
+
"onChain": false,
|
|
560
|
+
"replaceExistName": true
|
|
528
561
|
},
|
|
529
|
-
"description": "
|
|
562
|
+
"description": "Verify order progress is at Cancelled node for customer refund",
|
|
530
563
|
"table": [
|
|
531
564
|
{
|
|
532
565
|
"identifier": 0,
|
|
533
566
|
"b_submission": true,
|
|
534
567
|
"value_type": "Address",
|
|
535
|
-
"name": "
|
|
568
|
+
"name": "order_address"
|
|
536
569
|
},
|
|
537
570
|
{
|
|
538
571
|
"identifier": 1,
|
|
539
572
|
"b_submission": false,
|
|
540
573
|
"value_type": "String",
|
|
541
|
-
"value": "
|
|
542
|
-
"name": "
|
|
574
|
+
"value": "Cancelled",
|
|
575
|
+
"name": "cancelled_node"
|
|
543
576
|
}
|
|
544
577
|
],
|
|
545
578
|
"root": {
|
|
546
|
-
"type": "
|
|
547
|
-
"
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
"
|
|
553
|
-
"
|
|
554
|
-
"identifier": 0,
|
|
555
|
-
"convert_witness": 100
|
|
556
|
-
},
|
|
557
|
-
"parameters": []
|
|
579
|
+
"type": "logic_equal",
|
|
580
|
+
"nodes": [
|
|
581
|
+
{
|
|
582
|
+
"type": "query",
|
|
583
|
+
"query": 1253,
|
|
584
|
+
"object": {
|
|
585
|
+
"identifier": 0,
|
|
586
|
+
"convert_witness": 100
|
|
558
587
|
},
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
588
|
+
"parameters": []
|
|
589
|
+
},
|
|
590
|
+
{
|
|
591
|
+
"type": "identifier",
|
|
592
|
+
"identifier": 1
|
|
593
|
+
}
|
|
594
|
+
]
|
|
565
595
|
}
|
|
566
596
|
},
|
|
567
597
|
"env": {
|
|
@@ -570,15 +600,16 @@ For scenarios where customers need refunds before order completion.
|
|
|
570
600
|
}
|
|
571
601
|
}
|
|
572
602
|
```
|
|
603
|
+
|
|
573
604
|
---
|
|
574
605
|
|
|
575
|
-
### Step
|
|
606
|
+
### Step 8: Create Service (Store)
|
|
576
607
|
|
|
577
608
|
Create the Service object that represents your online store with products. This step binds all previously created components together.
|
|
578
609
|
|
|
579
|
-
> **Important**: For Service creation,
|
|
610
|
+
> **Important**: For Service creation, provide a complete configuration including machine, order_allocators with Guards, and products. The Service will be created and published in a single transaction.
|
|
580
611
|
|
|
581
|
-
####
|
|
612
|
+
#### 8.1 Understanding Order Allocators
|
|
582
613
|
|
|
583
614
|
The `order_allocators` configuration defines how order payments are distributed:
|
|
584
615
|
|
|
@@ -591,10 +622,12 @@ The `order_allocators` configuration defines how order payments are distributed:
|
|
|
591
622
|
|
|
592
623
|
**Recipient Types:**
|
|
593
624
|
- `{ "Signer": "signer" }` - Transaction sender (merchant)
|
|
594
|
-
- `{ "Entity": { "
|
|
625
|
+
- `{ "Entity": { "name_or_address": "..." } }` - Specific address or account name
|
|
595
626
|
- `{ "GuardIdentifier": 0 }` - Address from Guard table
|
|
596
627
|
|
|
597
|
-
|
|
628
|
+
> **Design Decision — Refund Recipient**: When using `{ "GuardIdentifier": 0 }` in the refund allocation, the refund is sent to the **Order object's on-chain address** (not the customer's wallet address). This is by design: the Order object acts as an escrow holding the refunded payment at its own address. The customer subsequently claims the refund from the Order object via a separate withdraw operation. This two-step design ensures the refund is traceable on-chain and tied to the specific order, providing better dispute resolution and audit trail.
|
|
629
|
+
|
|
630
|
+
#### 8.2 Create and Publish Service
|
|
598
631
|
|
|
599
632
|
**Prompt**: Create and publish a Service named "myshop_service_v2" with machine "myshop_machine_v2", order allocation using Guards, after-sales contact, and toy products.
|
|
600
633
|
|
|
@@ -607,7 +640,8 @@ The `order_allocators` configuration defines how order payments are distributed:
|
|
|
607
640
|
"type_parameter": "0x2::wow::WOW",
|
|
608
641
|
"permission": "myshop_permission_v2",
|
|
609
642
|
"tags": ["ecommerce", "toys", "store"],
|
|
610
|
-
"onChain": false
|
|
643
|
+
"onChain": false,
|
|
644
|
+
"replaceExistName": true
|
|
611
645
|
},
|
|
612
646
|
"description": "MyShop - Top quality toys for children",
|
|
613
647
|
"location": "Online Store",
|
|
@@ -646,7 +680,7 @@ The `order_allocators` configuration defines how order payments are distributed:
|
|
|
646
680
|
"price": 3000000000,
|
|
647
681
|
"stock": 100,
|
|
648
682
|
"suspension": false,
|
|
649
|
-
"wip": "",
|
|
683
|
+
"wip": "https://wowok.net/test/three_body.wip",
|
|
650
684
|
"wip_hash": ""
|
|
651
685
|
},
|
|
652
686
|
{
|
|
@@ -654,7 +688,7 @@ The `order_allocators` configuration defines how order payments are distributed:
|
|
|
654
688
|
"price": 5000000000,
|
|
655
689
|
"stock": 50,
|
|
656
690
|
"suspension": false,
|
|
657
|
-
"wip": "",
|
|
691
|
+
"wip": "https://wowok.net/test/three_body.wip",
|
|
658
692
|
"wip_hash": ""
|
|
659
693
|
},
|
|
660
694
|
{
|
|
@@ -662,7 +696,7 @@ The `order_allocators` configuration defines how order payments are distributed:
|
|
|
662
696
|
"price": 2000000000,
|
|
663
697
|
"stock": 75,
|
|
664
698
|
"suspension": false,
|
|
665
|
-
"wip": "",
|
|
699
|
+
"wip": "https://wowok.net/test/three_body.wip",
|
|
666
700
|
"wip_hash": ""
|
|
667
701
|
}
|
|
668
702
|
]
|
|
@@ -677,34 +711,36 @@ The `order_allocators` configuration defines how order payments are distributed:
|
|
|
677
711
|
}
|
|
678
712
|
```
|
|
679
713
|
|
|
680
|
-
|
|
714
|
+
**Important Notes:**
|
|
681
715
|
- After publishing, `machine`, `order_allocators`, and `arbitrations` become **immutable**
|
|
682
716
|
- Ensure your Guards and allocation logic are correct before publishing
|
|
683
717
|
- The `sharing` value of `10000` represents 100% (rate mode uses 0-10000 scale)
|
|
684
718
|
|
|
685
719
|
---
|
|
686
720
|
|
|
687
|
-
### Step
|
|
721
|
+
### Step 9: Update Product Pricing (Optional)
|
|
688
722
|
|
|
689
|
-
|
|
723
|
+
To offer promotional pricing, update product prices using the `sales` operation with `op: "set"`:
|
|
690
724
|
|
|
691
|
-
**Prompt**:
|
|
725
|
+
**Prompt**: Update the price of "Play Purse Set 35PCS" to 2.4WOW for a promotion.
|
|
692
726
|
|
|
693
727
|
```json
|
|
694
728
|
{
|
|
695
729
|
"operation_type": "service",
|
|
696
730
|
"data": {
|
|
697
731
|
"object": "myshop_service_v2",
|
|
698
|
-
"
|
|
699
|
-
"
|
|
700
|
-
"
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
732
|
+
"sales": {
|
|
733
|
+
"op": "set",
|
|
734
|
+
"sales": [
|
|
735
|
+
{
|
|
736
|
+
"name": "Play Purse Set 35PCS",
|
|
737
|
+
"price": 2400000000,
|
|
738
|
+
"stock": 100,
|
|
739
|
+
"suspension": false,
|
|
740
|
+
"wip": "https://wowok.net/test/three_body.wip",
|
|
741
|
+
"wip_hash": ""
|
|
742
|
+
}
|
|
743
|
+
]
|
|
708
744
|
}
|
|
709
745
|
},
|
|
710
746
|
"env": {
|
|
@@ -729,12 +765,13 @@ Create a customer account:
|
|
|
729
765
|
```json
|
|
730
766
|
{
|
|
731
767
|
"gen": {
|
|
732
|
-
"name": "myshop_customer"
|
|
768
|
+
"name": "myshop_customer",
|
|
769
|
+
"replaceExistName": true
|
|
733
770
|
}
|
|
734
771
|
}
|
|
735
772
|
```
|
|
736
773
|
|
|
737
|
-
**Get test tokens
|
|
774
|
+
**Get test tokens** (request twice to ensure sufficient balance for order + gas fees):
|
|
738
775
|
|
|
739
776
|
```json
|
|
740
777
|
{
|
|
@@ -745,6 +782,8 @@ Create a customer account:
|
|
|
745
782
|
}
|
|
746
783
|
```
|
|
747
784
|
|
|
785
|
+
> **Note**: The faucet provides 3 WOW per call. Since orders require payment plus gas fees, request faucet tokens twice to ensure sufficient balance.
|
|
786
|
+
|
|
748
787
|
---
|
|
749
788
|
|
|
750
789
|
### Step 1: Query Service Products
|
|
@@ -786,6 +825,15 @@ Customer creates an order by purchasing products from the Service.
|
|
|
786
825
|
"total_pay": {
|
|
787
826
|
"balance": 3000000000
|
|
788
827
|
}
|
|
828
|
+
},
|
|
829
|
+
"namedNewOrder": {
|
|
830
|
+
"name": "myshop_test_order"
|
|
831
|
+
},
|
|
832
|
+
"namedNewProgress": {
|
|
833
|
+
"name": "myshop_test_progress"
|
|
834
|
+
},
|
|
835
|
+
"namedNewAllocation": {
|
|
836
|
+
"name": "myshop_test_allocation"
|
|
789
837
|
}
|
|
790
838
|
}
|
|
791
839
|
},
|
|
@@ -800,7 +848,7 @@ Customer creates an order by purchasing products from the Service.
|
|
|
800
848
|
|
|
801
849
|
### Step 2.1: Send Shipping Address via Messenger (Privacy Protection)
|
|
802
850
|
|
|
803
|
-
After creating the order, the customer
|
|
851
|
+
After creating the order, the customer sends their shipping address and contact information to the merchant's after-sales support team. This is done securely through the Messenger system to protect privacy - the information is never stored on-chain.
|
|
804
852
|
|
|
805
853
|
```
|
|
806
854
|
┌─────────────────────────────────────────────────────────────────────────────────────┐
|
|
@@ -809,9 +857,9 @@ After creating the order, the customer needs to send their shipping address and
|
|
|
809
857
|
│ │
|
|
810
858
|
│ ┌──────────────────┐ End-to-End Encrypted ┌──────────────────┐ │
|
|
811
859
|
│ │ │◄──────────────────────────────────────►│ │ │
|
|
812
|
-
│ │ myshop_customer │ Messenger Channel │
|
|
813
|
-
│ │ (Customer) │ (Never on-chain) │ (After-Sales
|
|
814
|
-
│ │ │ │ Support
|
|
860
|
+
│ │ myshop_customer │ Messenger Channel │ myshop_merchant │ │
|
|
861
|
+
│ │ (Customer) │ (Never on-chain) │ (After-Sales │ │
|
|
862
|
+
│ │ │ │ Support) │ │
|
|
815
863
|
│ └────────┬─────────┘ └────────┬─────────┘ │
|
|
816
864
|
│ │ │ │
|
|
817
865
|
│ │ 1. Send shipping address │ │
|
|
@@ -833,10 +881,9 @@ After creating the order, the customer needs to send their shipping address and
|
|
|
833
881
|
│ └──────────────────┘ └──────────────────┘ │
|
|
834
882
|
│ │
|
|
835
883
|
│ Privacy Guarantees: │
|
|
836
|
-
│
|
|
837
|
-
│
|
|
838
|
-
│
|
|
839
|
-
│ ✅ WTS support - Can generate verifiable conversation records if needed │
|
|
884
|
+
│ - End-to-end encryption - Only customer and merchant can read │
|
|
885
|
+
│ - No on-chain storage - Message content never touches blockchain │
|
|
886
|
+
│ - Verifiable identity - Contact object confirms who you're talking to │
|
|
840
887
|
│ │
|
|
841
888
|
└─────────────────────────────────────────────────────────────────────────────────────┘
|
|
842
889
|
```
|
|
@@ -848,47 +895,51 @@ After creating the order, the customer needs to send their shipping address and
|
|
|
848
895
|
```json
|
|
849
896
|
{
|
|
850
897
|
"messenger": {
|
|
851
|
-
"m": "customer_messenger"
|
|
852
|
-
|
|
853
|
-
|
|
898
|
+
"m": "customer_messenger",
|
|
899
|
+
"name_or_account": "myshop_customer"
|
|
900
|
+
}
|
|
854
901
|
}
|
|
855
902
|
```
|
|
856
903
|
|
|
857
904
|
#### 2.1.2 Customer Sends Shipping Information
|
|
858
905
|
|
|
859
|
-
**Prompt**: Customer "myshop_customer" sends shipping address and contact information to
|
|
906
|
+
**Prompt**: Customer "myshop_customer" sends shipping address and contact information to merchant "myshop_merchant" via encrypted messenger.
|
|
860
907
|
|
|
861
908
|
```json
|
|
862
909
|
{
|
|
863
910
|
"operation": "send_message",
|
|
864
911
|
"from": "myshop_customer",
|
|
865
|
-
"to": "
|
|
866
|
-
"content": "Order Shipping Information:\n\nOrder ID:
|
|
912
|
+
"to": "myshop_merchant",
|
|
913
|
+
"content": "Order Shipping Information:\n\nOrder ID: 0xa6db...3d5\nProduct: Play Purse Set 35PCS\n\nRecipient: Zhang San\nPhone: 138-0000-0000\nAddress: Building 123, Unit 456, Room 789\n Chaoyang District, Beijing\n China, 100000\n\nPlease confirm receipt of this information."
|
|
867
914
|
}
|
|
868
915
|
```
|
|
869
916
|
|
|
870
|
-
|
|
917
|
+
> **Note**: Replace the Order ID with your actual order object address from Step 2.
|
|
918
|
+
>
|
|
919
|
+
> **Spam Protection**: The Messenger server allows only ONE message to a stranger (non-friend) before the recipient must reply. If the customer already sent an initial message to the merchant, the merchant must reply first before the customer can send additional messages. Once both parties have exchanged messages, they become "friends" and can send unlimited messages. If you encounter "Spam protection denied: You can only send one stranger message, wait for recipient to reply", have the merchant send a reply first.
|
|
871
920
|
|
|
872
|
-
|
|
921
|
+
#### 2.1.3 Merchant Confirms Receipt
|
|
922
|
+
|
|
923
|
+
**Prompt**: Merchant "myshop_merchant" views the message and sends confirmation to customer.
|
|
873
924
|
|
|
874
925
|
```json
|
|
875
926
|
{
|
|
876
927
|
"operation": "send_message",
|
|
877
|
-
"from": "
|
|
928
|
+
"from": "myshop_merchant",
|
|
878
929
|
"to": "myshop_customer",
|
|
879
|
-
"content": "Dear Customer,\n\nWe have received your shipping information:\n
|
|
930
|
+
"content": "Dear Customer,\n\nWe have received your shipping information:\n- Order ID: 0xa6db...3d5 confirmed\n- Shipping address verified\n- Contact phone: 138-0000-0000\n\nYour order will be processed within 24 hours. We'll send you the tracking number once shipped.\n\nThank you for shopping with MyShop!"
|
|
880
931
|
}
|
|
881
932
|
```
|
|
882
933
|
|
|
883
934
|
#### 2.1.4 View Conversation History
|
|
884
935
|
|
|
885
|
-
**Prompt**: View the conversation between customer and
|
|
936
|
+
**Prompt**: View the conversation between customer and merchant to confirm both messages were delivered.
|
|
886
937
|
|
|
887
938
|
```json
|
|
888
939
|
{
|
|
889
940
|
"operation": "watch_messages",
|
|
890
941
|
"filter": {
|
|
891
|
-
"peerAddress": "
|
|
942
|
+
"peerAddress": "myshop_merchant",
|
|
892
943
|
"account": "myshop_customer"
|
|
893
944
|
}
|
|
894
945
|
}
|
|
@@ -900,12 +951,13 @@ After creating the order, the customer needs to send their shipping address and
|
|
|
900
951
|
|
|
901
952
|
Customer can query the order status and progress.
|
|
902
953
|
|
|
903
|
-
**Prompt**: Query the order "
|
|
954
|
+
**Prompt**: Query the order "myshop_test_order" to check its current status and progress.
|
|
904
955
|
|
|
905
956
|
```json
|
|
906
957
|
{
|
|
907
958
|
"query_type": "onchain_objects",
|
|
908
|
-
"objects": ["
|
|
959
|
+
"objects": ["myshop_test_order"],
|
|
960
|
+
"no_cache": true
|
|
909
961
|
}
|
|
910
962
|
```
|
|
911
963
|
|
|
@@ -915,32 +967,34 @@ Customer can query the order status and progress.
|
|
|
915
967
|
|
|
916
968
|
Check the current workflow node of the order.
|
|
917
969
|
|
|
918
|
-
**Prompt**: Query the Progress "
|
|
970
|
+
**Prompt**: Query the Progress "myshop_test_progress" to see the current workflow node.
|
|
919
971
|
|
|
920
972
|
```json
|
|
921
973
|
{
|
|
922
974
|
"query_type": "onchain_objects",
|
|
923
|
-
"objects": ["
|
|
975
|
+
"objects": ["myshop_test_progress"],
|
|
976
|
+
"no_cache": true
|
|
924
977
|
}
|
|
925
978
|
```
|
|
979
|
+
|
|
926
980
|
---
|
|
927
981
|
|
|
928
982
|
### Step 5: Merchant Confirms Order
|
|
929
983
|
|
|
930
|
-
Merchant advances the order from "Order Confirmation"
|
|
984
|
+
Merchant advances the order from initial state to "Order Confirmation" node.
|
|
931
985
|
|
|
932
|
-
> **Note**:
|
|
986
|
+
> **Note**: Use `operation_type: "progress"` with `operate` to advance the workflow. The order is created with an empty initial node "", and the first step is to transition to "Order Confirmation" using "Confirm Order" forward.
|
|
933
987
|
|
|
934
|
-
**Prompt**: Advance the order "
|
|
988
|
+
**Prompt**: Advance the order "myshop_test_order" progress from initial state to "Order Confirmation" using the "Confirm Order" forward.
|
|
935
989
|
|
|
936
990
|
```json
|
|
937
991
|
{
|
|
938
|
-
"operation_type": "
|
|
992
|
+
"operation_type": "progress",
|
|
939
993
|
"data": {
|
|
940
|
-
"object": "
|
|
941
|
-
"
|
|
994
|
+
"object": "myshop_test_progress",
|
|
995
|
+
"operate": {
|
|
942
996
|
"operation": {
|
|
943
|
-
"next_node_name": "
|
|
997
|
+
"next_node_name": "Order Confirmation",
|
|
944
998
|
"forward": "Confirm Order"
|
|
945
999
|
},
|
|
946
1000
|
"hold": false,
|
|
@@ -953,22 +1007,23 @@ Merchant advances the order from "Order Confirmation" to "Shipping".
|
|
|
953
1007
|
}
|
|
954
1008
|
}
|
|
955
1009
|
```
|
|
1010
|
+
|
|
956
1011
|
---
|
|
957
1012
|
|
|
958
1013
|
### Step 6: Merchant Ships Order
|
|
959
1014
|
|
|
960
|
-
Merchant ships the order and advances
|
|
1015
|
+
Merchant ships the order and advances from "Order Confirmation" to "Shipping".
|
|
961
1016
|
|
|
962
|
-
**Prompt**: Advance the order
|
|
1017
|
+
**Prompt**: Advance the order progress from "Order Confirmation" to "Shipping" using the "Ship Goods" forward.
|
|
963
1018
|
|
|
964
1019
|
```json
|
|
965
1020
|
{
|
|
966
|
-
"operation_type": "
|
|
1021
|
+
"operation_type": "progress",
|
|
967
1022
|
"data": {
|
|
968
|
-
"object": "
|
|
969
|
-
"
|
|
1023
|
+
"object": "myshop_test_progress",
|
|
1024
|
+
"operate": {
|
|
970
1025
|
"operation": {
|
|
971
|
-
"next_node_name": "
|
|
1026
|
+
"next_node_name": "Shipping",
|
|
972
1027
|
"forward": "Ship Goods"
|
|
973
1028
|
},
|
|
974
1029
|
"hold": false,
|
|
@@ -981,22 +1036,23 @@ Merchant ships the order and advances to "In Transit".
|
|
|
981
1036
|
}
|
|
982
1037
|
}
|
|
983
1038
|
```
|
|
1039
|
+
|
|
984
1040
|
---
|
|
985
1041
|
|
|
986
1042
|
### Step 7: Confirm Delivery
|
|
987
1043
|
|
|
988
1044
|
Merchant or delivery service confirms the order has been delivered.
|
|
989
1045
|
|
|
990
|
-
**Prompt**: Advance the order
|
|
1046
|
+
**Prompt**: Advance the order progress from "Shipping" to "In Transit" using the "Confirm Delivery" forward.
|
|
991
1047
|
|
|
992
1048
|
```json
|
|
993
1049
|
{
|
|
994
|
-
"operation_type": "
|
|
1050
|
+
"operation_type": "progress",
|
|
995
1051
|
"data": {
|
|
996
|
-
"object": "
|
|
997
|
-
"
|
|
1052
|
+
"object": "myshop_test_progress",
|
|
1053
|
+
"operate": {
|
|
998
1054
|
"operation": {
|
|
999
|
-
"next_node_name": "
|
|
1055
|
+
"next_node_name": "In Transit",
|
|
1000
1056
|
"forward": "Confirm Delivery"
|
|
1001
1057
|
},
|
|
1002
1058
|
"hold": false,
|
|
@@ -1009,21 +1065,20 @@ Merchant or delivery service confirms the order has been delivered.
|
|
|
1009
1065
|
}
|
|
1010
1066
|
}
|
|
1011
1067
|
```
|
|
1068
|
+
|
|
1012
1069
|
---
|
|
1013
1070
|
|
|
1014
1071
|
### Step 8: Customer Completes Order
|
|
1015
1072
|
|
|
1016
1073
|
Customer confirms receipt and completes the order.
|
|
1017
1074
|
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
**Prompt**: Customer "myshop_customer" completes the order "0x5678...9abc" by advancing from "Completed" node using "Complete Order" forward.
|
|
1075
|
+
**Prompt**: Customer "myshop_customer" completes the order by advancing from "In Transit" to "Completed" node using "Complete Order" forward.
|
|
1021
1076
|
|
|
1022
1077
|
```json
|
|
1023
1078
|
{
|
|
1024
1079
|
"operation_type": "progress",
|
|
1025
1080
|
"data": {
|
|
1026
|
-
"object": "
|
|
1081
|
+
"object": "myshop_test_progress",
|
|
1027
1082
|
"operate": {
|
|
1028
1083
|
"operation": {
|
|
1029
1084
|
"next_node_name": "Completed",
|
|
@@ -1039,6 +1094,7 @@ Customer confirms receipt and completes the order.
|
|
|
1039
1094
|
}
|
|
1040
1095
|
}
|
|
1041
1096
|
```
|
|
1097
|
+
|
|
1042
1098
|
---
|
|
1043
1099
|
|
|
1044
1100
|
### Step 9: Merchant Withdraws Funds
|
|
@@ -1051,34 +1107,35 @@ After order completion, the merchant needs to:
|
|
|
1051
1107
|
|
|
1052
1108
|
First, activate the Allocation by submitting the Guard verification with the Order ID.
|
|
1053
1109
|
|
|
1054
|
-
> **Note**:
|
|
1110
|
+
> **Note**: The `alloc_by_guard` and `submission` fields require the actual Guard object address (0x...), not the local name. You can obtain the Guard address from the local mark list or by querying the Guard name.
|
|
1055
1111
|
|
|
1056
|
-
**Prompt**: Activate allocation "
|
|
1112
|
+
**Prompt**: Activate allocation "myshop_test_allocation" by verifying the withdraw guard with order "myshop_test_order".
|
|
1057
1113
|
|
|
1058
1114
|
```json
|
|
1059
1115
|
{
|
|
1060
1116
|
"operation_type": "allocation",
|
|
1061
1117
|
"data": {
|
|
1062
|
-
"object": "
|
|
1063
|
-
"alloc_by_guard": "
|
|
1118
|
+
"object": "myshop_test_allocation",
|
|
1119
|
+
"alloc_by_guard": "0x5af9...1074"
|
|
1064
1120
|
},
|
|
1065
1121
|
"submission": {
|
|
1066
1122
|
"type": "submission",
|
|
1067
1123
|
"guard": [
|
|
1068
1124
|
{
|
|
1069
|
-
"object": "
|
|
1125
|
+
"object": "0x5af9...1074",
|
|
1070
1126
|
"impack": true
|
|
1071
1127
|
}
|
|
1072
1128
|
],
|
|
1073
1129
|
"submission": [
|
|
1074
1130
|
{
|
|
1075
|
-
"guard": "
|
|
1131
|
+
"guard": "0x5af9...1074",
|
|
1076
1132
|
"submission": [
|
|
1077
1133
|
{
|
|
1078
1134
|
"identifier": 0,
|
|
1079
1135
|
"b_submission": true,
|
|
1080
1136
|
"value_type": "Address",
|
|
1081
|
-
"value": "
|
|
1137
|
+
"value": "0xa6db...3d5",
|
|
1138
|
+
"name": "order_address"
|
|
1082
1139
|
}
|
|
1083
1140
|
]
|
|
1084
1141
|
}
|
|
@@ -1092,6 +1149,8 @@ First, activate the Allocation by submitting the Guard verification with the Ord
|
|
|
1092
1149
|
}
|
|
1093
1150
|
```
|
|
1094
1151
|
|
|
1152
|
+
> **Note**: Replace the Guard address `0x5af9...1074` and Order address `0xa6db...3d5` with your actual object addresses. Use the full 64-character addresses in actual operations.
|
|
1153
|
+
|
|
1095
1154
|
#### 9.2 Withdraw Funds from Service
|
|
1096
1155
|
|
|
1097
1156
|
After the Allocation is activated, withdraw the funds from the Service.
|
|
@@ -1111,26 +1170,50 @@ After the Allocation is activated, withdraw the funds from the Service.
|
|
|
1111
1170
|
}
|
|
1112
1171
|
}
|
|
1113
1172
|
```
|
|
1173
|
+
|
|
1114
1174
|
---
|
|
1115
1175
|
|
|
1116
1176
|
## Alternative Flow: Order Cancellation
|
|
1117
1177
|
|
|
1118
1178
|
### Customer Cancels Order
|
|
1119
1179
|
|
|
1120
|
-
Customer can cancel the order
|
|
1180
|
+
Customer can cancel the order after the merchant confirms it. The "Cancel Order" forward transitions from "Order Confirmation" to "Cancelled". This requires the merchant to first confirm the order (advancing from the initial state "" to "Order Confirmation").
|
|
1121
1181
|
|
|
1122
|
-
|
|
1123
|
-
|
|
1124
|
-
**Prompt**: Customer "myshop_customer" cancels the order "0x5678...9abc" before merchant confirmation.
|
|
1182
|
+
**Step 1**: Merchant confirms the order (advances from "" to "Order Confirmation"):
|
|
1125
1183
|
|
|
1126
1184
|
```json
|
|
1127
1185
|
{
|
|
1128
1186
|
"operation_type": "progress",
|
|
1129
1187
|
"data": {
|
|
1130
|
-
"object": "
|
|
1188
|
+
"object": "myshop_test_progress",
|
|
1131
1189
|
"operate": {
|
|
1132
1190
|
"operation": {
|
|
1133
1191
|
"next_node_name": "Order Confirmation",
|
|
1192
|
+
"forward": "Confirm Order"
|
|
1193
|
+
},
|
|
1194
|
+
"hold": false,
|
|
1195
|
+
"message": "Order confirmed by merchant"
|
|
1196
|
+
}
|
|
1197
|
+
},
|
|
1198
|
+
"env": {
|
|
1199
|
+
"account": "myshop_merchant",
|
|
1200
|
+
"network": "testnet"
|
|
1201
|
+
}
|
|
1202
|
+
}
|
|
1203
|
+
```
|
|
1204
|
+
|
|
1205
|
+
**Step 2**: Customer cancels the order (advances from "Order Confirmation" to "Cancelled"):
|
|
1206
|
+
|
|
1207
|
+
**Prompt**: Customer "myshop_customer" cancels the order after merchant confirmation.
|
|
1208
|
+
|
|
1209
|
+
```json
|
|
1210
|
+
{
|
|
1211
|
+
"operation_type": "progress",
|
|
1212
|
+
"data": {
|
|
1213
|
+
"object": "myshop_test_progress",
|
|
1214
|
+
"operate": {
|
|
1215
|
+
"operation": {
|
|
1216
|
+
"next_node_name": "Cancelled",
|
|
1134
1217
|
"forward": "Cancel Order"
|
|
1135
1218
|
},
|
|
1136
1219
|
"hold": false,
|
|
@@ -1143,13 +1226,89 @@ Customer can cancel the order before it's confirmed.
|
|
|
1143
1226
|
}
|
|
1144
1227
|
}
|
|
1145
1228
|
```
|
|
1229
|
+
|
|
1230
|
+
> **Note**: Cancellation can only be done from the "Order Confirmation" state (after the merchant confirms the order, but before shipping). Once the order is shipped, cancellation is no longer possible through this forward.
|
|
1231
|
+
|
|
1232
|
+
### Customer Refund After Cancellation
|
|
1233
|
+
|
|
1234
|
+
After the order is cancelled, the customer can activate the refund allocation using the refund guard:
|
|
1235
|
+
|
|
1236
|
+
```json
|
|
1237
|
+
{
|
|
1238
|
+
"operation_type": "allocation",
|
|
1239
|
+
"data": {
|
|
1240
|
+
"object": "myshop_test_allocation",
|
|
1241
|
+
"alloc_by_guard": "0x5792...5d2c"
|
|
1242
|
+
},
|
|
1243
|
+
"submission": {
|
|
1244
|
+
"type": "submission",
|
|
1245
|
+
"guard": [
|
|
1246
|
+
{
|
|
1247
|
+
"object": "0x5792...5d2c",
|
|
1248
|
+
"impack": true
|
|
1249
|
+
}
|
|
1250
|
+
],
|
|
1251
|
+
"submission": [
|
|
1252
|
+
{
|
|
1253
|
+
"guard": "0x5792...5d2c",
|
|
1254
|
+
"submission": [
|
|
1255
|
+
{
|
|
1256
|
+
"identifier": 0,
|
|
1257
|
+
"b_submission": true,
|
|
1258
|
+
"value_type": "Address",
|
|
1259
|
+
"value": "0xa6db...3d5",
|
|
1260
|
+
"name": "order_address"
|
|
1261
|
+
}
|
|
1262
|
+
]
|
|
1263
|
+
}
|
|
1264
|
+
]
|
|
1265
|
+
},
|
|
1266
|
+
"env": {
|
|
1267
|
+
"account": "myshop_customer",
|
|
1268
|
+
"network": "testnet",
|
|
1269
|
+
"no_cache": true
|
|
1270
|
+
}
|
|
1271
|
+
}
|
|
1272
|
+
```
|
|
1273
|
+
|
|
1274
|
+
> **Note**: Replace the Guard address `0x5792...5d2c` and Order address `0xa6db...3d5` with your actual object addresses.
|
|
1275
|
+
|
|
1146
1276
|
---
|
|
1147
1277
|
|
|
1148
1278
|
## Alternative Flow: Dispute and Arbitration
|
|
1149
1279
|
|
|
1150
|
-
|
|
1280
|
+
This flow handles order disputes through a formal arbitration process. The arbitration state machine has these statuses:
|
|
1281
|
+
- 0: Principal_confirming (initial)
|
|
1282
|
+
- 1: Arbitrator_confirming (after dispute submitted)
|
|
1283
|
+
- 2: Voting (after materials confirmed)
|
|
1284
|
+
- 3: Arbitrated (after arbitration result provided)
|
|
1285
|
+
- 4: Objectionable (if principal objects)
|
|
1286
|
+
- 5: Finished (after compensation claimed)
|
|
1287
|
+
- 6: Withdrawn (30 days after arbitrated)
|
|
1288
|
+
|
|
1289
|
+
### Step 1: Service Compensation Fund Setup
|
|
1290
|
+
|
|
1291
|
+
The Service must have a compensation fund balance ≥ the arbitration indemnity amount. The merchant pre-funds this before any disputes.
|
|
1292
|
+
|
|
1293
|
+
**Prompt**: Merchant adds 3 WOW to the Service compensation fund.
|
|
1294
|
+
|
|
1295
|
+
```json
|
|
1296
|
+
{
|
|
1297
|
+
"operation_type": "service",
|
|
1298
|
+
"data": {
|
|
1299
|
+
"object": "myshop_service_v2",
|
|
1300
|
+
"compensation_fund_add": {"balance": 3000000000}
|
|
1301
|
+
},
|
|
1302
|
+
"env": {
|
|
1303
|
+
"account": "myshop_merchant",
|
|
1304
|
+
"network": "testnet"
|
|
1305
|
+
}
|
|
1306
|
+
}
|
|
1307
|
+
```
|
|
1308
|
+
|
|
1309
|
+
### Step 2: Create Arbitration Object
|
|
1151
1310
|
|
|
1152
|
-
|
|
1311
|
+
Create an Arbitration object for handling order disputes.
|
|
1153
1312
|
|
|
1154
1313
|
**Prompt**: Create an Arbitration object named "myshop_arbitration_v2" with permission "myshop_permission_v2" for dispute resolution.
|
|
1155
1314
|
|
|
@@ -1175,22 +1334,155 @@ First, create an Arbitration object for handling order disputes.
|
|
|
1175
1334
|
}
|
|
1176
1335
|
```
|
|
1177
1336
|
|
|
1178
|
-
|
|
1337
|
+
> **Note**: New Arbitration objects are created with `bPaused: true` by default. You must unpause it in the next step before submitting disputes.
|
|
1338
|
+
|
|
1339
|
+
### Step 3: Unpause the Arbitration Object
|
|
1340
|
+
|
|
1341
|
+
The merchant unpauses the Arbitration object to enable dispute submissions.
|
|
1342
|
+
|
|
1343
|
+
**Prompt**: Merchant unpauses the Arbitration object "myshop_arbitration_v2".
|
|
1344
|
+
|
|
1345
|
+
```json
|
|
1346
|
+
{
|
|
1347
|
+
"operation_type": "arbitration",
|
|
1348
|
+
"data": {
|
|
1349
|
+
"object": "myshop_arbitration_v2",
|
|
1350
|
+
"pause": false
|
|
1351
|
+
},
|
|
1352
|
+
"env": {
|
|
1353
|
+
"account": "myshop_merchant",
|
|
1354
|
+
"network": "testnet"
|
|
1355
|
+
}
|
|
1356
|
+
}
|
|
1357
|
+
```
|
|
1358
|
+
|
|
1359
|
+
### Step 4: Create a Dispute Order
|
|
1360
|
+
|
|
1361
|
+
Create a new order for testing the arbitration flow (if you don't have one already).
|
|
1362
|
+
|
|
1363
|
+
**Prompt**: Customer "myshop_customer" creates a new order for "Tree House Building Set" for arbitration testing.
|
|
1364
|
+
|
|
1365
|
+
```json
|
|
1366
|
+
{
|
|
1367
|
+
"operation_type": "service",
|
|
1368
|
+
"data": {
|
|
1369
|
+
"object": "myshop_service_v2",
|
|
1370
|
+
"order_new": {
|
|
1371
|
+
"buy": {
|
|
1372
|
+
"items": [
|
|
1373
|
+
{
|
|
1374
|
+
"name": "Tree House Building Set",
|
|
1375
|
+
"stock": 1
|
|
1376
|
+
}
|
|
1377
|
+
],
|
|
1378
|
+
"total_pay": {"balance": 2000000000}
|
|
1379
|
+
},
|
|
1380
|
+
"namedNewOrder": {"name": "myshop_arb_order", "replaceExistName": true},
|
|
1381
|
+
"namedNewProgress": {"name": "myshop_arb_progress", "replaceExistName": true},
|
|
1382
|
+
"namedNewAllocation": {"name": "myshop_arb_allocation", "replaceExistName": true}
|
|
1383
|
+
}
|
|
1384
|
+
},
|
|
1385
|
+
"env": {
|
|
1386
|
+
"account": "myshop_customer",
|
|
1387
|
+
"network": "testnet"
|
|
1388
|
+
}
|
|
1389
|
+
}
|
|
1390
|
+
```
|
|
1391
|
+
|
|
1392
|
+
> **Note**: The WIP hash is auto-computed by the SDK from the Service's WIP URL configuration.
|
|
1393
|
+
|
|
1394
|
+
### Step 5: Customer Submits Dispute
|
|
1395
|
+
|
|
1396
|
+
The customer submits a dispute against the order, creating an Arb object.
|
|
1397
|
+
|
|
1398
|
+
**Prompt**: Customer "myshop_customer" submits a dispute for order "myshop_arb_order" using arbitration "myshop_arbitration_v2".
|
|
1399
|
+
|
|
1400
|
+
```json
|
|
1401
|
+
{
|
|
1402
|
+
"operation_type": "arbitration",
|
|
1403
|
+
"data": {
|
|
1404
|
+
"object": "myshop_arbitration_v2",
|
|
1405
|
+
"dispute": {
|
|
1406
|
+
"order": "myshop_arb_order",
|
|
1407
|
+
"description": "Product quality issue - the tree house set arrived damaged",
|
|
1408
|
+
"proposition": ["Full refund to customer", "Partial refund 50%", "Replace with new product"],
|
|
1409
|
+
"fee": {"balance": 100000000},
|
|
1410
|
+
"namedArb": {"name": "myshop_arb_case", "replaceExistName": true}
|
|
1411
|
+
}
|
|
1412
|
+
},
|
|
1413
|
+
"env": {
|
|
1414
|
+
"account": "myshop_customer",
|
|
1415
|
+
"network": "testnet"
|
|
1416
|
+
}
|
|
1417
|
+
}
|
|
1418
|
+
```
|
|
1419
|
+
|
|
1420
|
+
> **Note**: The dispute fee (100000000 = 0.1 WOW) must be ≥ the Arbitration object's fee setting. The Arb object is created with status=1 (Arbitrator_confirming).
|
|
1421
|
+
|
|
1422
|
+
### Step 6: Merchant Confirms Materials
|
|
1423
|
+
|
|
1424
|
+
The merchant confirms the dispute materials are valid and sets the voting deadline.
|
|
1425
|
+
|
|
1426
|
+
**Prompt**: Merchant "myshop_merchant" confirms the dispute materials for Arb "myshop_arb_case" with no voting deadline (0 = no deadline).
|
|
1427
|
+
|
|
1428
|
+
```json
|
|
1429
|
+
{
|
|
1430
|
+
"operation_type": "arbitration",
|
|
1431
|
+
"data": {
|
|
1432
|
+
"object": "myshop_arbitration_v2",
|
|
1433
|
+
"confirm": {
|
|
1434
|
+
"arb": "myshop_arb_case",
|
|
1435
|
+
"voting_deadline": 0
|
|
1436
|
+
}
|
|
1437
|
+
},
|
|
1438
|
+
"env": {
|
|
1439
|
+
"account": "myshop_merchant",
|
|
1440
|
+
"network": "testnet"
|
|
1441
|
+
}
|
|
1442
|
+
}
|
|
1443
|
+
```
|
|
1444
|
+
|
|
1445
|
+
> **Note**: Use `0` for `voting_deadline` to indicate no deadline (immediate arbitration). The MCP tool does not accept `null` for this field. To set a specific deadline, use a Unix timestamp in milliseconds.
|
|
1446
|
+
|
|
1447
|
+
### Step 7: Merchant Provides Arbitration Result
|
|
1448
|
+
|
|
1449
|
+
The merchant provides the final arbitration result with feedback and indemnity amount.
|
|
1450
|
+
|
|
1451
|
+
**Prompt**: Merchant "myshop_merchant" provides arbitration result for Arb "myshop_arb_case" with 2 WOW indemnity.
|
|
1452
|
+
|
|
1453
|
+
```json
|
|
1454
|
+
{
|
|
1455
|
+
"operation_type": "arbitration",
|
|
1456
|
+
"data": {
|
|
1457
|
+
"object": "myshop_arbitration_v2",
|
|
1458
|
+
"arbitration": {
|
|
1459
|
+
"arb": "myshop_arb_case",
|
|
1460
|
+
"feedback": "After investigation, the product quality issue is confirmed. Full refund to customer and return shipping cost covered by merchant.",
|
|
1461
|
+
"indemnity": 2000000000
|
|
1462
|
+
}
|
|
1463
|
+
},
|
|
1464
|
+
"env": {
|
|
1465
|
+
"account": "myshop_merchant",
|
|
1466
|
+
"network": "testnet"
|
|
1467
|
+
}
|
|
1468
|
+
}
|
|
1469
|
+
```
|
|
1470
|
+
|
|
1471
|
+
> **Note**: The Arb status changes to 3 (Arbitrated). The indemnity amount must be ≤ the Service's compensation_fund balance.
|
|
1472
|
+
|
|
1473
|
+
### Step 8: Customer Claims Compensation
|
|
1179
1474
|
|
|
1180
|
-
|
|
1475
|
+
The customer claims the compensation from the Service's compensation fund.
|
|
1181
1476
|
|
|
1182
|
-
**Prompt**: Customer "myshop_customer"
|
|
1477
|
+
**Prompt**: Customer "myshop_customer" claims compensation for order "myshop_arb_order" from Arb "myshop_arb_case".
|
|
1183
1478
|
|
|
1184
1479
|
```json
|
|
1185
1480
|
{
|
|
1186
1481
|
"operation_type": "order",
|
|
1187
1482
|
"data": {
|
|
1188
|
-
"object": "
|
|
1189
|
-
"
|
|
1190
|
-
"arb": "
|
|
1191
|
-
"confirm": true,
|
|
1192
|
-
"description": "Product not as described - requesting refund",
|
|
1193
|
-
"proposition": ["Full refund", "Return shipping cost coverage"]
|
|
1483
|
+
"object": "myshop_arb_order",
|
|
1484
|
+
"arb_claim_compensation": {
|
|
1485
|
+
"arb": "myshop_arb_case"
|
|
1194
1486
|
}
|
|
1195
1487
|
},
|
|
1196
1488
|
"env": {
|
|
@@ -1200,19 +1492,25 @@ If there's a dispute, customer can submit arbitration.
|
|
|
1200
1492
|
}
|
|
1201
1493
|
```
|
|
1202
1494
|
|
|
1203
|
-
|
|
1495
|
+
> **Note**: The customer receives the indemnity amount (2 WOW) from the Service's compensation fund. The Arb status changes to 5 (Finished). The Order's `claimed_by` field is updated with the Arb address.
|
|
1496
|
+
|
|
1497
|
+
### Step 9: Query Arbitration Status
|
|
1204
1498
|
|
|
1205
|
-
Check the status of the arbitration.
|
|
1499
|
+
Check the final status of the arbitration.
|
|
1206
1500
|
|
|
1207
|
-
**Prompt**: Query the
|
|
1501
|
+
**Prompt**: Query the Arb "myshop_arb_case" to verify the arbitration is finished.
|
|
1208
1502
|
|
|
1209
1503
|
```json
|
|
1210
1504
|
{
|
|
1211
1505
|
"query_type": "onchain_objects",
|
|
1212
|
-
"objects": ["
|
|
1506
|
+
"objects": ["myshop_arb_case"],
|
|
1507
|
+
"no_cache": true,
|
|
1508
|
+
"network": "testnet"
|
|
1213
1509
|
}
|
|
1214
1510
|
```
|
|
1215
1511
|
|
|
1512
|
+
The Arb should have `status: 5` (Finished) with `compensation_time` set.
|
|
1513
|
+
|
|
1216
1514
|
---
|
|
1217
1515
|
|
|
1218
1516
|
## Summary
|
|
@@ -1222,15 +1520,14 @@ This MyShop e-commerce example demonstrates:
|
|
|
1222
1520
|
1. **Merchant Setup**:
|
|
1223
1521
|
- Permission management for access control
|
|
1224
1522
|
- Machine workflow for order processing with visual flow diagram
|
|
1225
|
-
- Contact objects for
|
|
1523
|
+
- Contact objects for after-sales support
|
|
1524
|
+
- Guard creation for fund allocation validation
|
|
1226
1525
|
- Service creation with products and pricing
|
|
1227
|
-
- Arbitration setup for dispute resolution
|
|
1228
|
-
- Discount coupon creation for promotions
|
|
1229
1526
|
|
|
1230
1527
|
2. **Customer Flow**:
|
|
1231
1528
|
- Product browsing and selection
|
|
1232
1529
|
- Order creation with payment
|
|
1233
|
-
-
|
|
1530
|
+
- Private information exchange via Messenger (shipping address, phone number)
|
|
1234
1531
|
- Progress tracking through workflow nodes
|
|
1235
1532
|
- Order completion and payment release
|
|
1236
1533
|
|
|
@@ -1238,90 +1535,68 @@ This MyShop e-commerce example demonstrates:
|
|
|
1238
1535
|
- End-to-end encrypted messaging for sensitive information
|
|
1239
1536
|
- Contact-based identity verification
|
|
1240
1537
|
- No private data stored on-chain
|
|
1241
|
-
- WTS support for verifiable conversation records
|
|
1242
1538
|
|
|
1243
1539
|
4. **Alternative Flows**:
|
|
1244
|
-
- Order cancellation
|
|
1245
|
-
-
|
|
1540
|
+
- Order cancellation after confirmation (from "Order Confirmation" state)
|
|
1541
|
+
- Customer refund after cancellation (via Guard-protected Allocation)
|
|
1542
|
+
- Dispute submission and arbitration process (7-step state machine)
|
|
1543
|
+
- Compensation claim from Service compensation fund
|
|
1246
1544
|
|
|
1247
|
-
All operations use the
|
|
1545
|
+
All operations use the WoWok SDK patterns with JSON-based tool calls, making it easy for AI agents to interact with the blockchain e-commerce system.
|
|
1248
1546
|
|
|
1249
1547
|
---
|
|
1250
1548
|
|
|
1251
|
-
##
|
|
1252
|
-
|
|
1253
|
-
When advancing order workflows, it's crucial to use the correct operation type based on who is performing the action:
|
|
1254
|
-
|
|
1255
|
-
### Order Owner (Merchant)
|
|
1256
|
-
|
|
1257
|
-
The order owner can use `operation_type: "order"` with the `progress` field:
|
|
1258
|
-
|
|
1259
|
-
```json
|
|
1260
|
-
{
|
|
1261
|
-
"operation_type": "order",
|
|
1262
|
-
"data": {
|
|
1263
|
-
"object": "0x5678...9abc",
|
|
1264
|
-
"progress": {
|
|
1265
|
-
"operation": {
|
|
1266
|
-
"next_node_name": "Shipping",
|
|
1267
|
-
"forward": "Confirm Order"
|
|
1268
|
-
},
|
|
1269
|
-
"hold": false,
|
|
1270
|
-
"message": "Order confirmed"
|
|
1271
|
-
}
|
|
1272
|
-
}
|
|
1273
|
-
}
|
|
1274
|
-
```
|
|
1275
|
-
|
|
1276
|
-
### Non-Owner (Customer, Agents)
|
|
1549
|
+
## Workflow Advancement Notes
|
|
1277
1550
|
|
|
1278
|
-
|
|
1551
|
+
When advancing order workflows, use `operation_type: "progress"` with the `operate` field for all workflow transitions:
|
|
1279
1552
|
|
|
1280
1553
|
```json
|
|
1281
1554
|
{
|
|
1282
1555
|
"operation_type": "progress",
|
|
1283
1556
|
"data": {
|
|
1284
|
-
"object": "
|
|
1557
|
+
"object": "myshop_test_progress",
|
|
1285
1558
|
"operate": {
|
|
1286
1559
|
"operation": {
|
|
1287
|
-
"next_node_name": "
|
|
1288
|
-
"forward": "
|
|
1560
|
+
"next_node_name": "Target Node Name",
|
|
1561
|
+
"forward": "Forward Name"
|
|
1289
1562
|
},
|
|
1290
1563
|
"hold": false,
|
|
1291
|
-
"message": "
|
|
1564
|
+
"message": "Operation description"
|
|
1292
1565
|
}
|
|
1566
|
+
},
|
|
1567
|
+
"env": {
|
|
1568
|
+
"account": "operator_account",
|
|
1569
|
+
"network": "testnet"
|
|
1293
1570
|
}
|
|
1294
1571
|
}
|
|
1295
1572
|
```
|
|
1296
1573
|
|
|
1297
|
-
> **Key Difference**:
|
|
1298
|
-
> - `order` operation: Uses `progress` field, only for order owners
|
|
1299
|
-
> - `progress` operation: Uses `operate` field, for anyone with permission to advance the workflow
|
|
1300
|
-
|
|
1301
1574
|
The Progress object ID can be obtained from:
|
|
1302
1575
|
- Order object's `progress` field
|
|
1303
1576
|
- Named during order creation with `namedNewProgress`
|
|
1304
1577
|
|
|
1578
|
+
The operator account depends on the forward definition:
|
|
1579
|
+
- Forwards with `permissionIndex` require the merchant account (with appropriate permission)
|
|
1580
|
+
- Forwards with `namedOperator: ""` allow the order owner (customer) to operate
|
|
1581
|
+
|
|
1305
1582
|
---
|
|
1306
1583
|
|
|
1307
1584
|
## Object Reference Summary
|
|
1308
1585
|
|
|
1309
|
-
| Object Type | Name |
|
|
1310
|
-
|
|
1311
|
-
| Account | myshop_merchant |
|
|
1312
|
-
| Account | myshop_customer |
|
|
1313
|
-
| Permission | myshop_permission_v2 |
|
|
1314
|
-
| Guard | myshop_withdraw_guard_v2 |
|
|
1315
|
-
| Guard | myshop_refund_guard_v2 |
|
|
1316
|
-
| Machine | myshop_machine_v2 |
|
|
1317
|
-
| Contact | myshop_aftersales_contact_v2 |
|
|
1318
|
-
| Service | myshop_service_v2 |
|
|
1319
|
-
| Arbitration | myshop_arbitration_v2 |
|
|
1320
|
-
|
|
|
1321
|
-
|
|
|
1322
|
-
|
|
|
1323
|
-
| Allocation | (dynamic) | 0x248f...69de | Order fund allocation |
|
|
1324
|
-
| Arb | (dynamic) | (dynamic) | Arbitration case |
|
|
1586
|
+
| Object Type | Name | Purpose |
|
|
1587
|
+
|-------------|------|---------|
|
|
1588
|
+
| Account | myshop_merchant | Store owner account |
|
|
1589
|
+
| Account | myshop_customer | Customer account |
|
|
1590
|
+
| Permission | myshop_permission_v2 | Access control management |
|
|
1591
|
+
| Guard | myshop_withdraw_guard_v2 | Merchant withdrawal validation (order completed) |
|
|
1592
|
+
| Guard | myshop_refund_guard_v2 | Customer refund validation (order cancelled) |
|
|
1593
|
+
| Machine | myshop_machine_v2 | Order processing workflow |
|
|
1594
|
+
| Contact | myshop_aftersales_contact_v2 | After-sales support contact |
|
|
1595
|
+
| Service | myshop_service_v2 | Online store with products |
|
|
1596
|
+
| Arbitration | myshop_arbitration_v2 | Dispute resolution (optional) |
|
|
1597
|
+
| Order | myshop_test_order | Customer purchase order (dynamic) |
|
|
1598
|
+
| Progress | myshop_test_progress | Order workflow progress (dynamic) |
|
|
1599
|
+
| Allocation | myshop_test_allocation | Order fund allocation (dynamic) |
|
|
1325
1600
|
|
|
1326
1601
|
---
|
|
1327
1602
|
|
|
@@ -1330,7 +1605,6 @@ The Progress object ID can be obtained from:
|
|
|
1330
1605
|
- Extend the workflow with more nodes (e.g., "Return Goods", "Refund Processing")
|
|
1331
1606
|
- Add more complex Guards for conditional transitions
|
|
1332
1607
|
- Implement WIP files for product verification
|
|
1333
|
-
- Create multiple discount campaigns
|
|
1334
1608
|
- Set up Repository for order data storage
|
|
1335
1609
|
- Add WTS generation for messenger conversation records
|
|
1336
1610
|
- Implement file sharing via Messenger (shipping labels, invoices)
|
|
@@ -1345,9 +1619,3 @@ The Progress object ID can be obtained from:
|
|
|
1345
1619
|
- Use the full 64-character address in actual operations
|
|
1346
1620
|
- Test on testnet before deploying to mainnet
|
|
1347
1621
|
- Ensure sufficient WOW tokens for transaction fees
|
|
1348
|
-
|
|
1349
|
-
---
|
|
1350
|
-
|
|
1351
|
-
## Actual Test Results
|
|
1352
|
-
|
|
1353
|
-
For actual execution results with real object addresses and transaction outputs from testnet, see [MyShop_TestResults.md](MyShop_TestResults.md).
|