confidential-agentic-payment-stack

intent

use this skill when your agent needs to make private, encrypted payments on ethereum using fully homomorphic encryption (fhEVM), manage escrow jobs for agentic commerce, register identity as an nft, submit proof-linked reputation feedback, or delegate encrypted balance viewing to other agents. all payment amounts stay encrypted on-chain - only payer and payee see them. runs on ethereum sepolia (default) or mainnet with zama's fhEVM infrastructure. supports three wallet modes: local private key (dev), dfns mpc (unattended agents), and ledger hardware wallet (supervised). pick this skill for confidential agent-to-agent payments, private service payments via x402 http payment flow, or escrow-based agentic commerce workflows.

inputs

required environment variables:

• RPC_URL: ethereum rpc endpoint (defaults to sepolia public node if not set). must resolve to either sepolia (chain id 11155111) or mainnet (chain id 1).
• USER_PRIVATE_KEY (wallet mode: user) OR DFNS_WALLET_ID + DFNS_AUTH_TOKEN + DFNS_CREDENTIAL_ID + DFNS_CREDENTIAL_PRIVATE_KEY or DFNS_PRIVATE_KEY_PATH (wallet mode: dfns) OR LEDGER_BRIDGE_URL + LEDGER_BRIDGE_TOKEN (wallet mode: ledger-bridge). at least one wallet source required.

optional environment variables:

• WALLET_MODE: explicitly set to user, dfns, or ledger-bridge. if omitted, auto-detects in order: dfns > user.
• CHAIN: mainnet or sepolia. auto-detected from rpc_url chain id if not provided.
• CUSDC_ADDRESS: override encrypted usdc (erc-7984) token address. defaults to sepolia 0x7c5BF43B851c1dff1a4feE8dB225b87f2C223639 or mainnet equivalent.
• VERIFIER_ADDRESS: override x402 payment verifier contract address.
• ESCROW_ADDRESS: override agenticcommerceprotocol (erc-8183) contract address.
• IDENTITY_ADDRESS: override agentidentityregistry (erc-721) contract address.
• REPUTATION_ADDRESS: override agentreputationregistry contract address.

external connections:

• zama fhEVM on ethereum sepolia or mainnet (implicit via rpc_url).
• dfns mpc wallet service (optional, requires oauth token and credential setup).
• ledger bridge service (optional, requires hosted bridge url and token).

node binaries required:

• node (v16+): required to run all commands.

procedure

token operations

step 1: wrap usdc into encrypted cusdc

• input: amount (decimal string or number, e.g. "10" for 10 usdc), wallet credentials from env.
• run: run wrap --amount 10
• output: json object with tx hash, receipt status, new encrypted balance.
• edge case: if user has insufficient usdc balance, tx reverts on-chain. skill returns { "ok": false, "error": "insufficient usdc balance" }.
• edge case: if wrapped amount exceeds token approval, tx fails. user must approve cusdc contract first via approve(cusdc_address, amount).

step 2: check encrypted balance (optional decrypt)

• input: optional --decrypt true flag (decryption requires fhEVM key material), optional --of 0xAddress to check another address (only works if delegation granted).
• run: run balance or run balance --decrypt true
• output: json with { "usdc": "...", "cusdc": "..." } balances. if --decrypt true, decryption proof fetched from kms or local cache.
• edge case: if decryption proof unavailable, returns encrypted balance only. skill does not fail - returns partial data.

step 3: send encrypted cusdc payment

• input: --to 0xRecipient (eth address), --amount (decimal string).
• run: run pay --to 0xRecipient --amount 1
• output: json with tx hash, receipt, verifier relay response.
• edge case: if recipient address is invalid (checksum mismatch, not eoa), tx fails with "invalid recipient".
• edge case: if encrypted balance < amount, tx reverts with "insufficient cusdc".
• edge case: if verifier relay service is down (network timeout >10s), skill retries once then returns { "ok": false, "error": "verifier relay unavailable" }.

step 4: initiate unwrap (cusdc to usdc)

• input: --amount (decimal string).
• run: run unwrap --amount 5
• output: json with tx hash, kms request handle (or legacy requestId + cleartextAmount + proof).
• note: unwrap is 2-step. step 1 submits encrypted unwrap request. step 2 finalizes via decryption proof.
• edge case: if kms service is unreachable, returns legacy proof format (requires manual proof generation).

step 5: finalize unwrap (complete decryption proof)

• input: --handle <handle> (recommended, auto-fetches proof) OR legacy args --requestId --cleartextAmount --proof.
• run: run finalize-unwrap --handle <handle> or run finalize-unwrap --requestId 123 --cleartextAmount 5 --proof 0x...
• output: json with final tx hash, unwrapped usdc balance.
• edge case: if proof has expired (>24 hours old), tx reverts with "proof expired". user must restart unwrap.
• edge case: if cleartextAmount does not match on-chain encrypted amount, proof validation fails.

escrow operations (agentic commerce protocol erc-8183)

step 6: create escrow job

• input: --provider 0xProviderAddr, --evaluator 0xEvaluatorAddr, --expiry <unix timestamp>, --description "job details". optional: --hook 0xHookContract.
• run: run create-job --provider 0x... --evaluator 0x... --expiry 1704067200 --description "code review"
• output: json with jobId (uint256), tx hash.
• edge case: if expiry timestamp is in past, tx reverts immediately.
• edge case: if provider == evaluator, tx may succeed but creates ambiguous state - skill allows this (no validation).

step 7: fund job with encrypted budget

• input: --jobId (uint256), --amount (decimal string). requires wrapped cusdc balance.
• run: run fund-job --jobId 1 --amount 50
• output: json with tx hashes for all 3 steps: encrypt, approve, fund.
• procedure: encrypts amount into escrow contract, approves cusdc spending, transfers encrypted cusdc to job.
• edge case: if any of 3 txs fail (e.g., out of gas), skill returns partial status { "ok": false, "failedStep": 2, "error": "out of gas" }.
• edge case: if job already funded, second fund tx reverts with "job already has budget".

step 8: complete or reject job

• input: --jobId, --action (approve or reject). optional: --reason "why".
• run: run complete-job --jobId 1 --action approve --reason "excellent work"
• output: json with tx hash, new job status.
• edge case: if caller is not evaluator, tx reverts with "unauthorized".
• edge case: if job is already completed, reverts with "job already settled".

identity & reputation operations

step 9: register agent as erc-721 identity nft

• input: --uri (ipfs or http uri pointing to agent metadata json).
• run: run register-agent --uri ipfs://QmXxxx...
• output: json with tokenId (nft id), tx hash, on-chain uri.
• edge case: if uri is unreachable (404 on http), operation proceeds - no validation on uri availability.
• edge case: if agent already registered (caller has existing tokenId), tx may revert or mint duplicate depending on contract logic.

step 10: submit proof-linked reputation feedback

• input: --agentId (nft token id), --score (0-100 integer), --nonce (to prevent replay). optional: --tag1 --tag2 (categorical tags), --endpoint (callback url), --feedbackURI (ipfs/http), --feedbackHash (keccak256).
• run: run give-feedback --agentId 5 --score 95 --nonce 1 --tag1 code-quality --tag2 responsiveness
• output: json with tx hash, proof id.
• edge case: if score out of range (not 0-100), returns { "ok": false, "error": "score must be 0-100" } without submitting tx.
• edge case: if nonce already used (replay), tx reverts with "nonce already consumed".

delegation operations (fhe viewing keys)

step 11: grant viewing permission to delegate

• input: --delegate 0xDelegateAddr. optional: --hours <number> (time limit), --permanent true (override hours), --contract <address> (restrict to single contract, default all).
• run: