mcpField
N
near-smart-contracts

near-smart-contracts

github.com/near開発1694 回インストール4 週間前に更新
リポジトリ

near-smart-contracts について

NEAR ProtocolでRustとNEAR SDK v5.xを使うスマートコントラクト開発向けのスキルです。NEAR固有のルールと例を通じて、安全設計、テスト、デプロイ、ガス最適化を扱います。

主な機能

  1. 01NEAR SDK v5.xの開発ガイド
  2. 02セキュリティと状態管理のルール
  3. 03クロスコントラクト呼び出しとアップグレード
  4. 04テストとガス最適化の実践
  5. 05cargo nearによる作成とデプロイ手順

活用シーン

  1. 01cargo nearでRustコントラクトを開始
  2. 02コントラクトの安全性と状態処理のレビュー
  3. 03コールバックと失敗ケースのテスト
  4. 04コントラクト操作のガスコスト削減

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/near/agent-skills --skill near-smart-contracts

インストール後、Claude Code で/near-smart-contractsを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

rules/
best-contract-tools.md
chain-signatures.md
security-storage-checks.md
state-collections.md
structure-near-bindgen.md
testing-integration-tests.md
upgrade-migration.md
xcc-promise-chaining.md
yield-resume.md

詳細

NEAR スマートコントラクト開発

Rust と NEAR SDK（v5.x）を使用して、NEAR Protocol 上で安全かつ効率的なスマートコントラクトを開発するための包括的なガイドです。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

  • Rust で新しい NEAR スマートコントラクトを作成するとき
  • セキュリティと最適化の観点から既存のコントラクトコードをレビューするとき
  • コントラクト間呼び出しとコールバックを実装するとき
  • コントラクトの状態とストレージを管理するとき
  • NEAR コントラクトをテストしてデプロイするとき
  • ガス使用量とパフォーマンスを最適化するとき

はじめに

前提条件

開発を始める前に、必要なツールをインストールしてください。

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add wasm32 target for compiling contracts
rustup target add wasm32-unknown-unknown

# Install cargo-near (build, deploy, and manage contracts)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/cargo-near/releases/latest/download/cargo-near-installer.sh | sh

# Install near-cli-rs (interact with NEAR network)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/near-cli-rs/releases/latest/download/near-cli-rs-installer.sh | sh
新しいプロジェクトの作成

重要：新しいプロジェクトを作成する際は、必ず cargo near new を実行してください。Cargo.toml、lib.rs、またはプロジェクトファイルを手動で作成しないでください。このコマンドは、正しい設定で必要なファイルをすべて生成します。

# REQUIRED: Create a new contract project using the official template
cargo near new my-contract

# Navigate to project directory
cd my-contract

# Build the contract
cargo near build

# Run tests
cargo test

cargo near new が必須である理由：

  • 適切な依存関係とビルド設定を含む正しい Cargo.toml を生成します
  • src/lib.rs のテンプレートを含む適切なプロジェクト構造を作成します
  • tests/ ディレクトリに統合テストの設定を含めます
  • overflow-checks = true を指定したリリースプロファイルを設定します
  • WASM コンパイルに適した正しい crate-type を設定します
  • ビルド失敗の原因となる一般的な設定ミスを防ぎます

次のことはしないでください：

  • Cargo.toml を手動で作成する
  • src/lib.rs を手動で作成する
  • サンプルからプロジェクト構造をコピー＆ペーストする
  • この手順を省略して、ファイルを直接作成する
プロジェクト構造
my-contract/
├── Cargo.toml          # Dependencies and project config
├── src/
│   └── lib.rs          # Main contract code
├── tests/              # Integration tests
│   └── test_basics.rs
└── README.md
Testnet へのデプロイ
# Create a testnet account (if needed)
near account create-account sponsor-by-faucet-service my-contract.testnet autogenerate-new-keypair save-to-keychain network-config testnet create

# Build in release mode
cargo near build --release

# Deploy to testnet
cargo near deploy my-contract.testnet without-init-call network-config testnet sign-with-keychain send

優先度別のルールカテゴリ

優先度カテゴリ影響度プレフィックス
1セキュリティと安全性重大security-
2コントラクト構造高structure-
3状態管理高state-
4コントラクト間呼び出し中〜高xcc-
5コントラクトのアップグレード中〜高upgrade-
6チェーン署名中〜高chain-
7ガス最適化中gas-
8Yield と Resume中yield-
9テスト中testing-
10ベストプラクティス中best-
1. セキュリティと安全性（重大）
  • security-storage-checks - ストレージ操作を必ず検証し、デポジットを確認する
  • security-access-control - predecessor_account_id を使用して適切なアクセス制御を実装する
  • security-reentrancy - 再入攻撃を防ぐ（外部呼び出しの前に状態を更新する）
  • security-overflow - オーバーフローを防ぐため、Cargo.toml で overflow-checks = true を使用する
  • security-callback-validation - コールバックの結果を検証し、失敗に対処する
  • security-private-callbacks - 外部呼び出しを防ぐため、コールバックに #[private] を付ける
  • security-yoctonear-validation - #[payable] 関数で付随するデポジットを検証する
  • security-sybil-resistance - スパムを防ぐため、最低デポジット額のチェックを実装する
2. コントラクト構造（高）
  • structure-near-bindgen - コントラクト構造体に #[near(contract_state)] マクロを使用する（旧 #[near_bindgen] の代替）
  • structure-initialization - #[init] パターンを使って適切な初期化を実装する
  • structure-versioning - バージョン管理の仕組みを用いて、コントラクトのアップグレードに備える
  • structure-events - env::log_str() と構造化イベントログ（NEP-297）を使用する
  • structure-standards - 標準規格については NEAR Enhancement Proposals（NEP）に従う
  • structure-serializers - データ構造体には #[near(serializers = [json, borsh])] を使用する
  • structure-panic-default - 初期化を必須にするため、#[derive(PanicOnDefault)] を使用する
3. 状態管理（HIGH）
  • state-collections - near_sdk::store の SDK コレクションを使用します：IterableMap、IterableSet、Vector、LookupMap、LookupSet、UnorderedMap、UnorderedSet、TreeMap
  • state-serialization - 状態には Borsh、外部インターフェースには JSON を使用します
  • state-lazy-loading - ガスを節約するため、遅延読み込みには SDK コレクションを使用します（一度にすべてではなく、必要に応じて読み込みます）
  • state-pagination - 大規模なデータセットには .skip() と .take() でページネーションを実装します
  • state-migration - バージョン管理を用いた状態移行戦略を計画します
  • state-storage-cost - 1 NEAR ≈ 100kb のストレージであり、コントラクトは自身のストレージに対して支払いが必要です
  • state-unique-prefixes - すべてのコレクションに一意のバイトプレフィックスを使用します（衝突を避けます）
  • state-native-vs-sdk - ネイティブコレクション（Vec、HashMap）はすべてのデータを読み込むため、100 エントリー未満の場合にのみ使用します
4. コントラクト間呼び出し（MEDIUM-HIGH）
  • xcc-promise-chaining - プロミスを正しくチェーンします
  • xcc-callback-handling - すべてのコールバックシナリオ（成功、失敗）に対応します
  • xcc-gas-management - コントラクト間呼び出しに適切なガスを割り当てます
  • xcc-error-handling - 堅牢なエラー処理を実装します
  • xcc-result-unwrap - チェックせずにプロミスの結果をアンラップしないでください
5. コントラクトのアップグレードと移行（MEDIUM-HIGH）
  • upgrade-migration - 状態のバージョン管理には列挙型を使用し、#[init(ignore_state)] を指定した migrate メソッドを実装します
  • upgrade-self-update - コントラクトがプログラムから自身を更新できるようにするパターンです
  • upgrade-cleanup-old-state - ストレージを解放するため、古い状態構造を必ず削除します
  • upgrade-dao-controlled - 本番環境のアップグレードガバナンスには、マルチシグまたは DAO を使用します
6. Chain Signatures（MEDIUM-HIGH）
  • chain-signatures - 外部ブロックチェーンのアドレスを導出し、MPC 署名をリクエストして、マルチチェーントランザクションを構築します
  • chain-callback-handling - MPC 署名のコールバックを適切に処理します
  • chain-gas-allocation - MPC 呼び出しには十分なガスを割り当てます（yield/resume パターン）
7. ガスの最適化（MEDIUM）
  • gas-batch-operations - トランザクションコストを削減するため、操作をバッチ処理します
  • gas-minimal-state-reads - 状態の読み書きを最小限に抑えます（メモリにキャッシュします）
  • gas-efficient-collections - 適切なコレクション型を選択します（LookupMap と IterableMap）
  • gas-view-functions - 読み取り専用関数を view（Rust では &self）として指定します
  • gas-avoid-cloning - 大規模なデータ構造の不要なクローンを避けます
  • gas-early-validation - 無効な入力に対するガスを節約するため、早い段階で require! を使用します
  • gas-prepaid-gas - コントラクト間呼び出しには適切なガスを付与します（推奨値：30 TGas）
8. Yield と Resume（MEDIUM）
  • yield-resume - yield されたプロミスを作成し、再開を通知し、タイムアウトに対応して、yield/resume 間の状態を管理します
  • yield-gatekeeping - 権限のない呼び出し元から resume メソッドを保護します
9. テスト（MEDIUM）
  • testing-integration-tests - 統合テストには near-sandbox と near-api を使用します
  • testing-unit-tests - モックコンテキストを使って包括的な単体テストを作成します
  • testing-sandbox - testnet/mainnet の前にローカルサンドボックス環境でテストします
  • testing-edge-cases - 境界条件、オーバーフロー、空の状態をテストします
  • testing-gas-profiling - 統合テストでガス使用量をプロファイリングします
  • testing-cross-contract - コントラクト間呼び出しとコールバックを十分にテストします
  • testing-failure-scenarios - プロミスの失敗とタイムアウトのシナリオをテストします
  • testing-time-travel - 時間に依存するテストには sandbox.fast_forward() を使用します
10. ベストプラクティス（中級）
  • best-contract-tools - NEP 標準（FT、NFT など）および NEP-297 の構造化イベントには、near-sdk-contract-tools を使用します
  • best-panic-messages - 明確で、対処方法が分かるパニックメッセージを記述します
  • best-logging - デバッグとイベントの出力には、env::log_str() を使用します
  • best-documentation - 公開メソッド、パラメーター、複雑なロジックをドキュメント化します
  • best-error-types - カスタムエラー型を定義するか、説明的な文字列を使用します
  • best-constants - マジックナンバーや設定には定数を使用します
  • best-require-macro - より適切なエラーメッセージを表示できるよう、assert! の代わりに require! を使用します
  • best-promise-return - 適切に追跡できるよう、コントラクト間呼び出しからプロミスを返します
  • best-sdk-crates - SDK がエクスポートするクレート（borsh、serde、base64 など）を再利用します
  • best-account-id-encoding - ストレージを 40% 節約するため、AccountId を base32 でエンコードします

使用方法

詳しい説明とコード例については、個々のルールファイルを参照してください。

rules/security-storage-checks.md
rules/structure-near-bindgen.md
rules/state-collections.md
rules/xcc-promise-chaining.md
rules/upgrade-migration.md
rules/chain-signatures.md
rules/yield-resume.md
rules/best-contract-tools.md
rules/testing-integration-tests.md

各ルールファイルには、次の内容が含まれています。

  • 重要な理由の簡潔な説明
  • 誤ったコード例とその説明
  • 正しいコード例とその説明
  • 追加の背景情報と NEAR 固有の考慮事項

追加ルール（上流ドキュメント）

ローカルファイルがないルールについては、公式ドキュメントを参照してください（プレーンな Markdown の場合は .md を付加します）。

トピック上流ドキュメント
セキュリティチェックリスト（全般）https://docs.near.org/smart-contracts/security/checklist
ストレージコスト攻撃https://docs.near.org/smart-contracts/security/storage
プライベートコールバックhttps://docs.near.org/smart-contracts/security/cross-contract-calls/callbacks
XCC 失敗時にアタッチされた NEAR を返金するhttps://docs.near.org/smart-contracts/security/cross-contract-calls/refunds
コールバック内でパニックを発生させないhttps://docs.near.org/smart-contracts/security/cross-contract-calls/callback-panics
安全な ft_on_transfer / 再入可能性https://docs.near.org/smart-contracts/security/cross-contract-calls/ft-transfer-call
転送前に残高を差し引くhttps://docs.near.org/smart-contracts/security/cross-contract-calls/reentrancy
1 yoctoNEAR を要求するhttps://docs.near.org/smart-contracts/security/one_yocto
シビル攻撃https://docs.near.org/smart-contracts/security/sybil
フロントランニングhttps://docs.near.org/smart-contracts/security/frontrunning
トークン ID の重複https://docs.near.org/smart-contracts/security/duplicate-inputs
乱数https://docs.near.org/smart-contracts/security/random
単体テストhttps://docs.near.org/smart-contracts/testing/unit-test
グローバルコントラクトhttps://docs.near.org/smart-contracts/global-contracts
シリアライゼーションhttps://docs.near.org/smart-contracts/anatomy/serialization
本番ビルドhttps://docs.near.org/smart-contracts/anatomy/reduce-size

最新のツールとバージョン

開発ツール
  • cargo-near：最新 — コントラクトのビルド、デプロイ、管理（cargo near build、cargo near deploy）
  • near-cli-rs：最新 — NEAR 用コマンドラインインターフェース（near contract call、near contract view）
  • rustc：最新の安定版 — Rust コンパイラー
  • near-sandbox：最新 — 統合テスト用のローカルサンドボックス環境
  • near-api-rs：最新 — NEAR とやり取りするための Rust API クライアント（テストでは near-workspaces-rs に代わるもの）
  • omni-transaction-rs：最新 — 複数のブロックチェーン（Bitcoin、Ethereum など）向けのトランザクションを構築
SDK バージョン
  • near-sdk-rs：v5.x（最新は 5.29.x）— 現行の安定版 SDK。#[handle_result] と #[near(contract_state)] が最新の慣用表現です
  • near-sdk-contract-tools：最新 — NEP 標準（FT、NFT、ストレージ管理）用の導出マクロ
主な機能
  • 統一されたマクロ構文：#[near(contract_state)] が #[near_bindgen] と derive を置き換えます
  • 柔軟なシリアライズ：データ構造体に #[near(serializers = [json, borsh])] を指定できます
  • ストアコレクション：near_sdk::store::IterableMap、IterableSet、LookupMap、LookupSet、Vector、UnorderedMap、UnorderedSet、TreeMap
  • 簡素化されたコントラクト間呼び出し：Promise::new() と .then() を使った高水準のプロミス API
  • NEP サポートを標準搭載：FT（NEP-141）、NFT（NEP-171）、その他の標準規格
  • 結果の処理：パニックを起こさずに Result<T, E> を返すメソッドに使用する #[handle_result]
  • Yield/Resume：コントラクトは実行を一時停止し、外部サービスによる再開を待機できます
  • チェーン署名：他のブロックチェーン（Bitcoin、Ethereum、Solana など）向けのトランザクションに署名できます
  • コントラクトツール：Owner、Pause、ロールベースアクセス制御パターン向けの derive マクロ

リソース

ストレージコストの参考情報

ストレージコスト備考
1 byte0.00001 NEAR0.1 NEAR あたり約 10kb
100 KB約 1 NEARおおよその目安
AccountId64+ bytesbase32 エンコーディングで 40% 節約できます
コントラクトコード変動コントラクトアカウントが支払います

SDK コレクションのリファレンス

コレクション反復可能クリア順序あり範囲検索用途
Vectorはいはいはいはいインデックスアクセスが可能な順序付きリスト
LookupMapいいえいいえいいえいいえ反復が不要な高速なキーと値の格納
LookupSetいいえいいえいいえいいえ高速な要素の存在確認
IterableMapはいはいはいいいえ反復可能なキーと値の格納
IterableSetはいはいはいいいえ反復可能なセット
UnorderedMapはいはいいいえいいえ順序なしで反復するキーと値の格納
UnorderedSetはいはいいいえいいえ順序なしで反復するセット
TreeMapはいはいはいはい範囲クエリに対応したソート済みのキーと値の格納

コメント

Markdown 対応