@wowok/skills 1.1.9 → 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.
@@ -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
- │ │ • Discount (Coupons) │ │ • Order Complete │ │
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
- └───────────────────►│ Order End │◄───────────────────────┘
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 → Order End
82
- **Alternative**: Order Confirmation → Cancel Order Order End (if cancelled)
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.1: Machine Workflow Design
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
- │ │ │ Order End │ │ │
250
- │ │ │ (Final State) │ │
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), Cancel Order (Customer) |
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 Completed nodes.
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": "Cancel Order",
310
- "namedOperator": "",
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 5.1: Create Contact Object for Customer Service
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
- #### 5.1.1 Enable Merchant Messenger
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
- #### 5.1.2 Create After-Sales Contact Object
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 6: Create Allocation Guards
475
+ ### Step 7: Create Guards for Fund Allocation
448
476
 
449
- Before creating the Service, you need Guards for order fund allocation. These Guards validate when funds can be withdrawn by the merchant or refunded to customers.
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
- #### 6.1 Create Merchant Withdraw Guard
479
+ #### 7.1 Create Withdraw Guard (Merchant Withdrawal)
452
480
 
453
- This Guard checks if the order has reached "Completed" status before allowing the merchant to withdraw funds.
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 in "Completed" status.
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": ["ecommerce", "withdraw", "merchant"]
491
+ "tags": ["order", "completed", "withdraw"],
492
+ "onChain": false,
493
+ "replaceExistName": true
464
494
  },
465
- "description": "Verify order is completed before merchant can withdraw funds. Submit order object ID.",
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": "order_id"
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": "node",
483
- "node": {
484
- "type": "logic_equal",
485
- "nodes": [
486
- {
487
- "type": "query",
488
- "query": 1253,
489
- "object": {
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
- "type": "identifier",
497
- "identifier": 1
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
- **How it works:**
511
- - Uses `convert_witness: 100` (TypeOrderProgress) to access the order's Progress object
512
- - Query ID `1253` (`progress.current`) retrieves the current node name
513
- - Compares with "Completed" to verify order status
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
- #### 6.2 Create Customer Refund Guard
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
- For scenarios where customers need refunds before order completion.
546
+ #### 7.2 Create Refund Guard (Customer Refund)
518
547
 
519
- **Prompt**: Create a Guard named "myshop_refund_guard_v2" for customer refund scenarios.
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": ["ecommerce", "refund", "customer"]
558
+ "tags": ["order", "cancelled", "refund"],
559
+ "onChain": false,
560
+ "replaceExistName": true
528
561
  },
529
- "description": "Allow refund for orders not yet shipped. Submit order object ID.",
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": "order_id"
568
+ "name": "order_address"
536
569
  },
537
570
  {
538
571
  "identifier": 1,
539
572
  "b_submission": false,
540
573
  "value_type": "String",
541
- "value": "Order Confirmation",
542
- "name": "confirmation_node"
574
+ "value": "Cancelled",
575
+ "name": "cancelled_node"
543
576
  }
544
577
  ],
545
578
  "root": {
546
- "type": "node",
547
- "node": {
548
- "type": "logic_equal",
549
- "nodes": [
550
- {
551
- "type": "query",
552
- "query": 1253,
553
- "object": {
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
- "type": "identifier",
561
- "identifier": 1
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 7: Create Service (Store)
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, you need to provide a complete configuration including machine, order_allocators with Guards, and products. The Service will be created and published in a single transaction.
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
- #### 7.1 Understanding Order Allocators
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": { "address": "..." } }` - Specific address
625
+ - `{ "Entity": { "name_or_address": "..." } }` - Specific address or account name
595
626
  - `{ "GuardIdentifier": 0 }` - Address from Guard table
596
627
 
597
- #### 7.2 Create and Publish Service
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
- ⚠️ **Important Notes:**
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 8: Create Discount Coupons (Optional)
721
+ ### Step 9: Update Product Pricing (Optional)
688
722
 
689
- Create discount coupons for promotional campaigns.
723
+ To offer promotional pricing, update product prices using the `sales` operation with `op: "set"`:
690
724
 
691
- **Prompt**: Create a 20% discount coupon named "HOLIDAY20" for holiday promotions, valid for 30 days, distributed to customers "alice" and "bob".
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
- "discount": {
699
- "name": "HOLIDAY20",
700
- "discount_type": 0,
701
- "discount_value": 2000,
702
- "benchmark": 0,
703
- "time_ms_start": 0,
704
- "time_ms_end": 2592000000,
705
- "count": 100,
706
- "recipient": ["alice", "bob"],
707
- "transferable": true
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 needs to send their shipping address and contact information to the after-sales support team. This is done securely through the Messenger system to protect privacy - the information is never stored on-chain.
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 │ myshop_aftersales│ │
813
- │ │ (Customer) │ (Never on-chain) │ (After-Sales) │ │
814
- │ │ │ │ Support Team │ │
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
- End-to-end encryption - Only customer and support can read │
837
- No on-chain storage - Message content never touches blockchain │
838
- Verifiable identity - Contact object confirms who you're talking to │
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
- "name_or_account": "myshop_customer"
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 after-sales support "myshop_aftersales" via encrypted messenger.
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": "myshop_aftersales",
866
- "content": "Order Shipping Information:\n\nOrder ID: 0x5678...9abc\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."
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
- #### 2.1.3 After-Sales Support Receives and Confirms
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
- **Prompt**: After-sales support "myshop_aftersales" views the message and sends confirmation to customer.
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": "myshop_aftersales",
928
+ "from": "myshop_merchant",
878
929
  "to": "myshop_customer",
879
- "content": "Dear Customer,\n\nWe have received your shipping information:\n Order ID: 0x5678...9abc 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!"
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 after-sales support to confirm both messages were delivered.
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": "myshop_aftersales",
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 "0x5678...9abc" to check its current status and progress.
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": ["0x5678...9abc"]
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 "0x1234...5678" to see the current workflow node.
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": ["0x1234...5678"]
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" to "Shipping".
984
+ Merchant advances the order from initial state to "Order Confirmation" node.
931
985
 
932
- > **Note**: The merchant (order owner) can use `operation_type: "order"` with `progress` to advance the workflow. Non-owners must use `operation_type: "progress"` with `operate`.
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 "0x5678...9abc" progress from "Order Confirmation" to "Shipping" using the "Confirm Order" forward.
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": "order",
992
+ "operation_type": "progress",
939
993
  "data": {
940
- "object": "0x5678...9abc",
941
- "progress": {
994
+ "object": "myshop_test_progress",
995
+ "operate": {
942
996
  "operation": {
943
- "next_node_name": "Shipping",
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 to "In Transit".
1015
+ Merchant ships the order and advances from "Order Confirmation" to "Shipping".
961
1016
 
962
- **Prompt**: Advance the order "0x5678...9abc" progress from "Shipping" to "In Transit" using the "Ship Goods" forward.
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": "order",
1021
+ "operation_type": "progress",
967
1022
  "data": {
968
- "object": "0x5678...9abc",
969
- "progress": {
1023
+ "object": "myshop_test_progress",
1024
+ "operate": {
970
1025
  "operation": {
971
- "next_node_name": "In Transit",
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 "0x5678...9abc" progress from "In Transit" to "Completed" using the "Confirm Delivery" forward.
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": "order",
1050
+ "operation_type": "progress",
995
1051
  "data": {
996
- "object": "0x5678...9abc",
997
- "progress": {
1052
+ "object": "myshop_test_progress",
1053
+ "operate": {
998
1054
  "operation": {
999
- "next_node_name": "Completed",
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
- > **Important**: Non-order owners (like the customer in this case) must use `operation_type: "progress"` to advance the workflow. Only the order owner (merchant) can use `operation_type: "order"` with progress operations.
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": "0x1234...5678",
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**: You can get the Allocation object ID from the Order object's `allocation` field, or by naming it during order creation with `namedNewAllocation`.
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 "0xdef0...1234" by verifying the withdraw guard with order "0x5678...9abc".
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": "0x248f01d944de8f6712ec06f9b4c54f93fe4132e5323488b2d24c83d7487069de",
1063
- "alloc_by_guard": "myshop_withdraw_guard_v2"
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": "myshop_withdraw_guard_v2",
1125
+ "object": "0x5af9...1074",
1070
1126
  "impack": true
1071
1127
  }
1072
1128
  ],
1073
1129
  "submission": [
1074
1130
  {
1075
- "guard": "myshop_withdraw_guard_v2",
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": "0x497ea4f7a5bb098802c23deedd8ed7122d6b501979394ce111aa66432d2ba0ca"
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 before it's confirmed.
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
- > **Note**: Customer (non-order owner) uses `operation_type: "progress"` to cancel the order.
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": "0x1234...5678",
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
- ### Step 1: Create Arbitration Object
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
- First, create an Arbitration object for handling order disputes.
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
- ### Step 2: Customer Submits Arbitration
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
- If there's a dispute, customer can submit arbitration.
1475
+ The customer claims the compensation from the Service's compensation fund.
1181
1476
 
1182
- **Prompt**: Customer "myshop_customer" submits arbitration for order "0x5678...9abc" using arbitration "myshop_arbitration".
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": "0x5678...9abc",
1189
- "arb_confirm": {
1190
- "arb": "myshop_arbitration",
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
- ### Step 3: Query Arbitration Status
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 arbitration "0xbeef...cafe" to check its status.
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": ["0xbeef...cafe"]
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 pre-sales and after-sales support
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
- - **Private information exchange via Messenger** (shipping address, phone number)
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 before confirmation
1245
- - Dispute submission and arbitration process
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 new WoWok SDK patterns with JSON-based tool calls, making it easy for AI agents to interact with the blockchain e-commerce system.
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
- ## Important: Order vs Progress Operations
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
- Non-owners must use `operation_type: "progress"` with the `operate` field:
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": "0x1234...5678",
1557
+ "object": "myshop_test_progress",
1285
1558
  "operate": {
1286
1559
  "operation": {
1287
- "next_node_name": "Completed",
1288
- "forward": "Complete Order"
1560
+ "next_node_name": "Target Node Name",
1561
+ "forward": "Forward Name"
1289
1562
  },
1290
1563
  "hold": false,
1291
- "message": "Order completed"
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 | Example Address | Purpose |
1310
- |-------------|------|-----------------|---------|
1311
- | Account | myshop_merchant | 0x73e1...708a | Store owner account |
1312
- | Account | myshop_customer | 0x6e95...d94d | Customer account |
1313
- | Permission | myshop_permission_v2 | 0x0e01...9862 | Access control management |
1314
- | Guard | myshop_withdraw_guard_v2 | 0x7fe6...91ea | Merchant withdrawal validation (order completed) |
1315
- | Guard | myshop_refund_guard_v2 | 0x6147...bda4 | Customer refund validation (order not shipped) |
1316
- | Machine | myshop_machine_v2 | 0x923b...6aac | Order processing workflow |
1317
- | Contact | myshop_aftersales_contact_v2 | 0x855a...f53b | After-sales support contact |
1318
- | Service | myshop_service_v2 | 0xc02e...9755 | Online store with products |
1319
- | Arbitration | myshop_arbitration_v2 | (to be created) | Dispute resolution |
1320
- | Discount | HOLIDAY20 | (to be created) | Promotional coupon |
1321
- | Order | (dynamic) | 0x497e...a0ca | Customer purchase order |
1322
- | Progress | (dynamic) | 0xf7ec...472f | Order workflow progress |
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).