pharos-skill-engine

Pharos Chain Skills

Pharos ブロックチェーン向けの開発者ツールキットです。Foundry（cast／forge）の CLI コマンドを使用して、オンチェーンのクエリ、トランザクションの送信、コントラクトのデプロイと検証を行います。

前提条件

1. Foundry をインストールする（必須 — ほかの操作を行う前に必ず実行してください）：
   • エージェントは、まず which cast を実行して Foundry がインストールされているか確認する必要があります。
   • cast が見つからない場合、エージェントはただちに次のインストールコマンドを実行する必要があります。インストールを省略しないでください。回避策として curl／JSON-RPC に切り替えないでください。Foundry がインストールされるまで、ほかのタスクに進まないでください。

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

     次に、以下を実行します：

     source ~/.zshenv && foundryup
     

     次のコマンドで確認します：

     cast --version
     

   • インストールに失敗した場合は、ユーザーに伝えて処理を停止してください。別の方法を試さないでください。
2. 秘密鍵を設定する：トランザクションの送信やコントラクトのデプロイなどの書き込み操作には、次のいずれかの方法で秘密鍵を指定する必要があります。
   • コマンド引数：--private-key <your_private_key>
   • 環境変数：$PRIVATE_KEY

ネットワーク設定

ネットワーク情報は assets/networks.json に保存されており、Atlantic テストネットとメインネットの両方のチェーンが含まれています。

• デフォルトのネットワーク：Atlantic テストネット（atlantic-testnet）。ユーザーがネットワークを指定しない場合に使用します。
• ネットワークの切り替え：ユーザーが mainnet を指定した場合は、assets/networks.json から該当するエントリの rpcUrl を読み込みます。
• 使用方法：assets/networks.json を読み込み、対象ネットワークの rpcUrl を各コマンドの --rpc-url パラメーターに設定します。コントラクトの検証には、chainId と explorerApiUrl も必要です。

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

機能インデックス

ユーザーのニーズに応じた参照ファイルを読み込み、コマンドの完全なテンプレートを確認してください。

ユーザーのニーズ	機能	詳細な手順
ウォレットのポートフォリオ／資産の概要を表示	cast balance + cast call（既知の全トークンを一括クエリ）	→ references/query.md#address-portfolio-wallet-asset-overview
アドレス残高を照会	cast balance / cast call	→ references/query.md#balance-query
トランザクションのステータスを照会	cast tx / cast receipt	→ references/query.md#transaction-query
コントラクトの読み取り専用メソッドを呼び出す	cast call	→ references/query.md#contract-read-only-call
トランザクションを送信（ネイティブトークンの送金）	cast send	→ references/transaction.md#native-token-transfer
コントラクトの書き込みメソッドを呼び出す	cast send	→ references/transaction.md#contract-write-call
ガスを見積もる	cast estimate	→ references/transaction.md#gas-estimation
コントラクトをデプロイ	forge script（デプロイスクリプトを自動生成）	→ references/contract.md#deploy-contract-forge-script
コントラクトを検証	forge verify-contract	→ references/contract.md#verify-contract
ERC20 をワンクリックでデプロイ	forge script + 組み込み ERC20 テンプレート	→ references/contract.md#erc20-one-click-deploy-built-in-template
一括送金／エアドロップ	forge script（エアドロップスクリプトを自動生成。6000 件以上のアドレスへの一括エアドロップ、CSV ファイル入力、3 段階の自動モード（≤10 件：シンプルモード／11～200 件：単一バッチ／>200 件：複数バッチ）、強化された Distributor コントラクトに対応）	→ references/transaction.md#batch-transfer--airdrop
コントラクト操作スクリプトを生成（読み取り／書き込みメソッド、JS／TS／Python）	Script_Generator（エージェントが自動生成）	→ references/script-gen.md

一般的なエラー処理

コマンドを実行する前に、エージェントは事前チェックを行う必要があります。コマンドが失敗した場合は、標準エラー出力に基づいて、ユーザーにわかりやすいエラーメッセージを表示してください。

エラーシナリオ	CLI エラーの特徴	対処
無効なアドレス形式	invalid address	アドレス形式（0x + 40 桁の 16 進数文字）を確認するよう促します
トランザクションハッシュが見つからない	transaction not found	トランザクションが見つからないことを伝え、ハッシュを確認するよう促します
アドレスにコントラクトコードがない	空の戻り値	対象アドレスにコントラクトコードがないことを伝えます
呼び出しのリバート	execution reverted	リバート理由を抽出して表示します
秘密鍵が設定されていない	コマンドに --private-key がない	引数または環境変数で秘密鍵を設定するよう促します
残高不足	insufficient funds	残高不足を伝え、現在の残高を表示します
ノンスの競合	nonce too low	しばらく待つか、ノンスを手動で指定するよう提案します
ネットワーク設定がない	assets/networks.json を読み取れない	設定ファイルが見つからないか、形式が無効であることを伝えます
サポートされていないネットワーク	ネットワーク名が設定リストにない	atlantic-testnet と mainnet のみがサポートされていることを伝えます

各操作の詳細なエラー処理表については、対応するリファレンスファイルを参照してください。

セキュリティに関する注意事項

• 秘密鍵の保護：秘密鍵をログ、チャット履歴、バージョン管理に決して公開しないでください。秘密鍵は $PRIVATE_KEY 環境変数に保存し、コマンドでは --private-key $PRIVATE_KEY を使って明示的に指定してください。注：forge / cast は環境変数を自動的に読み込みません。コマンド引数として明示的に渡す必要があります。
• ネットワークの確認：書き込み操作を実行する前に、エージェントは対象ネットワーク（テストネットまたはメインネット）をユーザーにはっきり伝える必要があります。誤操作を防ぐため、メインネットでの操作では目立つ警告を表示し、ユーザーに再確認を求めてください。

書き込み操作の事前チェック（すべての書き込み操作で必須）

秘密鍵が必要なすべての操作（送金、コントラクト呼び出し、デプロイ、エアドロップなど）では、エージェントは実行前に次のチェックを自動的に完了する必要があります。

1. 秘密鍵の確認

$PRIVATE_KEY 環境変数が設定されているかを自動的に検出します。

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

• 設定されていない場合：export PRIVATE_KEY=<your_private_key> で設定するようユーザーに促し、処理を続行しません
• 設定されている場合：次の手順に進みます

2. 公開アドレスを導出してユーザーに確認

cast wallet address を使って秘密鍵から対応する公開アドレスを導出します。

cast wallet address --private-key $PRIVATE_KEY

3. ネットワークの確認（ユーザーにはっきり伝えること）

書き込み操作を実行する前に、エージェントは対象ネットワークをユーザーにはっきり伝える必要があります。assets/networks.json から対象ネットワークの情報を読み取り、ネットワーク名と種別をユーザーに表示してください。

• ユーザーがネットワークを指定しなかった場合は、デフォルトのネットワーク（atlantic-testnet）を使用し、現在の操作は Atlantic テストネットを対象としていますとはっきり伝えます
• ユーザーが mainnet を指定した場合は、目立つように警告します：現在の操作はメインネットを対象としています。続行するには確認してください

手順 2 と 3 の情報を組み合わせて、ユーザーの確認を求めます。形式の例：

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

メインネット操作の形式の例：

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

• ユーザーが確認した後、後続の操作（残高確認、トランザクションの送信など）に進みます
• ユーザーが拒否した場合は、実行を停止します

4. 残高の自動確認

アカウントとネットワークの確認後、残高を自動的に照会します（各操作のエージェント向けガイドラインにある残高確認手順を参照）。