acton

Acton TON CLI ワークフロー

信頼できる情報源

• コマンドの表記と動作については、インストール済みのバイナリを優先してください。
  • acton --version
  • acton --help
  • acton help <command>
  • acton <command> --help
• 現在の概念、チュートリアル、完全なリファレンスについては、公式ホスト型ドキュメントを使用してください。
  • https://ton-blockchain.github.io/acton/docs/welcome/
  • https://ton-blockchain.github.io/acton/docs/commands/
  • https://ton-blockchain.github.io/acton/llms-full.txt
• 実際のプロジェクトパターンやコントラクトのリファレンスには、公式サンプルリポジトリを使用してください。
  • https://github.com/ton-blockchain/acton-contracts
• 必要な場合にのみ、同梱のリファレンスを参照してください。
  • コマンドをすばやく選ぶには references/command-map.md
  • よくある失敗例については references/troubleshooting.md
• ローカルのパス、プライベートなチェックアウト、特定の開発者のマシンを前提にしないでください。
• ユーザーがアップストリームの実装の調査を明示的に求めた場合にのみ、GitHub のソースを使用してください。acton-contracts は、プロジェクト構成とコントラクトパターンのサンプルとして扱い、CLI フラグの信頼できる情報源として扱わないでください。
• ドキュメントとインストール済み CLI の内容が異なる場合は、Acton のバージョンを明記し、そのローカルのワークフローではインストール済み CLI に従ってください。最新の動作を確認したい場合は、まず acton up またはインストール／更新手順を提案してください。

初回リリースでは対象外

• acton localnet や --net localnet は推奨しないでください。この機能はソースや trunk のヘルプに表示されている場合がありますが、初回リリースでは対象外のため、公開ワークフローでは利用できないものとして扱ってください。

Acton のインストールまたは更新

acton が見つからず、タスクで実行が必要な場合は、公開バイナリをインストールしてください。

curl -LsSf https://github.com/ton-blockchain/acton/releases/latest/download/acton-installer.sh | sh

その後、新しいシェルを開くか、必要に応じて更新されたシェルプロファイルを再読み込みし、次のコマンドで確認してください。

acton --version
acton --help

更新とバージョン管理：

• acton up は最新の安定版をインストールします。
• acton up --list は利用可能なバージョンを一覧表示します。
• acton up <version> は指定したバージョンをインストールします。
• インストール済み CLI が対応している場合、acton up --trunk は最新の trunk ビルドをインストールします。
• CI では、ton-blockchain/setup-acton@master または公開済みの ghcr.io/ton-blockchain/acton:<version> イメージを優先してください。

あらゆるプロジェクトで最初に確認すること

1. ツールとプロジェクトのコンテキストを確認します。
   • acton --version
   • acton doctor
   • pwd
2. プロジェクト外から実行する場合は、コンテキストを明示的に指定します。
   • acton --project-root <PATH> ...
   • acton --manifest-path <PATH>/Acton.toml ...
3. 記憶に頼る前に、関連するコマンドのヘルプを確認します。
   • acton help build
   • acton help test
   • acton help script
4. 関連するセクションについて Acton.toml を確認します。
   • [package]
   • [contracts]
   • [build]
   • [wrappers.tolk]
   • [wrappers.typescript]
   • [fmt]
   • [test]
   • [lint]
   • [networks]
   • [scripts]
   • [import-mappings]

プロジェクトルートの規則：設定ファイル内の相対パスはプロジェクトルートを基準に解決されます。相対 CLI パスフラグは、絶対パスとして渡さない限り、現在の作業ディレクトリを基準に解決されます。

プロジェクトの初期設定

• 新しいプロジェクトには acton new [path] --template empty|counter|jetton|nft を使用してください。
• acton new で便利なフラグ：
  • --name、--description、--license
  • テンプレートが対応している場合、TypeScript/Vite アプリのひな形を作成する --app
  • デフォルトのプロジェクト Git フックを設定する --hooks
  • コーディングエージェント向けのガイダンスを生成する --agents
• 既存のディレクトリに Acton のサポートを追加するには acton init を使用してください。
• acton init の便利なモード：
  • acton init --create-app [path] は TypeScript アプリのひな形のみを作成します。
  • acton init --stdlib-only は同梱の標準ライブラリのみを更新します。
• acton init は既存のマニフェストにデフォルトの [import-mappings] を追加できますが、この書き換えによって TOML コメントや不明なキーが削除される場合があります。

ビルド、コンパイル、ラッパー

• acton build [contract-name]
  • すべてのコントラクト、または1つのコントラクトとその推移的依存関係をビルドします。
  • 主なフラグ：--clear-cache、--graph <path>、--out-dir <dir>、--gen-dir <dir>、--output-fift <dir>、--info。
• acton compile <file.tolk>
  • 単一ファイルコンパイラのエントリーポイントです。
  • 主なフラグ：--json、--base64-only、--boc <file>、--fift <file>、--source-map <file>、--abi <file>、--allow-no-entrypoint、--clear-cache。
• acton wrapper <contract-name>
  • コントラクトの ABI から Tolk ラッパーを生成します。
  • テスト用スタブには --test、--test-output、または --test-output-dir を使用します。
  • gen-typescript-from-tolk 経由で TypeScript ラッパーを生成するには --ts を使用します。
  • --ts とテスト用スタブの生成を併用しないでください。
• ABI、ストレージ、またはメッセージの型が変更された場合は、生成済みファイルを手動で編集せず、ラッパーを再生成してください。
• ラッパーの出力先のデフォルトは、[wrappers.tolk]、[wrappers.typescript]、および @wrappers のインポートマッピングで設定します。

テストと品質ゲート

• コアエントリーポイント：acton test [path]。
• 主なテストフラグ：
  • --filter <regex>、--include <glob>、--exclude <glob>
  • --fail-fast
  • --fuzz-seed <seed>
  • 低レベルのエグゼキューターログを表示する --verbose
  • --debug --debug-port <port>
  • --backtrace full
  • --reporter console|dot|teamcity|junit またはカンマ区切りの組み合わせ
  • --junit-path <dir>、--junit-merge
  • --show-bodies
  • --clear-cache
• カバレッジ：
  • acton test --coverage --coverage-format lcov
  • acton test --coverage --coverage-format text
  • --coverage-file <path>
  • --coverage-minimum-percent <percent>
  • --coverage-include-wrappers
  • --coverage-include-tests
• ガスプロファイリング：
  • acton test --snapshot build/gas-baseline.json
  • acton test --baseline-snapshot build/gas-baseline.json
  • acton test --baseline-snapshot build/gas-baseline.json --fail-on-diff
• ミューテーションテスト：
  • acton test --mutate --mutate-contract <contract-name>
  • --mutation-diff worktree|ref|branch
  • --mutation-diff-ref <ref>
  • --mutation-levels critical,major,minor
  • --mutation-disable-rules <rule>
  • --mutation-rules-file <path>
  • --mutation-session-id <id>
  • --mutation-id <id>
  • --mutation-workers <n>
  • --mutation-minimum-percent <percent>
• フォークテスト：
  • acton test --fork-net testnet|mainnet|custom:<name>
  • acton test --fork-net testnet --fork-block-number <seqno>
• テスト UI とトレース：
  • acton test --ui
  • acton test --ui --ui-port <port>
  • acton test --save-test-trace
  • acton test --save-test-trace <dir>
• デフォルトは [test]、[test.coverage]、[test.fuzz]、および [test.mutation] で設定します。CLI フラグは、その実行に限り設定を上書きします。

リント、フォーマット、フック

• acton check [target]
  • プロジェクト、コントラクト名、または .tolk ファイルをチェックします。
  • 主なフラグ：--fix、--output-format plain|json|sarif|github|gitlab、--output-file <path>、--enable-only <code[,code...]>、--explain <rule>。
• リント設定は [lint]、[lint.rules]、および [lint.rules.<contract-name>] で行います。
• インライン抑制には // check-disable-next-line ... を使用します。
• acton fmt [paths...]
  • ソースをフォーマットします。
  • CI では acton fmt --check を使用します。
  • デフォルトは [fmt] で設定します。
• acton hooks new|install|status|uninstall
  • プロジェクトローカルの Git フックを .githooks で管理します。
• 一般的な CI ゲート：
  • acton build
  • acton test --reporter console,junit
  • acton check --output-format github
  • acton fmt --check

スクリプト、デプロイ、ネットワークからの読み取り

• acton script <path> [args...] は、単独の Tolk スクリプトを実行します。
• acton deploy コマンドはありません。デプロイはスクリプトによって実行されます。
• 状態を変更するスクリプトを安全に実行する手順：
  1. acton build
  2. acton test
  3. acton script <path> を実行してローカルでエミュレートします
  4. acton script <path> --net testnet
  5. testnet での検証後に限り、acton script <path> --net mainnet を実行します
• --net <network> は、testnet、mainnet、または custom:<name> に実トランザクションをブロードキャストします。--net を省略すると、ローカルで実行されます。
• --fork-net <network> は、ローカルで実行しながらリモートの状態を読み取ります。--net を指定した場合、--fork-net を省略すると、読み取りには選択したネットワークがデフォルトで使われます。
• スクリプトでよく使われるフラグ：--debug、--debug-port、--backtrace full、--verbose、--clear-cache、--fork-net、--fork-block-number、--net、--explorer tonscan|toncx|dton|tonviewer、--show-bodies。
• acton run <script-name> [args...] は、Acton.toml の [scripts] に登録されたエントリーを実行します。
• スクリプトの引数は main() の ABI に従って解析されます。Acton のフラグに見える引数を渡す場合は、その前に -- を指定してください。
• 組み込みのネットワーク API キーは環境変数で指定します。通常は .env から読み込みます：
  • TONCENTER_TESTNET_API_KEY
  • TONCENTER_MAINNET_API_KEY
  • custom:<name> 用の <NORMALIZED_NAME>_API_KEY

ウォレット、検証、調査

• ウォレット：
  • acton wallet new
  • acton wallet import
  • acton wallet list
  • acton wallet export-mnemonic
  • acton wallet sign
  • acton wallet remove
  • acton wallet airdrop
• 利用可能な場合は、安全なキーリングへの保存を優先してください。CI では mnemonic-env を使用し、平文のウォレットファイルやニーモニックは決してコミットしないでください。
• 検証：
  • acton verify [contract-name] --address <addr> --net testnet|mainnet
  • 便利なフラグ：--wallet <name>、--compiler-version <version>、--dry-run。
• RPC の調査：
  • acton rpc info <address>
  • acton rpc block
  • acton rpc block-number
  • acton rpc trace <hash>
• オンチェーンライブラリ：
  • acton library publish
  • acton library fetch
  • acton library info
  • acton library topup
• 低レベルツール：
  • acton disasm [boc-file]
  • acton retrace <tx-hash>
  • acton doc tvm <query...>
  • acton func2tolk <path>
  • acton ls --stdio または acton ls --port <port>
  • acton completions bash|elvish|fish|powershell|zsh|nushell

安全性と正確性に関するルール

• acton script --net mainnet、acton verify、acton library publish、または acton library topup を実行する前に、一度警告してください。
• 結果に影響する場合は、ウォレット、ネットワーク、プロジェクトルート、Acton のバージョンについて、前提を明示してください。
• コマンドやフラグを捏造しないでください。不明な場合は acton help <command> で確認してください。
• ユーザーのインストール済みバイナリが明示的にサポートしている場合を除き、acton litenode、[mappings]、--broadcast、--api-key、acton up --canary を使う古い例は使用しないでください。
• Acton のドキュメントで扱われていないブロックチェーンの概念には TON のドキュメントを、CLI の動作には Acton のドキュメントを使用してください。