use-ts-sdk

Name: use-ts-sdk
Author: aptos-labs

github.com/aptos-labs開発2071 回インストール24 週間前に更新

リポジトリ

use-ts-sdk について

Aptos dApp への `@aptos-labs/ts-sdk` 導入を調整するスキルです。個別タスクに適したスキルへ案内し、フルスタック連携の手順や鍵の安全管理、エラー対応を示します。

主な機能

01個別 SDK スキルへのタスク振り分け
02フルスタック dApp ワークフローの提示
03秘密鍵の安全な取り扱い方針
04エラー処理パターンの説明
05SDK バージョン変更の記録

活用シーン

01エンドツーエンドの dApp 連携計画
02SDK タスクに合うスキルの選択
03一般的なトランザクション・ネットワークエラーへの対応

インストール

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

$npx skills add https://github.com/aptos-labs/aptos-agent-skills --skill use-ts-sdk

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

詳細

TypeScript SDK を使用する（オーケストレーター）

目的

Aptos dApp 向けの @aptos-labs/ts-sdk 統合をオーケストレーションします。具体的なタスクの場合は、該当する細分化されたスキルに振り分けます。複合的なタスク（例：「フルスタックの dApp を作って」）の場合は、以下のワークフローに従います。

基本ルール

必ず @aptos-labs/ts-sdk を使用してください（現行の公式 SDK です。非推奨の aptos パッケージは使用しないでください）
ソースコードやフロントエンドのバンドルに秘密鍵をハードコードしないでください
クライアント側のコードやログに秘密鍵を絶対に公開しないでください
ブラウザーからアクセス可能な環境変数に秘密鍵を保存しないでください（公開設定にのみ VITE_ プレフィックスを使用してください）
サーバー側のスクリプトでは、必ず process.env を使用して環境変数から秘密鍵を読み込んでください

重要：ボイラープレートテンプレート

プロジェクトが npx create-aptos-dapp（ボイラープレートテンプレート）でひな形を作成されている場合、ウォレットアダプターと SDK のセットアップはすでに完了しています。 新しいコードを書く前に、既存の内容を確認してください。

frontend/components/WalletProvider.tsx — 自動接続機能を備えたウォレットアダプターのセットアップ
frontend/constants.ts — 環境変数から取得する NETWORK、MODULE_ADDRESS、APTOS_API_KEY
frontend/entry-functions/ — 既存のエントリー関数のパターン（新しい関数にもこのパターンを適用してください）
frontend/view-functions/ — 既存のビュー関数のパターン（新しい関数にもこのパターンを適用してください）

ウォレットプロバイダー、クライアントのセットアップ、定数がすでに存在する場合は、再作成しないでください。代わりに、既存のパターンに従って Move コントラクト用のエントリー関数やビュー関数を追加してください。

スキルの振り分け

タスクに応じて、該当する細分化されたスキルに振り分けてください。

タスク	スキル
Aptos クライアントのセットアップ／ネットワークの設定	ts-sdk-client
アカウント／署名者の作成（サーバー側）	ts-sdk-account
アドレスの解析、フォーマット、導出	ts-sdk-address
トランザクションの構築、署名、送信、シミュレーション	ts-sdk-transactions
オンチェーンデータの読み取り（ビュー、残高、リソース）	ts-sdk-view-and-query
Move 型を TypeScript 型にマッピング	ts-sdk-types
React フロントエンドでのウォレット接続	ts-sdk-wallet-adapter

フルスタック dApp のワークフロー

フロントエンド統合を一通り構築する場合：

クライアントをセットアップする → ts-sdk-client を読む
ビュー関数のラッパーを作成する → ts-sdk-view-and-query を読む
エントリー関数のペイロードを作成する → ts-sdk-transactions を読む
ウォレット接続を組み込む → ts-sdk-wallet-adapter を読む
型を正しく扱う → 必要に応じて ts-sdk-types を読む

ファイル構成のパターン

src/
  lib/
    aptos.ts                    # Singleton Aptos client + MODULE_ADDRESS
  view-functions/
    getCount.ts                 # One file per view function
    getListing.ts
  entry-functions/
    increment.ts                # One file per entry function
    createListing.ts
  hooks/
    useCounter.ts               # React hooks wrapping view functions
    useListing.ts
  components/
    WalletProvider.tsx           # AptosWalletAdapterProvider wrapper
    IncrementButton.tsx          # Components calling entry functions

エラー処理のパターン

async function submitTransaction(
  aptos: Aptos,
  signer: Account,
  payload: InputGenerateTransactionPayloadData
): Promise<string> {
  try {
    const transaction = await aptos.transaction.build.simple({
      sender: signer.accountAddress,
      data: payload
    });

    const pendingTx = await aptos.signAndSubmitTransaction({
      signer,
      transaction
    });

    const committed = await aptos.waitForTransaction({
      transactionHash: pendingTx.hash
    });

    if (!committed.success) {
      throw new Error(`Transaction failed: ${committed.vm_status}`);
    }

    return pendingTx.hash;
  } catch (error) {
    if (error instanceof Error) {
      if (error.message.includes("RESOURCE_NOT_FOUND")) {
        throw new Error("Resource does not exist at the specified address");
      }
      if (error.message.includes("MODULE_NOT_FOUND")) {
        throw new Error("Contract is not deployed at the specified address");
      }
      if (error.message.includes("ABORTED")) {
        const match = error.message.match(/code: (\d+)/);
        const code = match ? match[1] : "unknown";
        throw new Error(`Contract error (code ${code})`);
      }
    }
    throw error;
  }
}

エッジケース

シナリオ	確認内容	対応
リソースが見つからない	`error.message.includes("RESOURCE_NOT_FOUND")`	デフォルト値または null を返します
モジュールがデプロイされていない	`error.message.includes("MODULE_NOT_FOUND")`	「コントラクトがデプロイされていません」というメッセージを表示します
関数が見つからない	`error.message.includes("FUNCTION_NOT_FOUND")`	関数名とモジュールアドレスを確認します
Move の中断	`error.message.includes("ABORTED")`	中断コードを解析し、ユーザー向けのエラーに変換します
ガス不足	`error.message.includes("OUT_OF_GAS")`	`maxGasAmount` を増やして再試行します
シーケンス番号エラー	`error.message.includes("SEQUENCE_NUMBER")`	最新のシーケンス番号を取得してから再試行します
ネットワークのタイムアウト	`error.message.includes("timeout")`	指数バックオフで再試行します
アカウントが存在しない	`error.message.includes("ACCOUNT_NOT_FOUND")`	アカウントに資金を追加するか、ユーザーに作成を促します
残高不足	`error.message.includes("INSUFFICIENT_BALANCE")`	残高と必要な金額を表示します
ウォレットでユーザーが拒否	ウォレット固有の拒否エラー	「トランザクションがキャンセルされました」というメッセージを表示します

アンチパターン

非推奨の aptos npm パッケージは絶対に使用しないでください — @aptos-labs/ts-sdk を使用します
送信後に waitForTransaction を絶対に省略しないでください — トランザクションがまだコミットされていない可能性があります
モジュールアドレスを絶対にハードコードしないでください — 環境変数（VITE_MODULE_ADDRESS）を使用します
Aptos クライアントのインスタンスを複数作成しないでください — シングルトンを1つ作成し、共有します
実ユーザー向けのフロントエンドコードでは Account.generate() を絶対に使用しないでください — ウォレットアダプターを使用します
scriptComposer は絶対に使用しないでください — v6.0 で削除されました。代わりに個別のトランザクションを使用します
getAccountCoinAmount または getAccountAPTAmount は絶対に使用しないでください — 非推奨です。getBalance() を使用します

SDK のバージョンに関する注意事項

AIP-80 秘密鍵形式（v2.0+）

Ed25519 および Secp256k1 の秘密鍵は、toString() でシリアライズする際に、AIP-80 のプレフィックス付き形式を使用するようになりました。

const key = new Ed25519PrivateKey("0x...");
key.toString(); // Returns AIP-80 prefixed format, NOT raw hex

代替可能資産の転送（v1.39+）

await aptos.transferFungibleAssetBetweenStores({
  sender: account,
  fungibleAssetMetadataAddress: metadataAddr,
  senderStoreAddress: fromStore,
  recipientStoreAddress: toStore,
  amount: 1000n
});

アカウント抽象化（v1.34+、AIP-104）

// Check if AA is enabled for an account
const isEnabled = await aptos.abstraction.isAccountAbstractionEnabled({
  accountAddress: "0x...",
  authenticationFunction: `${MODULE_ADDRESS}::auth::authenticate`
});

// Enable AA on an account
const enableTxn = await aptos.abstraction.enableAccountAbstractionTransaction({
  accountAddress: account.accountAddress,
  authenticationFunction: `${MODULE_ADDRESS}::auth::authenticate`
});

// Use AbstractedAccount for signing with custom auth logic
import { AbstractedAccount } from "@aptos-labs/ts-sdk";

参考資料

パターンのドキュメント：

TYPESCRIPT_SDK.md — SDK API の完全なリファレンス

公式ドキュメント：

TypeScript SDK：https://aptos.dev/build/sdks/ts-sdk
API リファレンス：https://aptos-labs.github.io/aptos-ts-sdk/
ウォレットアダプター：https://aptos.dev/build/sdks/wallet-adapter/dapp
GitHub：https://github.com/aptos-labs/aptos-ts-sdk

詳細スキル：

ts-sdk-client — クライアントのセットアップと設定
ts-sdk-account — アカウント／署名者の作成
ts-sdk-address — アドレスの解析と導出
ts-sdk-transactions — トランザクションの構築、署名、送信
ts-sdk-view-and-query — ビュー関数とクエリ
ts-sdk-types — Move から TypeScript への型のマッピング
ts-sdk-wallet-adapter — React ウォレット統合

関連スキル：

write-contracts — この SDK が連携する Move コントラクトを作成します
deploy-contracts — TypeScript から呼び出す前にコントラクトをデプロイします

Markdown 対応

ログインしてコメント

基本情報

作者: aptos-labs
リポジトリ: aptos-labs/aptos-agent-skills
カテゴリ: 開発
インストール数: 71
GitHub スター: 20

問題を報告