@wowok/skills 1.1.5 → 1.1.7
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/README.md +1 -0
- package/dist/skills.d.ts.map +1 -1
- package/dist/skills.js +9 -1
- package/dist/skills.js.map +1 -1
- package/package.json +1 -1
- package/wowok-arbitrator/SKILL.md +105 -111
- package/wowok-guard/SKILL.md +72 -39
- package/wowok-machine/SKILL.md +137 -151
- package/wowok-messenger/SKILL.md +148 -178
- package/wowok-order/SKILL.md +186 -312
- package/wowok-output/SKILL.md +4 -0
- package/wowok-provider/SKILL.md +130 -176
- package/wowok-safety/SKILL.md +10 -8
- package/wowok-tools/SKILL.md +107 -157
package/wowok-messenger/SKILL.md
CHANGED
|
@@ -5,8 +5,8 @@ description: |
|
|
|
5
5
|
evidence collection, and dispute resolution.
|
|
6
6
|
|
|
7
7
|
Core features: send/receive encrypted messages, generate WTS evidence files,
|
|
8
|
-
verify message authenticity, manage
|
|
9
|
-
arbitration workflows.
|
|
8
|
+
verify message authenticity, manage conversations with anti-spam controls, and
|
|
9
|
+
integrate with arbitration workflows.
|
|
10
10
|
|
|
11
11
|
Used by customers, service providers, and arbitrators for secure off-chain
|
|
12
12
|
communication that creates tamper-proof audit trails.
|
|
@@ -22,12 +22,11 @@ always: false
|
|
|
22
22
|
|
|
23
23
|
# WoWok Messenger Guide
|
|
24
24
|
|
|
25
|
-
End-to-end encrypted messaging
|
|
25
|
+
End-to-end encrypted messaging with tamper-proof audit trails.
|
|
26
26
|
|
|
27
|
-
> **Role**: Any WoWok participant
|
|
28
|
-
> **
|
|
29
|
-
> **
|
|
30
|
-
> **Tool Reference**: See [wowok-tools](../wowok-tools/SKILL.md) for MCP tool schemas
|
|
27
|
+
> **Role**: Any WoWok participant
|
|
28
|
+
> **Schema**: `schema_query({ action: "get", name: "messenger_operation" })` — all 16 operations with full parameter types and constraints. This document focuses on **design decisions and strategy** not captured by the schema.
|
|
29
|
+
> **Related Skills**: [wowok-guard](../wowok-guard/SKILL.md) (guard design), [wowok-arbitrator](../wowok-arbitrator/SKILL.md) (WTS evidence in disputes), [wowok-order](../wowok-order/SKILL.md) (customer perspective), [wowok-provider](../wowok-provider/SKILL.md) (service provider perspective), [wowok-safety](../wowok-safety/SKILL.md) (safety)
|
|
31
30
|
|
|
32
31
|
---
|
|
33
32
|
|
|
@@ -35,259 +34,230 @@ End-to-end encrypted messaging for secure off-chain business communication with
|
|
|
35
34
|
|
|
36
35
|
### Trust Model
|
|
37
36
|
|
|
38
|
-
The
|
|
39
|
-
|
|
40
|
-
**Key Design Decisions**:
|
|
41
|
-
- Messages are **NOT on-chain**. Communication is off-chain for privacy and cost efficiency.
|
|
42
|
-
- The server **cannot read** messages. Ciphertext is opaque; only endpoints hold decryption keys.
|
|
43
|
-
- The server **proves message order**. Its Falcon512 signature on the Merkle tree is verifiable by anyone.
|
|
44
|
-
- On-chain proof is **optional**. A message's Merkle root can be anchored to the blockchain via `proof_message`.
|
|
37
|
+
Messages are **off-chain**, end-to-end encrypted. The server cannot read content — ciphertext is opaque. The server provides **verifiable message ordering** via Falcon512 signatures on a Merkle tree. On-chain anchoring (`proof_message`) is optional.
|
|
45
38
|
|
|
46
39
|
### Evidence Closure Principle
|
|
47
40
|
|
|
48
41
|
> **A message becomes valid evidence ONLY when the recipient explicitly responds to or decrypts it.**
|
|
49
42
|
|
|
50
|
-
One-sided claims are not evidence. The system enforces this through cryptographic and behavioral rules:
|
|
51
43
|
- A message alone proves nothing about the recipient's awareness.
|
|
52
|
-
- ARK confirmation (recipient-signed receipt) creates cryptographic proof
|
|
44
|
+
- ARK confirmation (recipient-signed receipt) creates cryptographic proof of acknowledgment.
|
|
53
45
|
- A reply is the strongest form of acknowledgment — it proves the recipient held the session key and acted on the message.
|
|
54
|
-
-
|
|
55
|
-
- Arbitration requires **confirmed**, reciprocated evidence — never unilateral claims.
|
|
56
|
-
|
|
57
|
-
---
|
|
58
|
-
|
|
59
|
-
## 1. Message Delivery Mechanism
|
|
46
|
+
- Arbitration requires **confirmed, reciprocated evidence** — never unilateral claims.
|
|
60
47
|
|
|
61
|
-
###
|
|
62
|
-
Messages from **strangers** (addresses not in the recipient's friends list) are subject to additional restrictions:
|
|
48
|
+
### Sessions
|
|
63
49
|
|
|
64
|
-
|
|
65
|
-
- **Reply unlocks**: When the recipient replies, the stranger is automatically added to the recipient's friends list, and both parties can message freely thereafter.
|
|
66
|
-
- **Cool-down window**: The one-message restriction persists for a configurable duration. If the recipient does not reply within this window, the stranger may retry one message.
|
|
67
|
-
- **Recipient opt-out**: A recipient can disable stranger messages entirely. When blocked, the sender receives the recipient's guard list as an alternative contact path.
|
|
50
|
+
Every conversation between two addresses has a deterministic session. Messages are ordered by a monotonically increasing `leafIndex` starting from zero, establishing their absolute position. Both parties share the same session context.
|
|
68
51
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
### 1.2 Guard Message Flow (Spam-Bypass Path)
|
|
52
|
+
---
|
|
72
53
|
|
|
73
|
-
|
|
54
|
+
## Setup
|
|
74
55
|
|
|
75
|
-
|
|
56
|
+
Before any communication:
|
|
76
57
|
|
|
77
|
-
|
|
58
|
+
1. **Account must exist** → `account_operation` (gen)
|
|
59
|
+
2. **Enable messenger** → `account_operation` (messenger), set a messenger name
|
|
60
|
+
3. **Get your address** → `account_operation` (get) — share this address with your counterparties
|
|
78
61
|
|
|
79
|
-
|
|
62
|
+
> The messenger name is required for message delivery. Without it, your account has no messenger endpoint and cannot receive messages.
|
|
80
63
|
|
|
81
64
|
---
|
|
82
65
|
|
|
83
|
-
##
|
|
66
|
+
## Daily Communication
|
|
84
67
|
|
|
85
|
-
|
|
68
|
+
The user's daily loop — these are the operations they will return to repeatedly.
|
|
86
69
|
|
|
87
|
-
|
|
70
|
+
### Check Inbox
|
|
88
71
|
|
|
89
|
-
|
|
72
|
+
Two approaches, depending on need:
|
|
90
73
|
|
|
91
|
-
|
|
74
|
+
- **Quick glance** — `watch_conversations` with `unreadOnly: true` lists all conversations with unread messages, sorted by activity. Each conversation shows a preview of the last messages.
|
|
75
|
+
- **Deep dive** — `watch_messages` with a specific `peerAddress` to view the full conversation with a particular counterparty. Supports keyword search, time-range filtering, direction filter, and status filter.
|
|
92
76
|
|
|
93
|
-
|
|
94
|
-
|------|---------|------------|-------------|
|
|
95
|
-
| **Blacklist** | Block specific addresses completely | `add`, `remove`, `clear`, `get`, `exist` | Server-configured max (default 1000) |
|
|
96
|
-
| **Friends List** | Allow trusted contacts to bypass all checks | `add`, `remove`, `clear`, `get`, `exist` | Server-configured max (default 1000) |
|
|
97
|
-
| **Guard List** | Specify which guards can verify strangers | `add`, `remove`, `get` | Server-configured max (default 100) |
|
|
77
|
+
**Design note**: By default, retrieving messages auto-marks them as viewed (`viewedAt` timestamp). Set `skipAutoMarkViewed: true` if you want to peek without marking read.
|
|
98
78
|
|
|
99
|
-
|
|
79
|
+
### Send Messages
|
|
100
80
|
|
|
101
|
-
|
|
102
|
-
- `guard`: The on-chain Guard object ID or name (see [wowok-guard](../wowok-guard/SKILL.md) for Guard design)
|
|
103
|
-
- `passportValiditySeconds`: How long a passport from this guard remains valid for messaging (typically 60s to 7 days)
|
|
81
|
+
Plain text via `send_message`; files (WTS, WIP, ZIP) via `send_file`.
|
|
104
82
|
|
|
105
|
-
|
|
83
|
+
**First-time contact with a stranger**: You get exactly one message. Make it count — include who you are, why you're contacting them, and what you need. After the recipient replies, you're auto-added to their friends list and can message freely.
|
|
106
84
|
|
|
107
|
-
|
|
85
|
+
**Guard-protected recipients**: If the recipient has disabled stranger messages, the rejection response includes their `guard_list`. Obtain a passport from one of those guards (`gen_passport` via `onchain_operations`), then resend with `guardAddress` + `passportAddress`.
|
|
108
86
|
|
|
109
|
-
|
|
87
|
+
**ZIP file attachments**: Use `send_file` for file delivery. Recipients extract via `extract_zip_messages`. The file is encrypted end-to-end; `zipMetadata` tracks download status locally.
|
|
110
88
|
|
|
111
|
-
|
|
89
|
+
### Mark as Read
|
|
112
90
|
|
|
113
|
-
-
|
|
114
|
-
|
|
115
|
-
- `false`: All stranger messages are rejected. The rejection response includes your `guard_list` so the sender can obtain a passport and retry.
|
|
116
|
-
|
|
117
|
-
- **`maxInboxSize`**: Maximum messages retained in your inbox (typically 10–1000). Older messages are removed when the limit is reached.
|
|
91
|
+
- `mark_conversation_as_viewed` — mark an entire conversation thread as read
|
|
92
|
+
- `mark_messages_as_viewed` — mark specific messages by ID
|
|
118
93
|
|
|
119
|
-
|
|
94
|
+
### Manage Contacts
|
|
120
95
|
|
|
121
|
-
|
|
96
|
+
Three independently managed lists. Schema covers all operations — here are the design choices:
|
|
122
97
|
|
|
123
|
-
|
|
98
|
+
| List | Design Intent |
|
|
99
|
+
|------|---------------|
|
|
100
|
+
| **Friends** | Mutual trust — added automatically when you reply to a stranger, or manually. Friends bypass all spam checks. |
|
|
101
|
+
| **Blacklist** | Permanent block — the address can never message you. |
|
|
102
|
+
| **Guard list** | Verified strangers — addresses holding a valid passport from any listed Guard can message you. Each entry pairs a Guard object ID with a validity duration (`passportValiditySeconds`: 10s to 10 years). |
|
|
124
103
|
|
|
125
|
-
|
|
104
|
+
---
|
|
126
105
|
|
|
127
|
-
|
|
106
|
+
## Anti-Spam Strategy
|
|
128
107
|
|
|
108
|
+
The four-layer protection model evaluates every incoming message:
|
|
129
109
|
|
|
130
|
-
|
|
110
|
+
```
|
|
111
|
+
Blacklist → Friends List → Guard Verification → Stranger Rules
|
|
112
|
+
(reject) (accept) (accept if passport valid) (one-message limit)
|
|
113
|
+
```
|
|
131
114
|
|
|
132
|
-
|
|
115
|
+
This section covers **how to configure these layers intelligently** for different user profiles — configuration combinations, not just field descriptions.
|
|
133
116
|
|
|
134
|
-
|
|
117
|
+
### Stranger Rules
|
|
135
118
|
|
|
136
|
-
|
|
119
|
+
Messages from non-friend, non-guard-verified addresses are subject to a **one-message limit**:
|
|
137
120
|
|
|
138
|
-
|
|
121
|
+
- Stranger sends one message. If the recipient replies, the stranger becomes a friend and messaging is unrestricted.
|
|
122
|
+
- If the recipient does not reply within the cool-down window, the stranger may retry with one new message.
|
|
123
|
+
- `allowStrangerMessages: false` disables stranger messages entirely.
|
|
139
124
|
|
|
140
|
-
|
|
125
|
+
### Strategy: Choosing Your Protection Profile
|
|
141
126
|
|
|
142
|
-
|
|
127
|
+
The optimal configuration depends on your role and openness needs:
|
|
143
128
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
129
|
+
| Profile | Settings | Who Should Use |
|
|
130
|
+
|---------|----------|----------------|
|
|
131
|
+
| **Open** | `allowStrangerMessages: true`, no guard list, empty blacklist | Public-facing services, open marketplaces |
|
|
132
|
+
| **Guarded** | `allowStrangerMessages: false`, guard list with 1-3 guards, friends list for known contacts | Service providers who want verified strangers only; customers discoverable by specific criteria |
|
|
133
|
+
| **Closed** | `allowStrangerMessages: false`, no guard list, friends-only | Private negotiations, internal team communication |
|
|
134
|
+
| **Defensive** | `allowStrangerMessages: true`, substantial blacklist | Users receiving harassment from specific addresses; open but monitoring |
|
|
147
135
|
|
|
148
|
-
**
|
|
136
|
+
**How to help the user choose**: Ask:
|
|
137
|
+
1. "Do you want strangers to be able to contact you at all?" → determines `allowStrangerMessages`
|
|
138
|
+
2. "If yes, should anyone be able to, or only those who meet certain criteria?" → determines Guard list need
|
|
139
|
+
3. "Are there specific addresses you want to block entirely?" → determines Blacklist use
|
|
149
140
|
|
|
150
|
-
|
|
141
|
+
### Strategy: Guard List Design
|
|
151
142
|
|
|
152
|
-
|
|
143
|
+
The Guard list is where anti-spam becomes programmable. A Guard validates that a stranger **meets a verifiable condition** before allowing their message through.
|
|
153
144
|
|
|
154
|
-
**
|
|
145
|
+
**Common Guard designs for messenger**:
|
|
155
146
|
|
|
156
|
-
|
|
147
|
+
| Guard Type | What It Verifies | Example Use |
|
|
148
|
+
|------------|-----------------|-------------|
|
|
149
|
+
| Token-gated | Sender holds a specific token/NFT | Premium customer community |
|
|
150
|
+
| Reputation | Sender's `personal` profile has ≥N likes | Verified reputation threshold |
|
|
151
|
+
| Order-based | Sender has an active order on your Service | Only current customers can message |
|
|
152
|
+
| Passport-based | Sender holds a valid passport from a trusted issuer | Whitelist of partner organizations |
|
|
153
|
+
| Payment | Sender has made a minimum payment | Paid consultation access |
|
|
157
154
|
|
|
158
|
-
|
|
155
|
+
**`passportValiditySeconds` trade-off**: Short (60s) = higher security, re-verification per message. Long (7 days) = better UX, one passport covers a week. Match to your Guard's use case: payment-based guards can use longer durations; order-status guards should use shorter durations (order state changes).
|
|
159
156
|
|
|
160
|
-
**
|
|
157
|
+
**Multiple guards**: Different guards can serve different purposes. A provider might use: (1) order-based guard for existing customers, (2) token-gated guard for premium access — both listed, either suffices for message delivery.
|
|
161
158
|
|
|
162
|
-
|
|
159
|
+
### Strategy: Troubleshooting Anti-Spam Issues
|
|
163
160
|
|
|
161
|
+
| Symptom | Diagnosis | Solution |
|
|
162
|
+
|---------|-----------|----------|
|
|
163
|
+
| "My message was rejected" | Recipient has `allowStrangerMessages: false` and you're not their friend | Check rejection response for `guard_list` → obtain passport → resend with `guardAddress`+`passportAddress` |
|
|
164
|
+
| "I'm getting too much spam" | `allowStrangerMessages: true` with no filtering | Switch to Guarded profile: set `allowStrangerMessages: false`, add at least one Guard to guard list |
|
|
165
|
+
| "A legitimate customer can't reach me" | Guard requirements too strict, or their passport expired | Lower Guard requirements, extend `passportValiditySeconds`, or add them to friends list manually |
|
|
166
|
+
| "Stranger keeps spamming after cool-down" | Working as designed — one retry per cool-down | Add to blacklist |
|
|
167
|
+
| "I disabled strangers but my friend can't message" | They may not actually be in your friends list | Use `friendslist` → `exist` to verify; add manually if needed |
|
|
164
168
|
|
|
165
|
-
|
|
169
|
+
### Strategy: Filtering Messages by Source
|
|
166
170
|
|
|
167
|
-
|
|
171
|
+
`watch_messages` supports `listFilterMode` to segment your inbox by relationship type:
|
|
168
172
|
|
|
169
|
-
|
|
173
|
+
- `friends` — only messages from your friends list
|
|
174
|
+
- `guard` — only messages from guard-verified senders
|
|
175
|
+
- `stranger` — only messages from unknown senders (highest priority for review)
|
|
176
|
+
- `any` — all messages (default)
|
|
170
177
|
|
|
171
|
-
|
|
178
|
+
Combine with `customListFilter` for fine-grained include/exclude logic.
|
|
172
179
|
|
|
173
|
-
|
|
180
|
+
**Practical use**: A service provider checking their inbox can first scan `listFilterMode: "friends"` for known-customer messages (low risk), then `listFilterMode: "stranger"` for new-customer inquiries (need attention).
|
|
174
181
|
|
|
175
182
|
---
|
|
176
183
|
|
|
177
|
-
##
|
|
178
|
-
|
|
179
|
-
### 4.1 Customer → Service Provider
|
|
184
|
+
## Evidence (WTS)
|
|
180
185
|
|
|
181
|
-
|
|
186
|
+
### Concept
|
|
182
187
|
|
|
183
|
-
|
|
184
|
-
- Query the Service object via `query_toolkit` with `query_type: "onchain_objects"` to extract `service.um` (Contact object ID)
|
|
185
|
-
- Query the Contact object to get `ims[].at` (list of messenger addresses the provider accepts messages at)
|
|
188
|
+
A WTS file is a **tamper-proof, self-verifying export** of a continuous conversation. Every message is cryptographically chained; any gap or modification breaks the chain. Participant signatures add non-repudiation.
|
|
186
189
|
|
|
187
|
-
|
|
188
|
-
- After order creation, check the Service's `customer_required` field (phone, email, delivery address, etc.)
|
|
189
|
-
- **AI should prompt**: Ask if the user wants to save this information to `local_info` for future use, or retrieve existing info from `local_info_list` to avoid re-entry
|
|
190
|
-
- Retrieve matching private information from local storage using `query_toolkit` → `local_info_list`
|
|
191
|
-
- Send via `messenger_operation` with `send_message` to the provider's customer service address
|
|
192
|
-
- **Request explicit confirmation** — unconfirmed delivery may stall order progress
|
|
193
|
-
- If this is first contact, you have exactly one message — make it count
|
|
190
|
+
### The Workflow
|
|
194
191
|
|
|
195
|
-
|
|
192
|
+
When a dispute requires evidence:
|
|
196
193
|
|
|
197
|
-
|
|
194
|
+
```
|
|
195
|
+
1. generate_wts → export messages by time/messageId/seqIndex range
|
|
196
|
+
2. sign_wts → add your Falcon512 signature (both parties can sign)
|
|
197
|
+
3. verify_wts → validate hash chain, continuity, and all signatures
|
|
198
|
+
4. wts2html → (optional) convert to human-readable HTML
|
|
199
|
+
5. send_file → submit signed WTS to the arbitrator via messenger
|
|
200
|
+
```
|
|
198
201
|
|
|
199
|
-
**
|
|
202
|
+
> **Key design decision**: Include the **full conversation** when generating WTS for arbitration — not just favorable messages. The arbitrator needs to see who said what, who acknowledged what, and the exact sequence. Selective exports undermine your credibility.
|
|
200
203
|
|
|
201
|
-
|
|
202
|
-
2. **Respond promptly**: Use `send_message` to reply. Your reply automatically adds the customer to your friends list if they were a stranger.
|
|
203
|
-
3. **Document agreements**: For any commitments (pricing, timeline changes, custom work), confirm them in messages. These become evidence if disputes arise.
|
|
204
|
-
4. **WTS for disputes**: If a disagreement escalates, the provider may generate and sign WTS to demonstrate good faith and support their position.
|
|
204
|
+
### On-Chain Proof (Optional)
|
|
205
205
|
|
|
206
|
-
|
|
207
|
-
- Respond promptly to maintain trust
|
|
208
|
-
- Document all agreements and changes in messages
|
|
209
|
-
- Confirm understanding before proceeding with orders
|
|
210
|
-
- Use guard list to allow verified strangers to reach you without opening to all strangers
|
|
206
|
+
`proof_message` anchors a message to the blockchain, creating an immutable timestamp proving the message existed before that point. Anyone can independently verify against this on-chain record.
|
|
211
207
|
|
|
212
|
-
|
|
208
|
+
### When to Generate WTS
|
|
213
209
|
|
|
214
|
-
|
|
210
|
+
- **Disputes only** — normal conversations are preserved server-side. WTS is evidence preparation, not archiving.
|
|
211
|
+
- **When the other party disputes a fact** — the WTS proves what was actually said and acknowledged.
|
|
212
|
+
- **When arbitration requires evidence submission** — signed WTS is the standard evidence format.
|
|
215
213
|
|
|
216
|
-
|
|
214
|
+
---
|
|
217
215
|
|
|
218
|
-
|
|
216
|
+
## Messenger Across Roles
|
|
219
217
|
|
|
220
|
-
|
|
221
|
-
2. **Messenger must be enabled**: Set a messenger name on the account via `account_operation` to enable Messenger functionality; clear it to disable.
|
|
218
|
+
This section shows **how Messenger fits into each participant's workflow** — not detailed SOP (see the role-specific skills for complete workflows), but the Messenger-specific touchpoints.
|
|
222
219
|
|
|
220
|
+
### Customer
|
|
223
221
|
|
|
224
|
-
|
|
222
|
+
| Touchpoint | Messenger Operation | When |
|
|
223
|
+
|------------|-------------------|------|
|
|
224
|
+
| Pre-order inquiry | `send_message` to service provider | Before order creation — ask about service details, pricing, custom requirements |
|
|
225
|
+
| Submit required info | `send_message` with delivery address, phone, etc. | After order creation — the Service's `customer_required` fields dictate what to send |
|
|
226
|
+
| Track progress | `watch_messages` with provider | During order fulfillment — receive status updates |
|
|
227
|
+
| Raise dispute | `generate_wts` + `sign_wts` + `send_file` to arbitrator | When resolution fails — submit evidence |
|
|
225
228
|
|
|
226
|
-
|
|
227
|
-
1. **Get current state**: Use `settings` (`get`) and list operations (`get`) to see the current configuration.
|
|
228
|
-
2. **Add trusted contacts**: Use `friendslist` (`add`) for known counterparties.
|
|
229
|
-
3. **Configure guards**: Use `guardlist` (`add`) if you want to accept verified strangers. The Guard objects must already exist on-chain (see [wowok-guard](../wowok-guard/SKILL.md)).
|
|
230
|
-
4. **Set stranger policy**: Use `settings` (`set`) with `allowStrangerMessages` to toggle stranger access.
|
|
231
|
-
5. **Block unwanted**: Use `blacklist` (`add`) for addresses you never want to hear from.
|
|
229
|
+
> **Full workflow**: See [wowok-order](../wowok-order/SKILL.md) for the complete customer journey.
|
|
232
230
|
|
|
233
|
-
|
|
231
|
+
### Service Provider
|
|
234
232
|
|
|
235
|
-
|
|
233
|
+
| Touchpoint | Messenger Operation | When |
|
|
234
|
+
|------------|-------------------|------|
|
|
235
|
+
| Monitor inquiries | `watch_conversations` with `unreadOnly` or `listFilterMode: "stranger"` | Daily — check for new customer messages |
|
|
236
|
+
| Respond to customers | `send_message` (reply auto-adds to friends) | As needed — timely response builds trust |
|
|
237
|
+
| Request customer info | `send_message` asking for `customer_required` fields | After order creation if not yet provided |
|
|
238
|
+
| Document agreements | `send_message` confirming terms, changes, custom work | Immediately after agreement — creates evidence trail |
|
|
239
|
+
| Dispute defense | `generate_wts` + `sign_wts` + `send_file` | When a customer escalates — prove good-faith communication |
|
|
236
240
|
|
|
237
|
-
|
|
241
|
+
> **Full workflow**: See [wowok-provider](../wowok-provider/SKILL.md) for the complete service provider journey.
|
|
238
242
|
|
|
239
|
-
|
|
243
|
+
### Arbitrator
|
|
240
244
|
|
|
241
|
-
|
|
245
|
+
| Touchpoint | Messenger Operation | When |
|
|
246
|
+
|------------|-------------------|------|
|
|
247
|
+
| Receive evidence | `watch_messages` or `watch_conversations` | When parties submit WTS files |
|
|
248
|
+
| Verify evidence | `verify_wts` on received files | Before reviewing — ensure evidence integrity |
|
|
249
|
+
| Communicate with parties | `send_message` for clarification requests | During dispute review |
|
|
250
|
+
| Sign attestation | `sign_wts` on verified evidence | After verification — arbitrator endorses authenticity |
|
|
242
251
|
|
|
243
|
-
|
|
252
|
+
> **Full workflow**: See [wowok-arbitrator](../wowok-arbitrator/SKILL.md) for the complete arbitration process.
|
|
244
253
|
|
|
245
|
-
| Purpose | Schema Name |
|
|
246
|
-
|---------|-------------|
|
|
247
|
-
| All messenger operations | `messenger_operation` |
|
|
248
|
-
| Query on-chain objects (services, guards, contacts) | `query_toolkit` |
|
|
249
|
-
| On-chain operations (gen_passport for guard) | `onchain_operations` |
|
|
250
|
-
| Local account management | `account_operation` |
|
|
251
|
-
| Local address book (marks) | `local_mark_operation` |
|
|
252
|
-
| Local private info storage | `local_info_operation` |
|
|
253
254
|
---
|
|
254
255
|
|
|
255
|
-
##
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
| View conversations | `watch_conversations` | `filter.unreadOnly?`, `filter.previewMessageCount?`, `filter.sortBy?` |
|
|
264
|
-
| View messages | `watch_messages` | `filter.peerAddress?`, `filter.direction?`, `filter.contentType?`, `filter.keyword?` |
|
|
265
|
-
| Mark as read | `mark_messages_as_viewed` | `messageIds`, `account?` |
|
|
266
|
-
| Mark convo read | `mark_conversation_as_viewed` | `peerAddress`, `account?` |
|
|
267
|
-
|
|
268
|
-
### Evidence (WTS)
|
|
269
|
-
|
|
270
|
-
| Goal | Operation | Key Parameters |
|
|
271
|
-
|------|-----------|----------------|
|
|
272
|
-
| Export | `generate_wts` | `params.myAccount`, `params.peerAccount`, `params.range?`, `params.outputDir` |
|
|
273
|
-
| Sign | `sign_wts` | `wtsFilePath`, `account`, `outputPath?` |
|
|
274
|
-
| Verify | `verify_wts` | `wtsFilePath` |
|
|
275
|
-
| View HTML | `wts2html` | `wtsPath`, `options.title?`, `options.theme?` |
|
|
276
|
-
| Prove on-chain | `proof_message` | `account`, `messageId`, `network` |
|
|
277
|
-
| Extract ZIP | `extract_zip_messages` | `account`, `messages`, `outputDir` |
|
|
278
|
-
|
|
279
|
-
### List Management
|
|
280
|
-
|
|
281
|
-
| Goal | Operation | Key Parameters |
|
|
282
|
-
|------|-----------|----------------|
|
|
283
|
-
| Add friend | `friendslist` (`add`) | `account`, `users` (addresses/names) |
|
|
284
|
-
| Block user | `blacklist` (`add`) | `account`, `users` (addresses/names) |
|
|
285
|
-
| Add guard | `guardlist` (`add`) | `account`, `guards[].guard`, `guards[].passportValiditySeconds` |
|
|
286
|
-
| Toggle strangers | `settings` (`set`) | `account`, `allowStrangerMessages` |
|
|
287
|
-
|
|
288
|
-
### Local Storage
|
|
289
|
-
|
|
290
|
-
| Goal | Tool | Key Parameters |
|
|
291
|
-
|------|------|----------------|
|
|
292
|
-
| Write private info | `local_info_operation` (add) | `data`: array of `{ name, default, contents }` |
|
|
293
|
-
| Read private info | `query_toolkit` → `local_info_list` | `filter.name?` |
|
|
256
|
+
## Common Pitfalls
|
|
257
|
+
|
|
258
|
+
- **One-message limit trap**: Sending a vague first message to a stranger wastes your only chance. Make the first message complete and actionable.
|
|
259
|
+
- **Disabled messenger**: Without a messenger name set, your account has no endpoint — counterparties cannot find or message you.
|
|
260
|
+
- **WTS range too narrow**: Selecting only favorable messages undermines evidence credibility. Include the full conversation.
|
|
261
|
+
- **Guard list without strategy**: Adding a Guard to your list without testing it (`gen_passport`) means you don't know what conditions strangers must meet — you may be blocking legitimate contacts.
|
|
262
|
+
- **`allowStrangerMessages: false` with no guard list and no friends**: Nobody can contact you. Always ensure at least one inbound path exists.
|
|
263
|
+
- **Stale passports**: `passportValiditySeconds` too short causes frequent re-verification failures. Match duration to your Guard's data volatility.
|