@wowok/agent-mcp 2.3.7 → 2.3.8

package/dist/schemas/bridge_operation.output.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://wowok.net/schemas/bridge_operation.json",
+  "title": "Bridge - Cross-Chain Operations",
+  "description": "Simplified cross-chain bridge between WOW and EVM (Ethereum mainnet). Operations: cross_chain_wow_to_evm, cross_chain_evm_to_wow, withdraw, query_active_evm_account, query_supported_evm_chains, query_supported_tokens, query_transfer_list, query_transfer_status, manage_evm_rpc. Global single activeEvmAccount auto-generated on first use. Use schema_query (name='bridge_operation') for exact field structures.",
+  "$ref": "#/definitions/bridge_operation",
+  "definitions": {
+    "bridge_operation": {
+      "type": "object",
+      "properties": {
+        "message": {
+          "type": "string",
+          "description": "Result summary or hint message"
+        },
+        "result": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "const": "data"
+                },
+                "data": {
+                  "description": "Operation result data (structure varies by operation_type)"
+                }
+              },
+              "required": [
+                "type"
+              ],
+              "additionalProperties": false,
+              "description": "Successful result"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "const": "error"
+                },
+                "error": {
+                  "type": "string",
+                  "description": "Error message"
+                }
+              },
+              "required": [
+                "type",
+                "error"
+              ],
+              "additionalProperties": false,
+              "description": "Error result"
+            }
+          ],
+          "description": "Bridge operation result (data or error)"
+        }
+      },
+      "required": [
+        "result"
+      ],
+      "additionalProperties": false,
+      "description": "Bridge operation output (matches CallOutput structure returned by the handler)"
+    }
+  }
+}

package/dist/schemas/bridge_operation.schema.json

@@ -0,0 +1,547 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://wowok.net/schemas/bridge_operation.json",
+  "title": "Bridge - Cross-Chain Operations",
+  "description": "Simplified cross-chain bridge between WOW and EVM (Ethereum mainnet). Operations: cross_chain_wow_to_evm, cross_chain_evm_to_wow, withdraw, query_active_evm_account, query_supported_evm_chains, query_supported_tokens, query_transfer_list, query_transfer_status, manage_evm_rpc. Global single activeEvmAccount auto-generated on first use. Use schema_query (name='bridge_operation') for exact field structures.",
+  "$ref": "#/definitions/bridge_operation",
+  "definitions": {
+    "bridge_operation": {
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "operation_type": {
+              "type": "string",
+              "const": "cross_chain_wow_to_evm"
+            },
+            "data": {
+              "type": "object",
+              "properties": {
+                "token": {
+                  "type": "string",
+                  "enum": [
+                    "ETH",
+                    "WETH",
+                    "WBTC",
+                    "USDC",
+                    "USDT"
+                  ],
+                  "description": "Cross-chain token type"
+                },
+                "amount": {
+                  "type": "string",
+                  "description": "Cross-chain amount (WOW-side smallest unit, wowDecimals)"
+                },
+                "withdrawTo": {
+                  "type": "string",
+                  "pattern": "^0x[0-9a-fA-F]{40}$",
+                  "description": "Final withdrawal EVM address; if omitted, assets remain in activeEvmAccount. When provided, the SDK uses the activeEvmAccount key to transfer to this address."
+                }
+              },
+              "required": [
+                "token",
+                "amount"
+              ],
+              "additionalProperties": false,
+              "description": "WOW→EVM cross-chain (step 1: deposit only). Returns immediately with depositTxDigest + bridgeSeq + transferId. This operation only locks assets on WOW; it does NOT complete the cross-chain. After deposit, bridge nodes need ~1-5 minutes to sign. Use query_transfer_status to monitor progress; when latestState.step shows 'signatures_ready', call claim_wow_to_evm (step 2) to claim assets on EVM. [Gas requirements] Step 1 needs WOW gas; Step 2 (claim_wow_to_evm) needs activeEvmAccount to have target-chain gas."
+            },
+            "env": {
+              "type": "object",
+              "properties": {
+                "account": {
+                  "type": "string",
+                  "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters).",
+                  "default": ""
+                },
+                "permission_guard": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "List of permission guard IDs. Used to extend additional operation permissions (requires verification and configuration in the Permission object)."
+                },
+                "no_cache": {
+                  "type": "boolean",
+                  "description": "Whether to disable caching."
+                },
+                "network": {
+                  "type": "string",
+                  "enum": [
+                    "localnet",
+                    "testnet",
+                    "mainnet"
+                  ],
+                  "description": "Network entrypoint: Specifies which network the operation occurs on"
+                },
+                "referrer": {
+                  "$ref": "#/definitions/bridge_operation/anyOf/0/properties/env/properties/account",
+                  "description": "Referrer ID. If the user is using the network for the first time, the referrer ID will be recorded."
+                }
+              },
+              "additionalProperties": false,
+              "description": "IMPORTANT: Execution environment includes: account for signing operations, network selection ([object Object]), additional Guard permissions, and more. Used to specify context information during the call. If account is not specified, the default account (\"\") will be used."
+            }
+          },
+          "required": [
+            "operation_type",
+            "data"
+          ],
+          "additionalProperties": false,
+          "description": "WOW→EVM cross-chain (simplified): assets auto-claim to activeEvmAccount; if withdrawTo is provided, an additional transfer is made to that address. [Requires WOW mainnet env]"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation_type": {
+              "type": "string",
+              "const": "cross_chain_evm_to_wow"
+            },
+            "data": {
+              "type": "object",
+              "properties": {
+                "token": {
+                  "type": "string",
+                  "enum": [
+                    "ETH",
+                    "WETH",
+                    "WBTC",
+                    "USDC",
+                    "USDT"
+                  ],
+                  "description": "Cross-chain token type (ETH=native ETH, others are ERC20)"
+                },
+                "amount": {
+                  "type": "string",
+                  "description": "Cross-chain amount (EVM-side smallest unit, evmDecimals)"
+                },
+                "recipientWowAddress": {
+                  "type": "string",
+                  "description": "WOW recipient address or account name; defaults to env.account if omitted"
+                }
+              },
+              "required": [
+                "token",
+                "amount"
+              ],
+              "additionalProperties": false,
+              "description": "EVM→WOW cross-chain (single step: deposit). Returns immediately with depositTxHash + transferId. Bridge will automatically claim on WOW (no WOW gas needed, no user action required). [Time estimate] ~10-20 minutes total: (1) 64-block confirmation ~12.8 min on ETH; (2) bridge node auto-claim ~1-5 min on WOW. [Status flow] Use query_transfer_status(refresh=true) to monitor: latestState.step: source_tx_pending → source_tx_confirmed → signatures_ready → completed. When latestState.confirmations >= 64, deposit is finalized and bridge nodes will sign. [Gas requirements] Only needs activeEvmAccount to have target-chain gas (for deposit). No WOW gas needed."
+            },
+            "env": {
+              "$ref": "#/definitions/bridge_operation/anyOf/0/properties/env",
+              "description": "IMPORTANT: Execution environment includes: account for signing operations, network selection ([object Object]), additional Guard permissions, and more. Used to specify context information during the call. If account is not specified, the default account (\"\") will be used."
+            }
+          },
+          "required": [
+            "operation_type",
+            "data"
+          ],
+          "additionalProperties": false,
+          "description": "EVM→WOW cross-chain (single step): deposit from activeEvmAccount, bridge auto-claims on WOW. No WOW gas needed. [Requires WOW mainnet env]"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation_type": {
+              "type": "string",
+              "const": "claim_wow_to_evm"
+            },
+            "data": {
+              "type": "object",
+              "properties": {
+                "transferId": {
+                  "type": "string",
+                  "description": "Transfer ID from cross_chain_wow_to_evm (br_<timestamp>_<counter>)"
+                }
+              },
+              "required": [
+                "transferId"
+              ],
+              "additionalProperties": false,
+              "description": "WOW→EVM claim (step 2): claim assets on EVM after bridge nodes have signed. Prerequisite: cross_chain_wow_to_evm (step 1) must be completed, and query_transfer_status must show latestState.step = 'signatures_ready' or 'source_tx_confirmed' (nodes have approved). Returns claimTxHash on success. After claim_wow_to_evm returns, the claim tx has been submitted and confirmed (1 block) on EVM. Use query_transfer_status(refresh=true) to verify latestState.step = 'completed'. [Gas requirements] Requires activeEvmAccount to have target-chain gas (for the claim transaction)."
+            },
+            "env": {
+              "$ref": "#/definitions/bridge_operation/anyOf/0/properties/env",
+              "description": "IMPORTANT: Execution environment includes: account for signing operations, network selection ([object Object]), additional Guard permissions, and more. Used to specify context information during the call. If account is not specified, the default account (\"\") will be used."
+            }
+          },
+          "required": [
+            "operation_type",
+            "data"
+          ],
+          "additionalProperties": false,
+          "description": "WOW→EVM claim (step 2): claim assets on EVM after bridge signed. Requires activeEvmAccount to have EVM gas. [Requires WOW mainnet env]"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation_type": {
+              "type": "string",
+              "const": "withdraw"
+            },
+            "data": {
+              "type": "object",
+              "properties": {
+                "to": {
+                  "type": "string",
+                  "pattern": "^0x[0-9a-fA-F]{40}$",
+                  "description": "Withdrawal target EVM address"
+                },
+                "amount": {
+                  "type": "string",
+                  "description": "Withdrawal amount (smallest unit)"
+                },
+                "token": {
+                  "type": "string",
+                  "enum": [
+                    "ETH",
+                    "WETH",
+                    "WBTC",
+                    "USDC",
+                    "USDT"
+                  ],
+                  "description": "ERC20 token identifier; if omitted or ETH, withdraws native ETH"
+                },
+                "tokenAddress": {
+                  "$ref": "#/definitions/bridge_operation/anyOf/0/properties/data/properties/withdrawTo",
+                  "description": "ERC20 contract address (alternative to token; allows withdrawing by contract address)"
+                },
+                "network": {
+                  "type": "string",
+                  "enum": [
+                    "mainnet"
+                  ],
+                  "default": "mainnet",
+                  "description": "Target chain (defaults to Ethereum mainnet)"
+                }
+              },
+              "required": [
+                "to",
+                "amount"
+              ],
+              "additionalProperties": false,
+              "description": "Withdraw from activeEvmAccount to another EVM address"
+            }
+          },
+          "required": [
+            "operation_type",
+            "data"
+          ],
+          "additionalProperties": false,
+          "description": "Withdraw from activeEvmAccount to another EVM address (non-cross-chain). [No env needed]"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation_type": {
+              "type": "string",
+              "const": "query_active_evm_account"
+            },
+            "data": {
+              "type": "object",
+              "properties": {
+                "network": {
+                  "$ref": "#/definitions/bridge_operation/anyOf/3/properties/data/properties/network",
+                  "description": "Specific chain; if omitted, queries all supported chains"
+                },
+                "tokens": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/definitions/bridge_operation/anyOf/0/properties/data/properties/withdrawTo"
+                  },
+                  "description": "Additional ERC20 token contract addresses to query; if omitted, only native ETH balance is queried"
+                }
+              },
+              "additionalProperties": false,
+              "description": "Query activeEvmAccount parameters"
+            }
+          },
+          "required": [
+            "operation_type"
+          ],
+          "additionalProperties": false,
+          "description": "Query activeEvmAccount address + balances (per chain or all chains). [No env needed]"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation_type": {
+              "type": "string",
+              "const": "query_supported_evm_chains"
+            }
+          },
+          "required": [
+            "operation_type"
+          ],
+          "additionalProperties": false,
+          "description": "List currently supported EVM chains (enum value / description / chainId / RPC health). [No env needed, no data required]"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation_type": {
+              "type": "string",
+              "const": "query_supported_tokens"
+            },
+            "data": {
+              "type": "object",
+              "properties": {
+                "network": {
+                  "$ref": "#/definitions/bridge_operation/anyOf/3/properties/data/properties/network",
+                  "description": "Specific chain; if omitted, returns token lists for all supported chains"
+                }
+              },
+              "additionalProperties": false,
+              "description": "Query supported Bridge tokens per chain (WOW/EVM addresses, decimals, description)"
+            }
+          },
+          "required": [
+            "operation_type"
+          ],
+          "additionalProperties": false,
+          "description": "List supported Bridge tokens per chain (WOW/EVM contract addresses, decimals, description). [No env needed]"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation_type": {
+              "type": "string",
+              "const": "query_transfer_list"
+            },
+            "data": {
+              "type": "object",
+              "properties": {
+                "onlyActive": {
+                  "type": "boolean",
+                  "description": "true returns only in-progress transfers; false/omitted returns all"
+                },
+                "status": {
+                  "type": "string",
+                  "enum": [
+                    "pending",
+                    "in_progress",
+                    "success",
+                    "failed"
+                  ],
+                  "description": "Filter by transfer status"
+                },
+                "direction": {
+                  "type": "string",
+                  "enum": [
+                    "wow_to_evm",
+                    "evm_to_wow",
+                    "withdraw"
+                  ],
+                  "description": "Filter by transfer direction"
+                },
+                "token": {
+                  "$ref": "#/definitions/bridge_operation/anyOf/3/properties/data/properties/token",
+                  "description": "Filter by token type (ETH/WETH/WBTC/USDC/USDT)"
+                },
+                "limit": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0,
+                  "maximum": 100,
+                  "description": "Maximum number of results (default: all, max: 100)"
+                }
+              },
+              "additionalProperties": false,
+              "description": "Query transfer list with optional filters (status / direction / token / limit)"
+            }
+          },
+          "required": [
+            "operation_type"
+          ],
+          "additionalProperties": false,
+          "description": "Query cross-chain / withdrawal transfer history list (optionally only in-progress). [No env needed]"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation_type": {
+              "type": "string",
+              "const": "query_transfer_status"
+            },
+            "data": {
+              "type": "object",
+              "properties": {
+                "transferId": {
+                  "type": "string",
+                  "description": "Transfer ID (br_<timestamp>_<counter>)"
+                },
+                "refresh": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Whether to refresh from on-chain state (default true). true=queries latest on-chain status (takes 5-15s, timeout at 15s on slow RPC). false=instant response from local cache (no on-chain query). Recommended: use refresh=true every 1-2 minutes for ongoing transfers; use refresh=false for quick checks between refreshes."
+                }
+              },
+              "required": [
+                "transferId"
+              ],
+              "additionalProperties": false,
+              "description": "Query single transfer parameters. [Wait hint] With refresh=true (default), this call may take 5-15 seconds to query on-chain state. If on-chain RPC is slow, it will timeout at 15s and return cached state. Set refresh=false for instant response from local cache. [Returned fields] The result includes: (1) record.step/status - high-level lifecycle (deposit/claimed/success); (2) record.latestState.step/status - fine-grained on-chain progress (source_tx_pending → source_tx_confirmed → signatures_ready → completed). Use latestState.confirmations to estimate remaining time (needs 64 for ETH→WOW finalization)."
+            }
+          },
+          "required": [
+            "operation_type",
+            "data"
+          ],
+          "additionalProperties": false,
+          "description": "Query a single transfer's detail by transferId"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation_type": {
+              "type": "string",
+              "const": "manage_evm_rpc"
+            },
+            "data": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "op": {
+                      "type": "string",
+                      "const": "list",
+                      "description": "List all configured RPC endpoints with health status"
+                    },
+                    "network": {
+                      "$ref": "#/definitions/bridge_operation/anyOf/3/properties/data/properties/network",
+                      "description": "Target chain (defaults to Ethereum mainnet)"
+                    }
+                  },
+                  "required": [
+                    "op"
+                  ],
+                  "additionalProperties": false,
+                  "description": "List RPC endpoints (no rpcUrl/rpcUrls needed)"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "op": {
+                      "type": "string",
+                      "const": "add",
+                      "description": "Append one or more RPC endpoints"
+                    },
+                    "network": {
+                      "$ref": "#/definitions/bridge_operation/anyOf/3/properties/data/properties/network",
+                      "description": "Target chain (defaults to Ethereum mainnet)"
+                    },
+                    "rpcUrls": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "format": "uri"
+                      },
+                      "minItems": 1,
+                      "description": "RPC URL(s) to add"
+                    }
+                  },
+                  "required": [
+                    "op",
+                    "rpcUrls"
+                  ],
+                  "additionalProperties": false,
+                  "description": "Add RPC endpoint(s)"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "op": {
+                      "type": "string",
+                      "const": "remove",
+                      "description": "Remove one or more RPC endpoints"
+                    },
+                    "network": {
+                      "$ref": "#/definitions/bridge_operation/anyOf/3/properties/data/properties/network",
+                      "description": "Target chain (defaults to Ethereum mainnet)"
+                    },
+                    "rpcUrls": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "format": "uri"
+                      },
+                      "minItems": 1,
+                      "description": "RPC URL(s) to remove"
+                    }
+                  },
+                  "required": [
+                    "op",
+                    "rpcUrls"
+                  ],
+                  "additionalProperties": false,
+                  "description": "Remove RPC endpoint(s)"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "op": {
+                      "type": "string",
+                      "const": "set",
+                      "description": "Full replace all RPC endpoints"
+                    },
+                    "network": {
+                      "$ref": "#/definitions/bridge_operation/anyOf/3/properties/data/properties/network",
+                      "description": "Target chain (defaults to Ethereum mainnet)"
+                    },
+                    "rpcUrls": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "format": "uri"
+                      },
+                      "minItems": 1,
+                      "description": "Full RPC list (replaces all existing endpoints)"
+                    }
+                  },
+                  "required": [
+                    "op",
+                    "rpcUrls"
+                  ],
+                  "additionalProperties": false,
+                  "description": "Full replace RPC endpoints"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "op": {
+                      "type": "string",
+                      "const": "ping",
+                      "description": "Health check one or more RPC endpoints"
+                    },
+                    "network": {
+                      "$ref": "#/definitions/bridge_operation/anyOf/3/properties/data/properties/network",
+                      "description": "Target chain (defaults to Ethereum mainnet)"
+                    },
+                    "rpcUrls": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "format": "uri"
+                      },
+                      "description": "Specific RPC URLs to ping; if omitted, pings all configured RPCs"
+                    }
+                  },
+                  "required": [
+                    "op"
+                  ],
+                  "additionalProperties": false,
+                  "description": "Health check RPC endpoints"
+                }
+              ],
+              "description": "EVM RPC endpoint management (discriminated by op)"
+            }
+          },
+          "required": [
+            "operation_type",
+            "data"
+          ],
+          "additionalProperties": false,
+          "description": "Manage EVM RPC endpoints (list/add/remove/set/ping) to mitigate public RPC 429 rate limits. [No env needed]"
+        }
+      ]
+    }
+  }
+}