@wowok/agent-mcp 2.2.11 → 2.2.13

package/docs/docs/payment.md

@@ -0,0 +1,512 @@
+
+# Payment Component (💰 Direct Transfer)
+
+---
+
+## Component Overview
+
+The Payment component is used to send instant, irreversible token transfers to any wallet address. Payment is an immutable object that can only be created, not modified.
+
+---
+
+## Function List
+
+| Function Name | Purpose | Usage Scenario | Significance |
+|---------------|---------|----------------|-------------|
+| **Create Single Recipient Payment** | Send tokens to one recipient | Personal payments, simple transfers | Direct, secure one-to-one token transfers |
+| **Create Multi-Recipient Payment** | Send tokens to multiple recipients in one transaction | Team bonuses, payroll, bulk transfers | Efficiently distribute tokens to multiple addresses simultaneously |
+| **Named Payment** | Create a named Payment object for tracking | Recorded transactions, audit trails | Creates identifiable payment objects on-chain |
+| **Payment with Info** | Add payment metadata (remark, index, for_object, for_guard) | Service payments, order payments, Guard-verified payments | Provides context and verification for payments |
+
+---
+
+## Complete Tool Call Structure
+
+Payment operations use the following top-level structure:
+
+```json
+{
+  "operation_type": "payment",
+  "data": { ... },    // Payment data definition
+  "env": { ... }       // Execution environment (optional)
+}
+```
+
+---
+
+## Schema Tree
+
+```
+payment (Payment Object)
+├── operation_type: "payment" (fixed value)
+├── data (Payment data definition)
+│   ├── object (object definition, required)
+│   │   ├── name|tags|type_parameter (create new object)
+│   │   └── type_parameter (token type, e.g., 0x2::wow::WOW)
+│   ├── revenue (recipient and amount array, required)
+│   │   └── [] (each item has recipient + amount)
+│   └── info (payment information, required)
+│       ├── remark (payment remark)
+│       ├── index (payment index)
+│       ├── for_object (optional, related object)
+│       └── for_guard (optional, Guard verification)
+└── env (optional, execution environment)
+    ├── account (string, optional) - account name or address, empty string for default
+    ├── network (string, optional) - "testnet" or "localnet"
+    ├── permission_guard (array, optional) - list of permission guard IDs
+    ├── no_cache (boolean, optional) - disable caching
+    └── referrer (string, optional) - referrer ID
+```
+
+---
+
+## Sub-feature 1: Create Single Recipient Payment
+
+### Feature Description
+
+Create a Payment object to send tokens to a single recipient. Payment is an immutable object and cannot be modified after creation.
+
+### Parameter Description
+
+| Parameter Path | Type | Required | Description | Constraints |
+|----------|------|------|------|------|
+| `operation_type` | string | Yes | Operation type | Fixed value "payment" |
+| `data.object` | object | Yes | Object configuration | Must include type_parameter |
+| `data.object.type_parameter` | string | Yes | Token type | e.g., "0x2::wow::WOW" |
+| `data.object.name` | string | No | Payment name | Max 64 bcs characters |
+| `data.revenue` | array | Yes | Recipient and amount array | At least one recipient, max 200 |
+| `data.revenue[].recipient` | object | Yes | Recipient | AccountOrMark_Address with name_or_address |
+| `data.revenue[].amount` | object | Yes | Amount | CoinParam with balance field |
+| `data.revenue[].amount.balance` | string/number | Yes | Amount value | Minimum unit, no decimals or negatives |
+| `data.info` | object | Yes | Payment information | Must include remark and index |
+| `data.info.remark` | string | Yes | Payment remark | Description of the payment |
+| `data.info.index` | number/string | Yes | Payment index | Numeric identifier for this payment |
+
+### Important Notes
+
+⚠️ **Payment is an immutable object!** Can only be created, not modified.
+
+⚠️ **Transfer is irreversible!** Please confirm recipient address is correct.
+
+⚠️ **Ensure sufficient balance!**
+
+⚠️ **Maximum 200 recipients per payment!**
+
+---
+
+### Examples
+
+#### Example 1.1: Minimal Single Recipient Payment
+
+**Prompt**: Create a Payment to send 5000000000 minimum unit WOW tokens to "alice", add remark "Thanks for the help!", set index 1.
+
+```json
+{
+  "operation_type": "payment",
+  "data": {
+    "object": {
+      "type_parameter": "0x2::wow::WOW"
+    },
+    "revenue": [
+      {
+        "recipient": { "name_or_address": "alice" },
+        "amount": { "balance": "5000000000" }
+      }
+    ],
+    "info": {
+      "remark": "Thanks for the help!",
+      "index": 1
+    }
+  }
+}
+
+**Execution Result**:
+```json
+{
+  "status": "success",
+  "object": "0xc8e8...1bb4",
+  "type": "Payment",
+  "version": "30128",
+  "change": "created",
+  "objects": [
+    {
+      "type": "WReceivedObject",
+      "object": "0x1a88...9649",
+      "change": "created"
+    },
+    {
+      "type": "Payment",
+      "object": "0xc8e8...1bb4",
+      "change": "created"
+    }
+  ]
+}
+```
+
+---
+
+#### Example 1.2: Named Single Recipient Payment
+
+**Prompt**: Create a Payment named "payment_to_alice" to send to "alice", add tags "personal", "payment", use WOW token, remark "Birthday gift", index 2.
+
+```json
+{
+  "operation_type": "payment",
+  "data": {
+    "object": {
+      "name": "payment_to_alice",
+      "tags": ["personal", "payment"],
+      "type_parameter": "0x2::wow::WOW"
+    },
+    "revenue": [
+      {
+        "recipient": { "name_or_address": "alice" },
+        "amount": { "balance": "10000000000" }
+      }
+    ],
+    "info": {
+      "remark": "Birthday gift",
+      "index": 2
+    }
+  }
+}
+
+**Execution Result**:
+```json
+{
+  "status": "success",
+  "object": "0x...",
+  "type": "Payment",
+  "version": "...",
+  "change": "created"
+}
+```
+
+---
+
+## Sub-feature 2: Create Multi-Recipient Payment
+
+### Feature Description
+
+Create a Payment object to send tokens to multiple recipients in a single transaction. This is efficient for bulk transfers.
+
+---
+
+### Examples
+
+#### Example 2.1: Two Recipients Payment
+
+**Prompt**: Create a Payment to send to "alice" and "bob" simultaneously: "alice" gets 3000000000, "bob" gets 2000000000, add remark "Team bonus", index 10.
+
+```json
+{
+  "operation_type": "payment",
+  "data": {
+    "object": {
+      "type_parameter": "0x2::wow::WOW"
+    },
+    "revenue": [
+      {
+        "recipient": { "name_or_address": "alice" },
+        "amount": { "balance": "3000000000" }
+      },
+      {
+        "recipient": { "name_or_address": "bob" },
+        "amount": { "balance": "2000000000" }
+      }
+    ],
+    "info": {
+      "remark": "Team bonus",
+      "index": 10
+    }
+  }
+}
+
+**Execution Result**:
+```json
+{
+  "status": "success"
+}
+```
+
+---
+
+#### Example 2.2: Named Multi-Recipient Payment
+
+**Prompt**: Create a Payment named "q1_bonus_payment" with tags "payroll", "q1-2025", send to three team members: "charlie" gets 5000000000, "dave" gets 4000000000, "eve" gets 3500000000, remark "Q1 2025 performance bonus", index 15.
+
+```json
+{
+  "operation_type": "payment",
+  "data": {
+    "object": {
+      "name": "q1_bonus_payment",
+      "tags": ["payroll", "q1-2025"],
+      "type_parameter": "0x2::wow::WOW"
+    },
+    "revenue": [
+      {
+        "recipient": { "name_or_address": "charlie" },
+        "amount": { "balance": "5000000000" }
+      },
+      {
+        "recipient": { "name_or_address": "dave" },
+        "amount": { "balance": "4000000000" }
+      },
+      {
+        "recipient": { "name_or_address": "eve" },
+        "amount": { "balance": "3500000000" }
+      }
+    ],
+    "info": {
+      "remark": "Q1 2025 performance bonus",
+      "index": 15
+    }
+  }
+}
+
+**Execution Result**:
+```json
+{
+  "status": "success"
+}
+```
+
+---
+
+## Sub-feature 3: Payment with Additional Info
+
+### Feature Description
+
+Create a Payment with additional metadata, such as linking to a specific object or Guard for verification purposes.
+
+---
+
+### Examples
+
+#### Example 3.1: Payment Linked to Object
+
+**Prompt**: Create a Payment linked to "my_service_order", send 8000000000 to "service_provider", remark "Service order payment", index 100, set for_object to "my_service_order".
+
+```json
+{
+  "operation_type": "payment",
+  "data": {
+    "object": {
+      "type_parameter": "0x2::wow::WOW"
+    },
+    "revenue": [
+      {
+        "recipient": { "name_or_address": "service_provider" },
+        "amount": { "balance": "8000000000" }
+      }
+    ],
+    "info": {
+      "remark": "Service order payment",
+      "index": 100,
+      "for_object": "my_service_order"
+    }
+  }
+}
+
+**Execution Result**:
+```json
+{
+  "status": "success"
+}
+```
+
+**Note**: The `for_object` parameter accepts any WoWok protocol object (such as Permission, Repository, Service, Demand, Order, etc.). The referenced object must be a WoWok object type (type must start with the WoWok package address).
+
+**To use this feature**:
+1. Create a WoWok object (e.g., Permission, Repository, Service, Demand) first
+2. Use that object's ID/name as `for_object`
+3. The Payment will be linked to that object for tracking purposes
+
+---
+
+#### Example 3.2: Payment with Guard Verification
+
+**Prompt**: Create a Payment that requires Guard verification: send 25000000000 to "merchant", remark "Purchase payment", index 200, set for_guard to "purchase_guard".
+
+```json
+{
+  "operation_type": "payment",
+  "data": {
+    "object": {
+      "name": "purchase_payment",
+      "type_parameter": "0x2::wow::WOW"
+    },
+    "revenue": [
+      {
+        "recipient": { "name_or_address": "merchant" },
+        "amount": { "balance": "25000000000" }
+      }
+    ],
+    "info": {
+      "remark": "Purchase payment",
+      "index": 200,
+      "for_guard": "purchase_guard"
+    }
+  }
+}
+
+**Execution Result**:
+```json
+{
+  "status": "success"
+}
+```
+
+---
+
+#### Example 3.3: Full Payment with Object and Guard
+
+**Prompt**: Create a complete Payment with all fields: named "order_500_payment", tags "service", "order-500", send 15000000000 to "vendor_alice", link to "service_order_500", use "service_guard" for verification, remark "Payment for service order #500", index 500, use WOW token.
+
+```json
+{
+  "operation_type": "payment",
+  "data": {
+    "object": {
+      "name": "order_500_payment",
+      "tags": ["service", "order-500"],
+      "type_parameter": "0x2::wow::WOW"
+    },
+    "revenue": [
+      {
+        "recipient": { "name_or_address": "vendor_alice" },
+        "amount": { "balance": "15000000000" }
+      }
+    ],
+    "info": {
+      "remark": "Payment for service order #500",
+      "index": 500,
+      "for_object": "service_order_500",
+      "for_guard": "service_guard"
+    }
+  }
+}
+
+**Execution Result**:
+```json
+{
+  "status": "success"
+}
+```
+
+---
+
+## Sub-feature 4: Payment with Environment Configuration
+
+### Feature Description
+
+Create a Payment with custom environment settings, such as specifying network or account.
+
+---
+
+### Examples
+
+#### Example 4.1: Payment on Testnet
+
+**Prompt**: On testnet network, create a Payment to send to "test_recipient", 1000000000 WOW, remark "Test payment", index 1, use default account.
+
+```json
+{
+  "operation_type": "payment",
+  "data": {
+    "object": {
+      "type_parameter": "0x2::wow::WOW"
+    },
+    "revenue": [
+      {
+        "recipient": { "name_or_address": "test_recipient" },
+        "amount": { "balance": "1000000000" }
+      }
+    ],
+    "info": {
+      "remark": "Test payment",
+      "index": 1
+    }
+  },
+  "env": {
+    "network": "testnet"
+  }
+}
+
+**Execution Result**:
+```json
+{
+  "status": "success"
+}
+```
+
+---
+
+#### Example 4.2: Payment with Specific Account
+
+**Prompt**: Use account "payment_manager" to create a Payment to send 6000000000 to "recipient_bob", remark "Project milestone payment", index 88.
+
+```json
+{
+  "operation_type": "payment",
+  "data": {
+    "object": {
+      "type_parameter": "0x2::wow::WOW"
+    },
+    "revenue": [
+      {
+        "recipient": { "name_or_address": "recipient_bob" },
+        "amount": { "balance": "6000000000" }
+      }
+    ],
+    "info": {
+      "remark": "Project milestone payment",
+      "index": 88
+    }
+  },
+  "env": {
+    "account": "payment_manager"
+  }
+}
+
+**Execution Result**:
+```json
+{
+  "status": "success"
+}
+```
+
+---
+
+## Important Notes
+
+⚠️ **Payment is an immutable object!** Can only be created, not modified.
+
+⚠️ **Transfer is irreversible!** Please confirm recipient address is correct.
+
+⚠️ **Ensure sufficient balance!**
+
+⚠️ **Maximum 200 recipients per payment!**
+
+⚠️ **type_parameter is required!** Specify token type inside object.
+
+⚠️ **All amount values must be positive integers!** No decimals or negative values.
+
+⚠️ **info.remark and info.index are required!** Must provide both for every payment.
+
+⚠️ **Use names instead of addresses in prompts for better readability.**
+
+---
+
+## Related Components
+
+| Component | Description |
+|-----------|-------------|
+| **[Treasury](treasury.md)** | Team fund management |
+| **[Reward](reward.md)** | Marketing incentives |
+| **[Allocation](allocation.md)** | Automatic fund distribution |
+| **[Service](service.md)** | WYSIWYG product trading |
+| **[Order](order.md)** | Order management |
+| **[Guard](guard.md)** | Trust verification engine |
+