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 (由 Bitcoin 保障)
语言	TypeScript

---

许可证

MIT — 见 LICENSE