Earnwithalee7890/stx-contract-deployment-hiro

stx-contract-deployment-hiro は何をしますか？

Clarityスマートコントラクトコレクション + Stacksブロックチェーン向けプレミアムSDK Stacksスマートコントラクトのデプロイ、操作、監視 — ウォレット検出、残高照会、Clarityエンコード、完全なコントラクト呼び出しサポートを、すべて1つのパッケージで提供します。

GitHub · NPM — @earnwithalee/stx-contract

---

このスキルで学べること

このスキルでは以下をカバーします：

• Stacksメインネット/テストネットでのClarityスマートコントラクトのデプロイと操作
• 型付きコントラクト呼び出しのための**@earnwithalee/stx-contract** SDKの使用
• Leather、XverseなどのStacksウォレットのウォレット検出と接続
• 残高、トランザクション、ブロック高、コントラクトデータなどのオンチェーン状態の読み取り
• 純粋なJavaScript/TypeScriptでのClarity値のエンコード
• リアルタイムオンチェーンイベントストリーミングのためのChainhookセットアップ
• メインネットデプロイ前のClarinetによるコントラクトテスト

---

推奨ツール

• 検索: ripgrep — リポジトリ内の高速コード検索
• デプロイ: Acme Deploy — Vercelへのデプロイ
• フォーマット: prettier — コードフォーマット (npm run format)
• リンター: eslint — 静的解析 (npm run lint)
• コントラクト: Clarinet — ローカルのClarityテストとデプロイ
• エクスプローラー: Hiro Explorer — デプロイされたコントラクトのオンチェーン確認
• ランタイム: Node.js >= 18
• ブロックチェーン: Stacks — Bitcoinで保護されたL2

---

インストール

npm install @earnwithalee/stx-contract
# または
yarn add @earnwithalee/stx-contract
# または
pnpm add @earnwithalee/stx-contract

---

クイックスタート

import { StxContractClient } from '@earnwithalee/stx-contract';

const client = new StxContractClient({ network: 'mainnet' });

---

ウォレット接続

import sdk from '@earnwithalee/stx-contract';

// ウォレット接続（Leather / Xverse自動検出）
const address = await sdk.wallet.connectWallet();
console.log('接続:', address);

// ウォレットプロバイダーの検出
const { available, provider } = sdk.wallet.detectWallet();

// アドレスを表示用にフォーマット
const short = sdk.wallet.formatAddress(address); // "SP2F...NFBT"

---

オンチェーンデータ — 残高とトランザクション

import sdk from '@earnwithalee/stx-contract';

// STX残高の取得
const balance = await sdk.api.getBalance('SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT');
console.log('残高:', balance.stx, 'STX');

// トランザクション履歴の取得
const txs = await sdk.api.getTransactions('SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT');

// 現在のブロック高の取得
const height = await sdk.api.getBlockHeight();

// トランザクションステータスの確認
const status = await sdk.api.getTransactionStatus('0xabc...');

// コントラクトの読み取り専用関数を実行
const result = await sdk.api.readContract({
  contractAddress: 'SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT',
  contractName: 'builder-rewards-v3',
  functionName: 'get-total-fees-collected',
  functionArgs: [],
});

---

Clarity値のエンコード

import sdk from '@earnwithalee/stx-contract';

// コントラクト呼び出し用に様々なClarity型をエンコード
const asciiStr  = sdk.encoding.encodeStringAscii('hello');
const uint256   = sdk.encoding.encodeUint(1000000n);
const principal = sdk.encoding.encodePrincipal('SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT');
const boolVal   = sdk.encoding.encodeBool(true);
const buff      = sdk.encoding.encodeBuffer(Buffer.from('deadbeef', 'hex'));

---

コントラクト関数の呼び出し（書き込み）

import sdk from '@earnwithalee/stx-contract';
import { AnchorMode, PostConditionMode } from '@stacks/transactions';

const txId = await sdk.contract.callPublic({
  contractAddress: 'SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT',
  contractName: 'builder-rewards-v3',
  functionName: 'register-builder',
  functionArgs: [
    sdk.encoding.encodePrincipal('SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT'),
  ],
  anchorMode: AnchorMode.Any,
  postConditionMode: PostConditionMode.Allow,
  network: 'mainnet',
});

console.log('TX送信:', txId);

---

Clarityコントラクトのデプロイ（Clarinet）

# Clarinet CLIのインストール
brew install hirosystems/tap/clarinet   # macOS
# または https://github.com/hirosystems/clarinet/releases からダウンロード

# プロジェクトの初期化
clarinet new my-contract && cd my-contract

# 新しいコントラクトの作成
clarinet contract new my-token

# チェックとテスト
clarinet check
clarinet test

# テストネットにデプロイ
clarinet deployments generate --testnet
clarinet deployments apply --testnet

# メインネットにデプロイ
clarinet deployments generate --mainnet
clarinet deployments apply --mainnet

---

Chainhook — リアルタイムオンチェーンイベントストリーミング

// chainhooks/builder-event.json
{
  "name": "builder-registered",
  "version": 1,
  "chain": "stacks",
  "networks": {
    "mainnet": {
      "start_block": 150000,
      "predicate": {
        "scope": "contract_call",
        "contract_identifier": "SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT.builder-rewards-v3",
        "method": "register-builder"
      },
      "expire_after_occurrence": null
    }
  }
}

---

Clarityコントラクトの例

;; builder-rewards-v3.clar
(define-map builder-scores principal uint)

(define-public (register-builder (builder principal))
  (begin
    (asserts! (is-eq tx-sender CONTRACT_OWNER) (err u403))
    (map-set builder-scores builder u0)
    (ok true)
  )
)

(define-read-only (get-score (builder principal))
  (default-to u0 (map-get? builder-scores builder))
)

(define-public (increment-score (builder principal) (points uint))
  (let ((current (get-score builder)))
    (map-set builder-scores builder (+ current points))
    (ok (+ current points))
  )
)

---

ローカル実行

git clone https://github.com/Earnwithalee7890/stx-contract-deployment-hiro.git
cd stx-contract-deployment-hiro
npm install
cp .env.example .env    # STX_PRIVATE_KEY と HIRO_API_KEY を設定
npm run dev             # Next.js開発サーバー起動

---

環境変数

# .env.example
STX_NETWORK=mainnet                          # mainnet | testnet
STX_PRIVATE_KEY=your_private_key_here
HIRO_API_KEY=your_hiro_api_key               # https://platform.hiro.so
NEXT_PUBLIC_CONTRACT_ADDRESS=SP2F500B8DTRK1EANJQ054BRAB8DDKN6QCMXGNFBT

---

技術スタック

レイヤー	技術
SDK	@earnwithalee/stx-contract (npm)
フレームワーク	Next.js（App Router）
スマートコントラクト	Clarity（Stacksメインネット）
テスト	Clarinet + Vitest
ウォレット	Leather、Xverse（プロバイダーインジェクション）
チェーンAPI	Hiro Extended API v1
ブロックチェーン	Stacks L2（Bitcoinで保護）
言語	TypeScript

---

ライセンス

MIT — LICENSE を参照