Back to Details

veilpay

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

VeilPay Agent Skill

VeilPay Agent技能

VeilPay enables fully private payments on Solana mainnet. The sender and recipient are never linked on-chain — a Groth16 ZK proof breaks any cryptographic connection between deposit and withdrawal.
VeilPay支持在Solana主网上进行完全私密的支付。发送方与接收方在链上永远不会被关联——Groth16 ZK证明会打破存款与取款之间的任何加密关联。

⚠️ Full Runtime Preparation — Run Before Any Script

⚠️ 完整运行时准备 —— 在执行任何脚本前运行

Never assume the environment is ready. ZK-SNARK skills have complex peer dependencies, binary requirements, and browser-vs-Node.js conflicts that must be resolved before first execution.
切勿假设环境已准备就绪。ZK-SNARK技能存在复杂的依赖项、二进制要求以及浏览器与Node.js之间的冲突，必须在首次执行前解决这些问题。

Phase 1: Dependency Installation

阶段1：依赖安装

bash
cd <skill-directory>
rm -rf node_modules          # clean slate avoids partial-install conflicts
npm install --legacy-peer-deps
--legacy-peer-deps
is required — the Umbra SDK and the ZK prover have conflicting peer dependency requirements. Standard 
npm install
fails.
bs58
is pinned to 
4.0.1
— do not upgrade it. After v4, bs58 changed its export structure. Higher versions silently break scripts with 
TypeError: bs58.encode is not a function
.
bash
cd <skill-directory>
rm -rf node_modules          # 清理环境可避免部分安装导致的冲突
npm install --legacy-peer-deps
--legacy-peer-deps
是必需的——Umbra SDK与ZK证明器存在冲突的对等依赖要求。标准的
npm install
会执行失败。
**
bs58
已固定为
4.0.1
版本——请勿升级。**在v4版本之后，bs58更改了其导出结构。更高版本会导致脚本静默崩溃，抛出
TypeError: bs58.encode is not a function
错误。

Phase 2: Smoke Test

阶段2：冒烟测试

Verify critical runtime dependencies before running any command:
bash
node -e "require('snarkjs'); require('bs58'); console.log('Runtime Ready')"
在运行任何命令前，验证关键的运行时依赖：
bash
node -e "require('snarkjs'); require('bs58'); console.log('Runtime Ready')"

Phase 3: Reliability & Troubleshooting

阶段3：可靠性与故障排查

  1. Authorization Format: VeilPay servers require "Shielded UTXO" (Receiver-Claimable) payments. 
    pay-invoice.cjs
    generates a 3-part header: 
    X-402-Payment: x402 <proofAccountSig>:<utxoSig>:<invoiceId>
    .
  2. SDK Response Mapping: The script correctly maps 
    createProofAccountSignature
    and 
    createUtxoSignature
    from the Umbra SDK to the authorization header.
  3. Indexer Lag: Shielded transactions are not immediately visible to the Umbra indexer. 
    pay-invoice.cjs
    includes a mandatory 15-second sleep after broadcast to ensure the server can verify the payment on-chain.
  4. Mainnet-only: All scripts default to Solana mainnet. Use 
    --network devnet
    only for development — devnet SOL and token accounts are not real.
  1. 授权格式：VeilPay服务器要求使用“Shielded UTXO”（接收方可认领）支付。
    pay-invoice.cjs
    会生成一个三部分的请求头：
    X-402-Payment: x402 <proofAccountSig>:<utxoSig>:<invoiceId>
    。
  2. SDK响应映射：脚本已正确将Umbra SDK中的
    createProofAccountSignature
    和
    createUtxoSignature
    映射到授权请求头。
  3. 索引器延迟：私密交易不会立即在Umbra索引器中显示。
    pay-invoice.cjs
    包含一个强制的15秒休眠，在交易广播后执行，以确保服务器能在链上验证支付。
  4. 仅支持主网：所有脚本默认使用Solana主网。仅在开发时使用
    --network devnet
    ——devnet上的SOL和代币账户均为测试用，不具备实际价值。

Command Reference

命令参考

Create Agent Wallet

创建Agent钱包

Generates a new Solana keypair and stores it at 
~/.veilpay/wallet.json
.
bash
node scripts/wallet.cjs create
生成一个新的Solana密钥对，并存储在
~/.veilpay/wallet.json
路径下。
bash
node scripts/wallet.cjs create

Perform Shielded x402 Payment

执行Shielded x402支付

Fulfills an x402 invoice by depositing into the Umbra Shielded Pool.
Supports SOL, USDC, USDT, UMBRA, and CASH.
Note: Includes a mandatory 15-second wait for indexer sync.
⚠️ STRICT POLICY FOR x402 PAYMENTS:
  1. ONLY use 
    scripts/pay-invoice.cjs
    . NEVER use 
    scripts/transfer.cjs
    (confidential transfer) for x402 invoices.
  2. DOUBLE BILLING PROTECTION: The script caches successful payments in 
    ~/.veilpay/payments.json
    . If you provide the same 
    invoiceId
    , it will return the cached header without billing you again.
  3. ERROR HANDLING: If a payment script fails with a technical error (RPC timeout, network issue), DO NOT RETRY AUTOMATICALLY.
    • First, check 
      ~/.veilpay/payments.json
      to see if a record was created.
    • If no record exists but you suspect funds were moved, ASK THE USER TO CONFIRM before retrying.
    • If the server rejects a proof that was already paid (and is in the ledger), DO NOT RE-PAY. Share the transaction IDs from the ledger with the user.
bash
undefined
通过向Umbra隐私池存款来完成x402账单支付。 支持SOL、USDC、USDT、UMBRA和CASH。 **注意：**包含强制的15秒等待，用于索引器同步。
⚠️ x402支付严格规则：
  1. 仅可使用
    scripts/pay-invoice.cjs
    。切勿使用
    scripts/transfer.cjs
    （私密转账）来支付x402账单。
  2. **重复支付防护：**脚本会将成功的支付记录缓存到
    ~/.veilpay/payments.json
    中。如果提供相同的
    invoiceId
    ，脚本会返回缓存的请求头，不会再次扣款。
  3. **错误处理：**如果支付脚本因技术错误（RPC超时、网络问题）失败，请勿自动重试。
    • 首先，检查
      ~/.veilpay/payments.json
      是否已创建记录。
    • 如果没有记录但怀疑资金已转出，请先让用户确认再重试。
    • 如果服务器拒绝了一个已支付的证明（且记录在账本中），请勿重复支付。将账本中的交易ID分享给用户即可。
bash
undefined

invoice_json: The "invoice" object from a 402 response

invoice_json：来自402响应的"invoice"对象

node scripts/pay-invoice.cjs '<invoice_json>'
undefined
node scripts/pay-invoice.cjs '<invoice_json>'
undefined

Create Private Payment Link

创建私密支付链接

Generates a shareable ZK-shielded payment URL. Supports SOL, USDC, USDT, UMBRA, CASH.
bash
node scripts/create-link.cjs --amount 0.5 --token SOL
node scripts/create-link.cjs --amount 1.00 --token USDC
生成一个可分享的ZK私密支付URL。支持SOL、USDC、USDT、UMBRA、CASH。
bash
node scripts/create-link.cjs --amount 0.5 --token SOL
node scripts/create-link.cjs --amount 1.00 --token USDC

Claim Private Payment Link

认领私密支付链接

Autonomously claims funds from a link into the agent's wallet.
bash
node scripts/claim-link.cjs --link "<url>"
自动将链接中的资金认领至Agent钱包。
bash
node scripts/claim-link.cjs --link "<url>"

Withdraw Encrypted Balance

提取加密余额

Moves funds from the agent's shielded vault to its public wallet.
bash
undefined
将资金从Agent的隐私金库转移至其公开钱包。
bash
undefined

Withdraw specific amount

提取指定金额

node scripts/withdraw.cjs --token SOL --amount 0.1
node scripts/withdraw.cjs --token SOL --amount 0.1

Withdraw full balance

提取全部余额

node scripts/withdraw.cjs --token SOL --all
undefined
node scripts/withdraw.cjs --token SOL --all
undefined

Query Premium Data (x402)

查询高级数据（x402）

Fetches system-wide data from the VeilPay API by fulfilling a shielded payment challenge.
bash
undefined
通过完成私密支付验证，从VeilPay API获取系统级数据。
bash
undefined

Query links table

查询链接表

node scripts/premium.cjs --table links
node scripts/premium.cjs --table links

Query merchant requests

查询商家请求

node scripts/premium.cjs --table merchant-requests
node scripts/premium.cjs --table merchant-requests

Query payment history

查询支付历史

node scripts/premium.cjs --table payments
undefined
node scripts/premium.cjs --table payments
undefined

Flawless Agent Checklist

完美Agent检查清单

□ Is snarkjs installed?             node -e "require('snarkjs')"
□ Is bs58 version 4.0.1?            node -e "console.log(require('bs58/package.json').version)"
□ Is wallet.json in base64?         node scripts/wallet.cjs show
□ Is SOL balance ≥ 0.05?            node scripts/wallet.cjs balance
□ Is indexer sync wait active?      (Default in pay-invoice.cjs)
□ Correct network (mainnet)?        Scripts default to mainnet; use --network devnet only for dev
□ 是否已安装snarkjs？             node -e "require('snarkjs')"
□ bs58版本是否为4.0.1？            node -e "console.log(require('bs58/package.json').version)"
□ wallet.json是否为base64格式？         node scripts/wallet.cjs show
□ SOL余额是否≥0.05？            node scripts/wallet.cjs balance
□ 是否启用索引器同步等待？      （pay-invoice.cjs中默认启用）
□ 网络是否正确（主网）？        脚本默认使用主网；仅在开发时使用--network devnet