stx-contract-deployment-hiro

stx-contract-deployment-hiro 是做什麼的？

Clarity 智能合約集合 + 適用於 Stacks 區塊鏈的進階 SDK。 部署、互動與監控 Stacks 智能合約 — 錢包偵測、餘額查詢、Clarity 編碼與完整的合約呼叫支援，全部整合在一個套件中。

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 — 由比特幣保護的 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('交易已提交：', 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 (provider injection)
鏈 API	Hiro Extended API v1
區塊鏈	Stacks L2 (由比特幣保護)
語言	TypeScript

---

授權條款

MIT — 請參閱 LICENSE