@wowok/agent-mcp 2.2.11 → 2.2.13

package/docs/docs/contact.md

@@ -0,0 +1,709 @@
+# Contact Component (💬 Communication Hub)
+
+---
+
+## Component Overview
+
+The Contact component is used to manage on-chain instant messaging contact profiles, serving as the core for secure IM address management.
+
+**Key Role in Secure Communication:**
+
+The Contact component is the **foundation of end-to-end encrypted messaging** in the WoWok protocol. It serves as the bridge between on-chain identity and off-chain secure communication through the [Messenger](messenger.md) system.
+
+**How Contact Enables Secure Messaging:**
+
+1. **On-Chain Identity**: Contact objects are published on-chain, providing a verifiable public identity that anyone can look up
+2. **Messenger Integration**: Each Contact object can be linked to a Messenger account, enabling encrypted communication
+3. **Privacy Protection**: While the Contact identity is public, all actual communication is **end-to-end encrypted** and **never stored on-chain**
+4. **Service Communication**: In [Service](service.md) transactions, Contact objects enable customers and service providers to exchange sensitive information (shipping addresses, phone numbers, etc.) securely without exposing this data on the blockchain
+
+**Typical Usage Flow:**
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  Create Contact │────▶│  Enable Messenger │────▶│  Secure Chat   │
+│   (On-chain)    │     │  (Encrypted IM)   │     │  (E2E Encrypted)│
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+         │                                               │
+         │                                               │
+         ▼                                               ▼
+┌─────────────────┐                          ┌─────────────────┐
+│ Share Contact   │                          │  Exchange Info  │
+│ with Others     │                          │  (Private)      │
+└─────────────────┘                          └─────────────────┘
+```
+
+**Important Links:**
+- **[Messenger](messenger.md)** - End-to-end encrypted messaging system
+- **[Service](service.md)** - Uses Contact for secure customer-service provider communication
+- **[Order](order.md)** - Uses Contact via `required_info` field for private information exchange
+
+---
+
+## Why Contact is Essential
+
+| Scenario | Without Contact | With Contact |
+|----------|----------------|--------------|
+| **Service Purchase** | No way to send shipping address privately | Customer sends encrypted address via Messenger linked to Contact |
+| **Dispute Resolution** | No verifiable communication history | WTS (Witness Timestamped Snapshot) provides cryptographic proof of conversations |
+| **Team Collaboration** | No secure team communication channel | Team members communicate via encrypted channels linked to Contact identities |
+| **Customer Support** | Public on-chain messages expose sensitive data | Private end-to-end encrypted support conversations |
+
+**Privacy & Security Guarantees:**
+- ✅ **End-to-end encryption** - Only conversation participants can read messages
+- ✅ **No on-chain storage** - Message content is never published to the blockchain
+- ✅ **Verifiable identity** - Contact provides cryptographic proof of who you're communicating with
+- ✅ **WTS support** - Generate cryptographically verifiable conversation records for [Arbitration](arbitration.md) if needed
+
+---
+
+## Function List
+
+| Function Name | Purpose | Usage Scenario | Significance |
+|---------------|---------|----------------|-------------|
+| **Create Contact** | Set up IM contact profile | Establish team communication, service support | Creates on-chain identity for [Messenger](messenger.md) encrypted messaging |
+| **Manage IM List** | Add/remove contact entries | Update communication partners | Controls who can initiate encrypted conversations with you |
+| **Set Status** | Update availability message | Indicate online presence, response times | Improves communication efficiency |
+| **Enable Messenger** | Link Contact to encrypted messaging | Enable end-to-end encrypted chat | Foundation for secure private communication |
+| **Service Integration** | Connect Contact to Service/Order | Allow customers to send private info | Enables secure exchange of shipping addresses, phone numbers, etc. |
+
+
+---
+
+## Schema Tree (4-Level Structure)
+
+```
+Contact Component
+├── operation_type: "contact"
+├── data
+│   ├── object
+│   │   ├── Option 1: Name or Address (string)
+│   │   │   └── [contact_name or contact_id]
+│   │   └── Option 2: Named Object with Permission
+│   │       ├── name (string, optional)
+│   │       ├── tags (array of strings, optional)
+│   │       ├── onChain (boolean, optional)
+│   │       ├── replaceExistName (boolean, optional)
+│   │       └── permission
+│   │           ├── Option 1: Name or Address (string)
+│   │           │   └── [permission_name or permission_id]
+│   │           └── Option 2: Named Object with Description
+│   │               ├── name (string, optional)
+│   │               ├── tags (array of strings, optional)
+│   │               ├── onChain (boolean, optional)
+│   │               ├── replaceExistName (boolean, optional)
+│   │               └── description (string, optional)
+│   ├── my_status (string, optional)
+│   ├── description (string, optional)
+│   ├── location (string, optional)
+│   ├── ims (optional)
+│   │   ├── op: "add"
+│   │   │   └── im (array)
+│   │   │       ├── at (string)
+│   │   │       └── description (string, optional) - max 256 bcs characters
+│   │   ├── op: "set"
+│   │   │   └── im (array)
+│   │   │       ├── at (string)
+│   │   │       └── description (string, optional) - max 256 bcs characters
+│   │   ├── op: "remove"
+│   │   │   └── im (array of strings)
+│   │   ├── op: "clear"
+│   ├── owner_receive (transfer received coins or NFT objects to owner, optional)
+│   │   ├── Option 1: "recently" (string) - receive all recent objects
+│   │   ├── Option 2: Array of received objects
+│   │   │   └── [{ id: "object_id", type: "object_type" }]
+│   │   └── Option 3: Received balance object
+│   │       ├── balance (number or string)
+│   │       ├── token_type (string)
+│   │       └── received (array of received items)
+├── 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
+└── submission (optional, submission data)
+    ├── type (string) - fixed value "submission"
+    ├── guard (array) - list of guards to verify
+    │   └── [{ object: "guard_id", impack: boolean }]
+    └── submission (array) - submission data for guards
+        └── [{ guard: "guard_id", submission: [guard_submission_items] }]
+            └── guard_submission_items
+                ├── identifier (number, 0-255) - Guard table item identifier
+                ├── b_submission (boolean) - whether this item requires submission
+                ├── value_type (number | string) - value type (e.g., 6 or "U64" for U64 type)
+                ├── **value (any) - submitted value**
+                └── name (string, optional) - item name
+```
+
+---
+
+### ⚠️ Important Note About Submission
+
+If the execution returns a `submission` field in the response, it indicates that additional Guard verification data is required. You must:
+
+1. Complete all required submission data within the `submission` structure
+2. Resubmit the operation with the completed submission data
+3. **Do not modify any other parts of the structure** - only fill in the required submission values
+
+The submission structure will specify which Guard objects need verification and what data needs to be provided for each Guard table item.
+
+**Query Value Types**: Use the `wowok_buildin_info` tool with `{ "info": "value types" }` to query all supported value types with their numeric and string representations. This helps you understand what `value_type` values are valid for submission data.
+
+---
+
+## Sub-function 1: Create New Contact
+
+### Function Description
+
+Create a new Contact object for managing instant messaging contacts.
+
+### Parameter Description
+
+| Parameter | Type | Required | Description | Constraints |
+|-----------|------|----------|-------------|-------------|
+| `object.name` | string | No | Local mark name | Max 64 BCS bytes, cannot start with "0x" |
+| `object.id` | string | No | Object ID | 0x prefix + 64 hex characters |
+| `object.permission` | string/object | No | Permission object | Can be existing permission ID/name, or new permission object |
+| `description` | string | No | Contact object description or public information | Max 4000 BCS characters |
+| `location` | string | No | Physical or virtual location of the Contact | Max 256 BCS characters |
+| `ims` | object | No | IM contact operations | See description below |
+
+### Examples
+
+#### Example 1.1: Create Simple Contact
+
+**Prompt:** Create a new contact object named "service_support" with an existing permission, set description to "Customer support contact information", and location to "Online service".
+
+```json
+{
+  "operation_type": "contact",
+  "data": {
+    "object": {
+      "name": "service_support",
+      "permission": "existing_permission"
+    },
+    "description": "Customer support contact information",
+    "location": "Online service"
+  }
+}
+```
+
+**Execution Result**:
+```json
+{
+  "status": "success",
+  "object": "0xb607...190c",
+  "type": "Contact",
+  "version": "93060",
+  "change": "created"
+}
+```
+
+#### Example 1.2: Create Contact with New Permission
+
+**Prompt:** Create a new contact named "team_contact", create a new permission object named "team_permission", set description to "Team contact information", and add "alice" with description "Product Manager" to the IM list.
+
+```json
+{
+  "operation_type": "contact",
+  "data": {
+    "object": {
+      "name": "team_contact",
+      "permission": {
+        "name": "team_permission"
+      }
+    },
+    "description": "Team contact information",
+    "ims": {
+      "op": "add",
+      "im": [
+        {
+          "at": "alice",
+          "description": "Product Manager"
+        }
+      ]
+    }
+  }
+}
+```
+
+**Execution Result**:
+```json
+{
+  "status": "success",
+  "object": "0x3c06...c965",
+  "type": "Contact",
+  "version": "93537",
+  "change": "created"
+}
+```
+
+---
+
+## Sub-function 2: Manage IM Contact List (ims)
+
+### Function Description
+
+Manage the Contact object's instant messaging contact list, supporting add, set, remove, and clear operations.
+
+### Parameter Description
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ims.op` | string | Yes | Operation type: add/set/remove/clear |
+| `ims.im` | array | Required for add/set | IM contact list |
+| `ims.im[].at` | string | Yes | Contact account address or name |
+| `ims.im[].description` | string | No | Contact note or description | Max 256 BCS characters |
+
+### Constraints
+
+⚠️ **Maximum IM Contact Limit**: 200 contacts per Contact object. 
+
+### Operation Type Description
+
+| Operation Type | Description |
+|----------------|-------------|
+| `add` | Add new contacts to existing list |
+| `set` | Replace entire contact list |
+| `remove` | Remove specified contacts (use address or name) |
+| `clear` | Clear all contacts |
+
+### Important Notes
+
+⚠️ **my_status is only valid when your account is already in the IM list**.
+
+### Examples
+
+#### Example 2.1: Add Contacts
+
+**Prompt:** Use the existing contact "service_support" and add a new contact: "testuser1" with description "Technical Support".
+
+```json
+{
+  "operation_type": "contact",
+  "data": {
+    "object": "service_support",
+    "ims": {
+      "op": "add",
+      "im": [
+        {
+          "at": "testuser1",
+          "description": "Technical Support"
+        }
+      ]
+    }
+  }
+}
+```
+
+**Execution Result**:
+```json
+{
+  "status": "success",
+  "object": "0xb607...190c",
+  "type": "Contact",
+  "version": "94028",
+  "change": "mutated"
+}
+```
+
+#### Example 2.2: Set Contact List (Replace)
+
+**Prompt:** Use the existing contact "team_contact" and replace the entire IM list with "alice" (description: "Designer") and "testuser1" (description: "Developer").
+
+```json
+{
+  "operation_type": "contact",
+  "data": {
+    "object": "team_contact",
+    "ims": {
+      "op": "set",
+      "im": [
+        {
+          "at": "alice",
+          "description": "Designer"
+        },
+        {
+          "at": "testuser1",
+          "description": "Developer"
+        }
+      ]
+    }
+  }
+}
+```
+
+**Execution Result**:
+```json
+{
+  "status": "success",
+  "object": "0x3c06...c965",
+  "type": "Contact",
+  "version": "94531",
+  "change": "mutated"
+}
+```
+
+#### Example 2.3: Remove Contacts
+
+**Prompt:** Use the existing contact "service_support" and remove the contact named "testuser1" from the IM list.
+
+```json
+{
+  "operation_type": "contact",
+  "data": {
+    "object": "service_support",
+    "ims": {
+      "op": "remove",
+      "im": ["testuser1"]
+    }
+  }
+}
+```
+
+**Execution Result**:
+```json
+{
+  "status": "success",
+  "object": "0xb607...190c",
+  "type": "Contact",
+  "version": "94532",
+  "change": "mutated"
+}
+```
+
+#### Example 2.4: Clear Contacts
+
+**Prompt:** Use the existing contact "team_contact" and clear all contacts from the IM list.
+
+```json
+{
+  "operation_type": "contact",
+  "data": {
+    "object": "team_contact",
+    "ims": {
+      "op": "clear"
+    }
+  }
+}
+```
+
+**Execution Result**:
+```json
+{
+  "status": "success",
+  "object": "0x3c06...c965",
+  "type": "Contact",
+  "version": "94533",
+  "change": "mutated"
+}
+```
+
+---
+
+## Sub-function 3: Set Personal Status (my_status)
+
+### Function Description
+
+Set your status message in this contact list.
+
+### Parameter Description
+
+| Parameter | Type | Required | Description | Constraints |
+|-----------|------|----------|-------------|-------------|
+| `my_status` | string | Yes | Status message | Max 64 BCS bytes, cannot start with "0x" |
+
+### Important Notes
+
+⚠️ **Only valid when your account is already in the IM list**.
+
+### Example
+
+**Prompt:** Use the existing contact "service_support" and set your personal status to "Online, available for contact".
+
+```json
+{
+  "operation_type": "contact",
+  "data": {
+    "object": "service_support",
+    "my_status": "Online, available for contact"
+  }
+}
+```
+
+**Execution Result**:
+```json
+{
+  "status": "success",
+  "object": "0xb607...190c",
+  "type": "Contact",
+  "version": "95965",
+  "change": "mutated"
+}
+```
+
+---
+
+## Sub-function 4: Receive Objects (owner_receive)
+
+### Function Description
+
+Receive objects sent to this Contact object and unwrap them to send to the permission owner.
+
+This function allows the Contact object owner to receive objects (including CoinWrapper from Payment) that were sent to the Contact object address.
+
+### Parameter Description
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `owner_receive` | string or array | Yes | Receive configuration: "recently" to receive all recent objects, or array of received object IDs |
+
+### Important Notes
+
+⚠️ **The Contact object must have a Permission object associated with it** to use owner_receive.
+
+⚠️ **Only the Permission owner can execute owner_receive**.
+
+### Examples
+
+#### Example 4.1: Receive All Recently Received Objects
+
+**Prerequisites**: Before receiving objects, you need to send a Payment to the Contact object. Here are the steps:
+
+**Step 1**: Create a Contact object
+
+```json
+{
+  "operation_type": "contact",
+  "data": {
+    "object": {
+      "name": "contact_receive_test_v3"
+    },
+    "description": "Contact for testing owner receive functionality"
+  }
+}
+```
+
+**Step 2**: Send a Payment to the Contact object
+
+```json
+{
+  "operation_type": "payment",
+  "data": {
+    "object": {
+      "name": "payment_to_contact_v3"
+    },
+    "revenue": [
+      {
+        "recipient": {
+          "name_or_address": "contact_receive_test_v3"
+        },
+        "amount": {
+          "balance": 1000000000
+        }
+      }
+    ],
+    "info": {
+      "remark": "Test payment to contact",
+      "index": 11
+    }
+  }
+}
+```
+
+**Step 3**: Receive the objects from the Contact object
+
+**Prompt:** Use the existing contact "contact_receive_test_v3" and receive all recently sent objects.
+
+```json
+{
+  "operation_type": "contact",
+  "data": {
+    "object": "contact_receive_test_v3",
+    "owner_receive": "recently"
+  }
+}
+```
+
+**Execution Result**:
+```json
+{
+  "status": "success",
+  "object": "0xaee9...1db7",
+  "type": "Contact",
+  "version": "14541",
+  "change": "mutated"
+}
+```
+
+#### Example 4.2: Receive Specific Objects
+
+**Prompt:** Use the existing contact "contact_receive_test_v3" and receive specific objects by their IDs.
+
+```json
+{
+  "operation_type": "contact",
+  "data": {
+    "object": "contact_receive_test_v3",
+    "owner_receive": [
+      {
+        "id": "0xaee9b75f7903d05dbfb4ee2abe9e036503c66f4bc552d835543b9b49d3851db7",
+        "type": "0x2::payment::CoinWrapper<0x2::wow::WOW>"
+      }
+    ]
+  }
+}
+```
+
+**Execution Result**:
+```json
+{
+  "status": "success",
+  "object": "0xaee9...1db7",
+  "type": "Contact",
+  "version": "14542",
+  "change": "mutated"
+}
+```
+
+---
+
+## Sub-function 5: Combined Operations
+
+### Function Description
+
+Execute multiple operations in a single call.
+
+### Example
+
+#### Example 5.1: Create Contact and Add Contacts
+
+**Prompt:** Create a new contact named "customer_service" with existing permission "service_permission", set description to "Customer service team contact information", set location to "7x24 Online Support", add "alice" (Pre-sales Consulting) and "testuser1" (After-sales Support) to IM list.
+
+```json
+{
+  "operation_type": "contact",
+  "data": {
+    "object": {
+      "name": "customer_service",
+      "permission": "service_permission"
+    },
+    "description": "Customer service team contact information",
+    "location": "7x24 Online Support",
+    "ims": {
+      "op": "add",
+      "im": [
+        {
+          "at": "alice",
+          "description": "Pre-sales Consulting"
+        },
+        {
+          "at": "testuser1",
+          "description": "After-sales Support"
+        }
+      ]
+    }
+  }
+}
+```
+
+**Execution Result**:
+```json
+{
+  "status": "success",
+  "object": "0x7a22...080b",
+  "type": "Contact",
+  "version": "96881",
+  "change": "created"
+}
+```
+
+---
+
+## Contact + Messenger Integration Guide
+
+### Step 1: Create Your Contact Object
+
+Create a Contact object that will serve as your public identity for secure messaging.
+
+```json
+{
+  "operation_type": "contact",
+  "data": {
+    "object": {
+      "name": "my_contact",
+      "onChain": true
+    },
+    "description": "My secure contact for encrypted messaging"
+  }
+}
+```
+
+### Step 2: Enable Messenger for Your Account
+
+Use the [account operation](account.md) to enable Messenger for your account, linking it to your Contact object:
+
+```json
+{
+  "operation": "account_operation",
+  "account": "my_account",
+  "messenger": "my_contact"
+}
+```
+
+See [account.md](account.md) for detailed messenger configuration.
+
+### Step 3: Start Secure Conversations
+
+Once Messenger is enabled, you can send encrypted messages to any Contact object:
+
+```json
+{
+  "operation": "send_message",
+  "from": "my_account",
+  "to": "recipient_contact",
+  "content": "Hello! This message is end-to-end encrypted."
+}
+```
+
+See [Messenger Documentation](messenger.md) for full messaging capabilities.
+
+### Step 4: Use Contact in Service/Order (For Private Information Exchange)
+
+When purchasing from a Service that requires private information:
+
+**For Customers:**
+1. Attach your Contact to the order via `required_info` field (see [Order](order.md#function-2-set-required-information-required_info))
+2. Use Messenger to send shipping address, phone number, etc. to the service's Contact
+
+**For Service Providers:**
+1. Configure your Service with a Contact object (see [Service](service.md#sub-feature-7-configure-contact-um))
+2. Customers will use this Contact to send you encrypted private information
+
+---
+
+## Important Notes
+
+⚠️ **my_status is only valid when your account is already in the IM list**.
+
+⚠️ **Contact information is publicly visible on-chain**, please set carefully. Never include sensitive personal information in the Contact description or location fields.
+
+⚠️ **Messenger encryption**: While your Contact identity is public, all messages sent via Messenger are **end-to-end encrypted** and **never stored on-chain**. Only conversation participants can read the message content.
+
+⚠️ **WTS for Arbitration**: If you need to prove what was discussed in a conversation (e.g., for dispute resolution), use [Messenger's WTS feature](messenger.md#example-7-generate-wts) to create a cryptographically verifiable record.
+
+---
+
+## Related Components
+
+| Component | Description |
+|-----------|-------------|
+| **[Service](service.md)** | WYSIWYG product trading - uses Contact for secure customer communication |
+| **[Order](order.md)** | Order management - uses `required_info` field for private information exchange |
+| **[Messenger](messenger.md)** | Secure end-to-end encrypted chat system |
+| **[Account](account.md)** | Account management - includes Messenger enablement |
+| **[Personal](personal.md)** | Personal on-chain portal |
+| **[LocalInfo](localinfo.md)** | Private information management |
+| **[Permission](permission.md)** | Permission management |
+| **[Arbitration](arbitration.md)** | Dispute resolution - can use WTS from Messenger as evidence |