--- name: qfc-openclaw-skill description: QFC blockchain interaction — wallet, faucet, chain queries, staking, epoch & finality, AI inference homepage: https://github.com/qfc-network/qfc-openclaw-skill license: MIT metadata: {"openclaw":{"requires":{"bins":["node"]}}} --- # QFC OpenClaw Skill > AI agent skill for full QFC blockchain interaction ## Capabilities ### Wallet Management - **Create Wallet**: Generate a new HD wallet with mnemonic, address, and private key - **Import Wallet**: Restore wallet from private key - **Get Balance**: Query QFC balance for any address - **Send QFC**: Transfer QFC tokens to another address - **Sign Message**: Sign an arbitrary message with the wallet's private key ### Wallet Persistence - **Save Wallet**: Encrypt and persist a wallet to disk (`~/.openclaw/qfc-wallets/`) using industry-standard keystore format (scrypt KDF, compatible with MetaMask/Geth) - **Load Wallet**: Decrypt and restore a previously saved wallet by address + password - **List Saved Wallets**: Show all persisted wallets (address, name, network) without needing a password - **Remove Wallet**: Delete a saved wallet's keystore file and metadata - **Export Keystore JSON**: Get the encrypted keystore JSON for a saved wallet (for import into MetaMask or other tools) ### Faucet (Testnet Only) - **Request Test QFC**: Get test tokens on testnet (chain_id=9000) ### Chain Queries - **Get Block Number**: Latest block height - **Get Block**: Block details by number or 'latest' - **Get Transaction**: Transaction info by hash - **Get Receipt**: Transaction receipt with logs ### Network Status - **Node Info**: Version, chain ID, peer count, validator status - **Network State**: Current network condition (normal/congested) - **Chain ID / Block Number / Gas Price**: Basic network parameters ### Staking & Validators - **List Validators**: All validators with stake, score, and compute mode - **Get Stake**: Staked QFC amount for an address - **Contribution Score**: Validator score (0-10000) - **Score Breakdown**: Detailed 7-dimension scoring with metrics ### Epoch & Finality - **Current Epoch**: Epoch number, start time, duration - **Finalized Block**: Latest finalized block number ### Smart Contracts (v2.1) - **Call Contract**: Read contract state (no gas needed) — pass address, ABI, method, and args - **Send Transaction**: Write to a contract (requires wallet signer, costs gas) - **Deploy Contract**: Deploy a new contract from ABI + bytecode - **Check Contract**: Verify if an address has contract code deployed - **Get Code**: Retrieve raw bytecode at an address - **Verify Contract**: Submit source code to QFC explorer for verification (compiler version, EVM version, optimizer settings) ### ERC-20 Tokens (v2.1) - **Deploy Token**: Create a new ERC-20 token on QFC — specify name, symbol, and initial supply. All tokens are minted to the deployer. No compiler needed (pre-compiled bytecode). Set `mintable: true` for a token with mint/burn/owner support. Auto-verifies source code on QFC explorer after deployment. - **Mint Tokens**: Mint new tokens to any address (mintable tokens only, caller must be owner) - **Burn Tokens**: Burn tokens from your balance (reduces total supply, mintable tokens only) - **Token Info**: Get name, symbol, decimals, and total supply of any ERC-20 token - **Token Balance**: Check token balance for any address - **Transfer Tokens**: Send ERC-20 tokens to another address (auto-handles decimals) - **Approve Spender**: Approve a contract/address to spend tokens (supports "max" for unlimited) - **Check Allowance**: Query how much a spender is approved to use - **Token Portfolio** (v2.3): View all token holdings for a wallet — native QFC balance plus every ERC-20 token with non-zero balance - **Transfer History** (v2.3): View token transfer history from the explorer — filter by token and/or address - **Batch Transfer Tokens** (v2.4): Send tokens to multiple addresses in one operation (sequential transfers) - **Batch Send QFC** (v2.4): Send native QFC to multiple addresses - **Deploy Airdrop Contract** (v2.5): Deploy a reusable Airdrop contract — batch transfer any ERC-20 in a single transaction (saves gas vs sequential). Auto-verifies source on explorer. - **Smart Airdrop** (v2.5): Airdrop tokens via the Airdrop contract — auto-approves, supports variable or fixed amounts per recipient ### NFT / ERC-721 (v2.4) - **Deploy NFT Collection**: Create a new ERC-721 NFT contract with name and symbol - **Mint NFT**: Mint a new NFT with metadata URI to any address (owner only) - **View NFT**: Query token URI, owner, and balance for any NFT - **Transfer NFT**: Transfer an NFT to another address ### Token Swap / DEX (v2.5) - **Deploy Pool**: Create a constant-product AMM pool (x*y=k) for any ERC-20 token pair. 0.3% swap fee. LP tokens track liquidity shares. Auto-verifies source on explorer. - **Pool Info**: View pool reserves, token details, current price, and total LP supply - **Add Liquidity**: Deposit both tokens into a pool to earn LP tokens (auto-approves) - **Remove Liquidity**: Burn LP tokens to withdraw proportional share of both tokens - **Swap Tokens**: Swap one token for another with slippage protection (default 1%) - **Get Quote**: Preview expected output amount, price impact, and fee before swapping - **LP Balance**: Check LP token balance for any address - **Deploy WQFC** (v3.0): Deploy the Wrapped QFC (ERC-20 wrapper for native QFC) - **Wrap/Unwrap QFC** (v3.0): Convert native QFC ↔ WQFC for use in DEX pools - **Swap QFC for Token** (v3.0): Auto-wrap native QFC and swap in one call - **Swap Token for QFC** (v3.0): Swap token to WQFC and auto-unwrap to native QFC ### Token Launchpad (v3.0) - **Launch Token**: One-command token launch — deploy token + deploy WQFC pool + add initial liquidity. Returns token address, pool address, and LP details. ### NFT Marketplace (v3.0) - **Deploy Marketplace**: Deploy an on-chain NFT marketplace contract with configurable platform fee (default 2%, max 10%). Fee is deducted from sale price and sent to feeRecipient. - **List NFT**: List an NFT for sale with a price in QFC (auto-approves marketplace) - **Buy NFT**: Purchase a listed NFT by sending QFC (platform fee auto-deducted, excess auto-refunded) - **Cancel Listing**: Cancel an active listing (seller only) - **View Listings**: Get all active listings or filter by NFT collection - **Get Listing**: View details of a specific listing - **Get Fee Info**: Query current platform fee (basis points) and fee recipient - **Set Fee**: Update platform fee and/or recipient (marketplace owner only) ### Multi-Call (v3.0) - **Deploy Multicall3**: Deploy a batch-call contract for aggregating view calls - **Batch Calls**: Execute multiple contract reads in a single RPC request - **Batch Token Balances**: Query balanceOf for many tokens at once - **Batch Pool Reserves**: Query reserves for multiple AMM pools at once ### Event Subscriptions (v3.0) - **Watch Transfers**: Poll for new ERC-20 Transfer events on a token - **Watch Swaps**: Poll for new Swap events on an AMM pool - **Watch NFT Sales**: Poll for new Sold events on the marketplace - **Watch Blocks**: Poll for new blocks with transaction counts ### Discord Bot Integration (v2.5) - **Command Processor**: Framework-agnostic Discord bot command handler — no discord.js dependency - **Supported Commands**: `!help`, `!faucet`, `!balance`, `!portfolio`, `!tx`, `!block`, `!price`, `!info` - **Parse + Execute**: Parse raw messages into commands, execute them, and return Discord-formatted responses - **Custom Prefix**: Configurable command prefix (default `!`) - **Example Script**: See `scripts/discord-bot-example.mjs` for discord.js integration pattern ### Agent Registry (v3.2) - **Register Agent**: Register an AI agent on-chain with permissions, daily spending limit, max-per-tx limit, and initial QFC deposit - **Fund Agent**: Top up an agent's on-chain deposit with additional QFC - **Revoke Agent**: Deactivate a registered agent on the registry - **Get Agent**: Query agent info by ID (owner, address, permissions, deposit, daily spend, active status) - **List Agents**: List all agent IDs owned by an address - **Issue Session Key**: Authorize a session key address for an agent with a time-limited duration - **Rotate Session Key**: Atomically revoke an old session key and issue a new one - **Revoke Session Key**: Immediately deactivate a session key - **Get Session Key**: Query session key details (expiration, active status) - **Validate Session Key**: Check if a session key address is currently valid ### Safe Execution Mode (v3.3) - **Preflight Check**: Query on-chain agent state before submitting any transaction - Verifies agent exists and is active - Checks required permission is granted - Validates amount within per-tx limit (maxPerTx) - Validates amount within remaining daily budget (dailyLimit − spentToday) - Checks sufficient deposit balance - Optionally validates session key is active and not expired - **Human-Readable Deny Reasons**: Returns clear explanations for each failed check - **Warnings**: Alerts for near-limit conditions (>80% daily budget, >90% deposit used) - **Dry-Run Mode**: Run all checks without submitting the transaction (`dryRun: true`) - **Safe Fund Agent**: `safeFundAgent()` — preflight + fund in one call - **Generic Safe Execute**: `safeExecute()` — preflight + arbitrary callback, blocks if policy denied ### Agent Wallet Client (v3.4) - **AgentWalletClient**: High-level client wrapping QFCAgent + QFCInference for autonomous agent operations - **Session-Key Inference**: Submit inference tasks using a session key instead of the owner's long-lived private key — the on-chain registry validates the session key's permissions and spending limits - **Preflight-Guarded Submission**: Automatically runs preflight policy checks before every inference submission (permission, daily budget, deposit balance, session key validity) - **Full Agent Lifecycle**: register, fund, revoke, status, list — all through a single client - **Session Key Management**: issue, rotate, revoke, validate session keys - **Fee Estimation**: Estimate inference cost before submission - **Demo Scenarios**: Autonomous Trader, Content Generator, AI Oracle — see `scripts/demo-*.mjs` ### AI Inference (v2.1) - **List Models**: Approved AI models from the on-chain registry (name, version, GPU tier) - **Inference Stats**: Network-wide statistics (tasks completed, active miners, avg time, FLOPS, pass rate) - **Submit Task**: Submit a public inference task with model ID, input data, and max fee (requires wallet signature) - **Estimate Fee**: Get estimated cost for an inference task based on model and input size - **Query Task Status**: Check if a task is pending, assigned, completed, failed, or expired - **Wait for Result**: Poll until task reaches a terminal state (configurable timeout) - **Decode Result**: Parse the JSON envelope + base64 result payload from completed tasks ## Security Rules 1. **Never expose private keys or mnemonics** in conversation output. Store them securely and reference by wallet address only. 2. **Confirm transactions >100 QFC** — Always ask for explicit user confirmation before sending large amounts. 3. **Verify recipient addresses** — Validate address format (0x + 40 hex chars) before sending. 4. **Default to testnet** — Unless the user explicitly requests mainnet, all operations use testnet. 5. **Rate limit transactions** — Maximum 1000 QFC per day by default (configurable). ## Setup Run `{baseDir}/scripts/setup.sh` before first use. This installs dependencies and compiles TypeScript modules to `{baseDir}/dist/`. ## Configuration ### Network Setup ``` Testnet RPC: https://rpc.testnet.qfc.network (chain ID: 9000) Mainnet RPC: https://rpc.qfc.network (chain ID: 9001) ``` ### Environment Variables - `QFC_NETWORK` — "testnet" (default) or "mainnet" - `QFC_RPC_URL` — Override RPC endpoint ## Modules | Module | Class | Description | |--------|-------|-------------| | `contract` | `QFCContract` | Read/write/deploy smart contracts | | `token` | `QFCToken` | ERC-20 token operations + airdrop contract | | `nft` | `QFCNFT` | ERC-721 NFT operations | | `swap` | `QFCSwap` | AMM token swap / DEX + WQFC wrapper | | `marketplace` | `QFCMarketplace` | NFT marketplace (list/buy/sell) | | `multicall` | `QFCMulticall` | Batch contract reads in single RPC | | `events` | `QFCEvents` | Event subscriptions via polling | | `agent` | `QFCAgent` | AI agent registry — register, fund, revoke, session keys | | `agent-wallet` | `AgentWalletClient` | High-level agent wallet — session-key inference, lifecycle, safe execution | | `inference` | `QFCInference` | AI inference task submission & results | | `provider` | — | Shared provider creation & RPC helper | All modules are compiled to `{baseDir}/dist/`. | `wallet` | `QFCWallet` | Wallet create/import/balance/send/sign/save/load | | `keystore` | `QFCKeystore` | Encrypted wallet persistence (scrypt keystore) | | `security` | `SecurityPolicy` | Pre-transaction safety checks | | `faucet` | `QFCFaucet` | Testnet token requests | | `chain` | `QFCChain` | Block, transaction, receipt queries | | `network` | `QFCNetwork` | Node info & network status | | `staking` | `QFCStaking` | Validator & staking info | | `epoch` | `QFCEpoch` | Epoch & finality info | | `discord` | `QFCDiscordBot` | Discord bot command processor (no discord.js dependency) | ## Usage Examples ### Create a wallet, save it, and get test tokens ``` Create a new QFC wallet on testnet, save it with password "mypass", then request 10 QFC from the faucet ``` ### Load a saved wallet ``` List my saved QFC wallets and load the first one with password "mypass" ``` ### Check network status ``` What's the current QFC testnet status? Show me node info and latest block. ``` ### Query validators ``` List all QFC validators and their contribution scores ``` ### Check transaction ``` Look up transaction 0xabc... on QFC testnet — show me the receipt ``` ### ERC-20 Tokens ``` Create a new token called "My Token" with symbol MTK and 1 million supply on QFC testnet ``` ``` Deploy an ERC-20 token named "QFC Rewards" (symbol: QREW) with 10 million supply ``` ``` Create a mintable token called "Game Gold" with symbol GOLD and 0 initial supply ``` ``` Mint 5000 GOLD tokens to address 0x1234... ``` ``` Burn 100 of my GOLD tokens ``` ``` What is the token at 0xabcd...? Show me name, symbol, and total supply. ``` ``` Check my token balance for 0xabcd... token ``` ``` Transfer 50 tokens (0xabcd...) to 0x5678... ``` ### Token Portfolio & History ``` Show me all token balances for address 0xfe913E97238B28abac7a55173f5878fD29147210 ``` ``` What tokens does my wallet hold on QFC testnet? ``` ``` Show transfer history for token 0x603f0c43966f68dfb0737314cde8c4a46a0cc1f9 ``` ``` Show my recent transfers for the XHT token ``` ### Batch Operations ``` Airdrop 100 XHT tokens to these addresses: 0x1111..., 0x2222..., 0x3333... ``` ``` Send 10 QFC to each of these addresses: 0xaaaa..., 0xbbbb... ``` ### Smart Airdrop (single-tx) ``` Deploy an airdrop contract on QFC testnet ``` ``` Airdrop 100 XHT to 0x1111..., 200 XHT to 0x2222..., and 50 XHT to 0x3333... using airdrop contract 0xabcd... ``` ``` Airdrop 500 GOLD tokens equally to these 10 addresses using the airdrop contract ``` ### NFTs ``` Deploy an NFT collection called "QFC Punks" with symbol QPUNK ``` ``` Mint an NFT to 0x1234... with metadata URI https://api.example.com/metadata/1 ``` ``` Who owns token #0 in NFT contract 0xabcd...? ``` ``` Get the metadata URI for token #3 in the NFT collection at 0xabcd... ``` ``` Transfer NFT #2 from my wallet to 0x5678... on contract 0xabcd... ``` ### Token Swap / DEX ``` Create a swap pool for tokens 0xAAA... and 0xBBB... on QFC testnet ``` ``` Add liquidity: 1000 of token A and 500 of token B to pool 0xPOOL... ``` ``` Swap 100 of token 0xAAA... for token B on pool 0xPOOL... ``` ``` Get a quote: how much token B would I get for 50 of token A on pool 0xPOOL...? ``` ``` Show pool info for 0xPOOL... — reserves, price, and LP supply ``` ``` Remove all my liquidity from pool 0xPOOL... ``` ### WQFC (Wrapped QFC) ``` Deploy WQFC contract on QFC testnet ``` ``` Wrap 100 QFC into WQFC using contract 0xWQFC... ``` ``` Swap 50 native QFC for token 0xAAA... via WQFC pool 0xPOOL... ``` ### Token Launchpad ``` Launch a new token called "Moon Coin" (MOON) with 1M supply, add 100k tokens and 500 QFC as initial liquidity ``` ### NFT Marketplace ``` Deploy an NFT marketplace on QFC testnet with 2% platform fee ``` ``` Deploy a marketplace with 5% fee sent to 0xFEE... ``` ``` List NFT #3 from collection 0xNFT... for 10 QFC on marketplace 0xMKT... ``` ``` Buy listing #0 on marketplace 0xMKT... ``` ``` Show all active NFT listings on marketplace 0xMKT... ``` ``` Check the platform fee on marketplace 0xMKT... ``` ### Multi-Call ``` Deploy a Multicall3 contract on QFC testnet ``` ``` Batch check balances of 5 tokens for my wallet using multicall 0xMC... ``` ### Smart Contracts ``` Is 0x1234...abcd a contract address on QFC testnet? ``` ``` Read the name() and symbol() of ERC-20 contract 0xabcd... ``` ``` Call the balanceOf method on contract 0xabcd... for address 0x1234... ``` ``` Verify the source code for contract 0xabcd... on the QFC explorer ``` ### AI Inference ``` What AI models are available on QFC? ``` ``` How much does it cost to run a text embedding on QFC? ``` ``` Submit an inference task using qfc-embed-small with input "Hello world" and max fee 0.1 QFC ``` ``` Check the status of inference task 0xdef456... ``` ``` Show me QFC inference network statistics ``` ### Agent Registry ``` Register an AI agent called "my-agent" with Transfer permission, 100 QFC daily limit, 10 QFC max per tx, and 5 QFC deposit ``` ``` Fund agent "my-agent" with 50 QFC ``` ``` Issue a session key for agent "my-agent" to address 0x1234... valid for 1 hour ``` ``` Rotate the session key for agent "my-agent" from 0xOLD... to 0xNEW... with 2 hour validity ``` ``` Revoke the session key at 0x1234... for agent "my-agent" ``` ``` Is session key 0x1234... still valid? ``` ``` Show info for agent "my-agent" ``` ``` List all agents owned by 0xfe913E97238B28abac7a55173f5878fD29147210 ``` ### Safe Execution Mode ``` Check if agent "my-agent" can spend 50 QFC (dry run, don't submit) ``` ``` Safely fund agent "my-agent" with 20 QFC — check policy first, then submit if allowed ``` ``` Run preflight check for agent "my-agent" with Transfer permission and 5 QFC amount ``` ### Agent Wallet Client ``` Create an autonomous trader agent: register "trader-1" with InferenceSubmit and Transfer permissions, 100 QFC daily limit, issue a session key, then submit a sentiment analysis inference using only the session key ``` ``` Set up a content generator agent with InferenceSubmit-only permission and a 7-day session key ``` ``` Run an AI oracle: register agent, estimate inference fee, run preflight check, then submit a query — all using the session key ``` ``` Submit an inference task as agent "my-agent" using session key — model qfc-embed-small, input "Hello world" ``` ### Discord Bot ``` Set up a QFC Discord bot using scripts/discord-bot-example.mjs as a template ``` ``` Integrate QFCDiscordBot into my existing Discord bot to handle !balance and !faucet commands ``` ## Error Handling | Error | Meaning | Action | |-------|---------|--------| | INSUFFICIENT_FUNDS | Not enough QFC | Check balance, fund wallet | | INVALID_ADDRESS | Bad recipient format | Verify 0x + 40 hex chars | | NETWORK_ERROR | RPC connection failed | Check RPC URL, retry | | NONCE_TOO_LOW | Transaction already sent | Wait for confirmation, retry | | FAUCET_TESTNET_ONLY | Faucet used on mainnet | Switch to testnet | | CALL_EXCEPTION | Contract call reverted | Check method name, args, and ABI | | UNPREDICTABLE_GAS | Gas estimation failed | Contract may revert, check args | | MODEL_NOT_FOUND | Unknown model ID | List models with getModels() | | TASK_EXPIRED | Inference task timed out | Resubmit with higher fee | | FEE_TOO_LOW | Max fee below minimum | Use estimateFee() to get base price | | AGENT_NOT_FOUND | Unknown agent ID | Check agentId, list agents with listAgents() | | SESSION_KEY_EXPIRED | Session key past expiry | Issue or rotate to a new session key | | PREFLIGHT_DENIED | Policy check failed | Inspect preflight.reasons[] for details | | DAILY_LIMIT_EXCEEDED | Amount exceeds remaining daily budget | Wait for daily reset or increase limit | | PER_TX_LIMIT_EXCEEDED | Amount exceeds per-transaction cap | Split into smaller transactions | | DEPOSIT_INSUFFICIENT | Agent deposit too low | Fund agent with fundAgent() | | PERMISSION_DENIED | Agent lacks required permission | Re-register with correct permissions |