pharos-skill-engine

Pharos Chain Skills

Developer toolkit for the Pharos blockchain. Perform on-chain queries, send transactions, deploy and verify contracts via Foundry (cast / forge) CLI commands.

Prerequisites

1. Install Foundry (MANDATORY — MUST be done before ANY other action):
   • The Agent MUST first run which cast to check if Foundry is installed.
   • If cast is NOT found, the Agent MUST immediately run the following installation commands. Do NOT skip installation. Do NOT fall back to curl/JSON-RPC as a workaround. Do NOT proceed with any other task until Foundry is installed.

     curl -L https://foundry.paradigm.xyz | bash
     

     Then run:

     source ~/.zshenv && foundryup
     

     Then verify with:

     cast --version
     

   • If installation fails, inform the user and STOP. Do not attempt alternative approaches.
2. Configure Private Key: Write operations (sending transactions, deploying contracts) require a private key, provided via one of the following:
   • Command argument: --private-key <your_private_key>
   • Environment variable: $PRIVATE_KEY

Network Configuration

Network information is stored in assets/networks.json, containing both the Atlantic testnet and mainnet chains.

• Default Network: Atlantic testnet (atlantic-testnet). Used when the user does not specify a network.
• Switching Networks: When the user specifies mainnet, read the corresponding entry's rpcUrl from assets/networks.json.
• Usage: Read assets/networks.json and fill the target network's rpcUrl into each command's --rpc-url parameter. Contract verification also requires chainId and explorerApiUrl.

# Example: reading network configuration
RPC_URL=$(jq -r '.networks[] | select(.name=="atlantic-testnet") | .rpcUrl' assets/networks.json)

Capability Index

Load the corresponding reference file based on user needs to get full command templates.

User Need	Capability	Detailed Instructions
View wallet portfolio / asset overview	cast balance + cast call (batch query all known tokens)	→ references/query.md#address-portfolio-wallet-asset-overview
Query address balance	cast balance / cast call	→ references/query.md#balance-query
Query transaction status	cast tx / cast receipt	→ references/query.md#transaction-query
Call contract read-only method	cast call	→ references/query.md#contract-read-only-call
Send transaction (native transfer)	cast send	→ references/transaction.md#native-token-transfer
Call contract write method	cast send	→ references/transaction.md#contract-write-call
Estimate Gas	cast estimate	→ references/transaction.md#gas-estimation
Deploy contract	forge script (auto-generate deploy script)	→ references/contract.md#deploy-contract-forge-script
Verify contract	forge verify-contract	→ references/contract.md#verify-contract
One-click ERC20 deploy	forge script + built-in ERC20 template	→ references/contract.md#erc20-one-click-deploy-built-in-template
Batch transfer / Airdrop	forge script (auto-generate airdrop script, supports 6000+ address batched airdrop, CSV file input, three-tier auto mode: ≤10 simple mode / 11-200 single batch / >200 multi-batch, hardened Distributor contract)	→ references/transaction.md#batch-transfer--airdrop
Generate contract interaction scripts (read/write methods, JS/TS/Python)	Script_Generator (Agent auto-generates)	→ references/script-gen.md

General Error Handling

Before executing commands, the Agent should perform pre-checks; when commands fail, provide user-friendly error messages based on stderr output.

Error Scenario	CLI Error Signature	Handling
Invalid address format	invalid address	Prompt to check address format (0x + 40 hex characters)
Transaction hash not found	transaction not found	Prompt that transaction was not found, suggest checking the hash
No contract code at address	Empty return value	Prompt that target address has no contract code
Call revert	execution reverted	Extract and display revert reason
Private key not configured	Command missing --private-key	Prompt user to configure private key (argument or environment variable)
Insufficient balance	insufficient funds	Prompt insufficient balance, show current balance
Nonce conflict	nonce too low	Suggest waiting or manually specifying nonce
Missing network config	assets/networks.json unreadable	Prompt that config file is missing or has invalid format
Unsupported network	Network name not in config list	Prompt that only atlantic-testnet and mainnet are supported

See the corresponding reference files for detailed error handling tables for each operation.

Security Reminders

• Private Key Protection: Never expose private keys in logs, chat history, or version control. Store the private key in the $PRIVATE_KEY environment variable and reference it explicitly in commands via --private-key $PRIVATE_KEY. Note: forge / cast do not automatically read environment variables; they must be explicitly passed as command arguments.
• Network Confirmation: Before executing write operations, the Agent must clearly inform the user of the target network (testnet or mainnet). Mainnet operations require a prominent warning and user re-confirmation to prevent accidental operations.

Write Operation Pre-checks (Required for All Write Operations)

For all operations requiring a private key (transfers, contract calls, deployments, airdrops, etc.), the Agent must automatically complete the following checks before execution:

1. Private Key Check

Automatically detect whether the $PRIVATE_KEY environment variable is set:

# Check if environment variable exists (without outputting the private key)
[ -n "$PRIVATE_KEY" ] && echo "PRIVATE_KEY is set" || echo "PRIVATE_KEY is not set"

• If not set: Prompt the user to configure via export PRIVATE_KEY=<your_private_key>, do not proceed
• If set: Continue to next step

2. Derive Public Address and Confirm with User

Derive the corresponding public address from the private key via cast wallet address:

cast wallet address --private-key $PRIVATE_KEY

3. Network Confirmation (Must Clearly Inform User)

The Agent must clearly inform the user of the target network before executing any write operation. Read the target network info from assets/networks.json and display the network name and type to the user.

• If the user did not specify a network, use the default network (atlantic-testnet) and clearly inform the user: Current operation targets the Atlantic testnet
• If the user specified mainnet, prominently warn the user: Current operation targets mainnet, please confirm to proceed

Combine the information from steps 2 and 3 for user confirmation. Example format:

Detected private key address: 0x1234...abcd
Target network: Atlantic Testnet (atlantic-testnet)
Proceed with this account on this network?

Example format for mainnet operations:

Detected private key address: 0x1234...abcd
⚠️ Target network: Mainnet (mainnet) — please proceed with caution
Proceed with this account on mainnet?

• After user confirmation, continue with subsequent operations (balance check, transaction sending, etc.)
• If user declines, stop execution

4. Automatic Balance Check

After confirming the account and network, automatically query the balance (see the balance check steps in each operation's Agent guidelines).