Portkey Official Ca Agent Skills

---
name: portkey-ca-agent-skills
description: Portkey Contract Account wallet registration, authentication, verifier codes, recovery, guardians, CA identity, assets, transfers, approval proofs, chain readiness, contract calls, and encrypted keystore workflows on AElf. Use when CA hash, guardian, registration, recovery, or manager-forward behavior is required; use the EOA skill for mnemonic or direct private-key wallet lifecycle workflows.
---

# Portkey CA Agent Skill

## Capabilities
- Auth operations: verifier, email code, register, recover, status
- Query operations: account, guardian, assets, chain config, transfer preflight
- Tx operations: transfer, contract call, approvals, keystore workflows
- Shared wallet context: auto-set active CA profile for cross-skill signer resolution
- Supports SDK, CLI, MCP, OpenClaw, and IronClaw integration from one codebase.

## Online configuration
- Portkey CA currently supports `mainnet` only; the testnet deployment is decommissioned.
- Public services: AA API `https://aa-portkey.portkey.finance`, EOA asset fallback `https://eoa-portkey.portkey.finance`, and GraphQL `https://indexer-api.aefinder.io/api/app/graphql/portkey`.
- Chain RPC, CA contract, and default MultiToken addresses are returned by the Portkey chain-info API as `endPoint`, `caContractAddress`, and `defaultToken.address`; they are intentionally not duplicated as static deployment constants.
- Public account, chain, and asset reads need no local private key. Registration, recovery, and writes use an encrypted CA keystore or explicit signer variables listed in `.env.example`.
- `PORTKEY_*` overrides, AA-to-EOA fallback controls, and the shared wallet-context path are all included in the packaged `.env.example`.

## Safe usage rules
- Never print private keys, mnemonics, or tokens in channel outputs.
- For write operations, require explicit user confirmation and validate parameters before sending transactions.
- Prefer read-only preflight checks first when available.
- Route `Get*` and other read-only contract methods through `view-call` / `callContractViewMethod`, not `forward-call`.
- Route `forward-call` / `managerForwardCall` only to state-changing methods.
- For `Empty`-input view methods such as `GetConfig`, omit params entirely so the runtime performs `.call()` with no arguments.
- Treat backend `3002 / Guardian not exist.` as an unregistered account and route to `register`.
- Before `transfer` / `cross-chain-transfer`, run `transfer-preflight` to decide whether the path is:
  - direct transfer
  - one-time guardian approval
  - transfer-limit modification
  - wallet security upgrade / guardian sync
- Recommended stable write path is:
  - `recover-and-save`
  - poll `manager-sync-status` on the target chain
  - collect fresh `transferApprove` proofs
  - submit `transfer` / `cross-chain-transfer` with `loginEmail + password`
- Older AA/CA accounts recovered on `AELF` and then written on `tDVV` are a high-risk sync scenario; always check `manager-sync-status` before the first `forward-call` / claim / transfer on `tDVV`.
- `transfer-preflight` reports both the transferred asset balance and the chain default fee-token balance (`feeSymbol` / `feeBalance` / `feeDecimals`) when deciding one-time approval eligibility.
- `send-code` / `verify-code` support `transferApprove` for one-time transfer approval proof collection.
- `transfer`, `cross-chain-transfer`, and transfer-related `forward-call` accept optional `guardiansApproved`.
- `transfer`, `cross-chain-transfer`, and generic `forward-call` now block early when the current manager has not yet synced to the target chain.
- CLI write commands can resolve signer directly from CA keystore options (`loginEmail` / `password` / `keystoreFile`) instead of relying on a previous in-memory `unlock`.
- `wallet-status` returns `recommendedAction` / `userHint` when a local keystore exists but is still locked. `recommendedAction=unlock` is the next machine step; `userHint` explains how to verify the selected `loginEmail` / `keystoreFile` first and then route to `recover-and-save` only if the password was truly forgotten.
- `VirtualTransactionCreated` is forwarded-write evidence only; it is not a decoded view payload and not a standalone proof that a read-only contract query succeeded.

## Command recipes
- Start MCP server: `bun run mcp`
- Run CLI entry: `bun run portkey_query_skill.ts chain-info`
- Run transfer preflight: `bun run portkey_query_skill.ts transfer-preflight --ca-hash <hash> --ca-address <addr> --chain-id tDVV --symbol ELF --amount 100000000`
- Run manager sync status: `bun run portkey_query_skill.ts manager-sync-status --ca-hash <hash> --chain-id tDVV --manager-address <addr-from-recover-and-save-or-selected-signer>`
- Read active wallet context: `portkey_get_active_wallet`
- Set active wallet context: `portkey_set_active_wallet`
- Install into IronClaw: `bun run setup ironclaw`
- Generate OpenClaw config: `bun run build:openclaw`
- Verify OpenClaw config: `bun run build:openclaw:check`
- Run CI coverage gate: `bun run test:coverage:ci`

## Distribution / Activation
- GitHub repo/tree URLs are discovery-only for hosts and agents.
- Preferred IronClaw activation from npm: `bunx -p @portkey/ca-agent-skills portkey-ca-setup ironclaw`
- Preferred OpenClaw activation from npm when managed install is unavailable: `bunx -p @portkey/ca-agent-skills portkey-ca-setup openclaw`
- Local repo checkout is for development and smoke tests only.
- Migration note: `portkey-setup` was removed in `2.0.0`; use `portkey-ca-setup` for npm-based activation.

## Limits / Non-goals
- This skill focuses on domain operations and adapters; it is not a full wallet custody system.
- Do not hardcode environment secrets in source code or docs.
- Avoid bypassing validation for external service calls.
- Do not use this skill for EOA mnemonic/private-key wallet lifecycle flows.