contract

合约技能

提供在 Stacks 区块链上部署和交互 Clarity 智能合约的功能。可从 .clar 源文件部署合约、调用公开函数（可选设置后置条件），并调用只读函数查询链上状态。

• read — 只读，无需钱包。
• deploy 和 call — 写入操作，会广播交易；需要已解锁的钱包。

用法

bun run contract/contract.ts <subcommand> [options]

子命令

deploy

在 Stacks 区块链上部署 Clarity 智能合约。从 .clar 文件读取合约源代码，并广播 smart_contract 交易。

bun run contract/contract.ts deploy \
  --source <path-to-file.clar> \
  --name <contract-name> \
  [--fee <fee>]

选项：

• --source（必填）— 要部署的 .clar 源文件路径
• --name（必填）— 合约名称（小写，可使用连字符，最多 128 个字符）
• --fee（可选）— 费用预设（low|medium|high）或 micro-STX 金额；若省略则自动估算

输出：

{
  "success": true,
  "txid": "abc123...",
  "contractId": "SP2...deployer.my-contract",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet"
}

call

调用已部署的 Stacks 智能合约中的公开函数。对 contract_call 交易进行签名并广播。

bun run contract/contract.ts call \
  --contract <contractId> \
  --function <functionName> \
  --args <json-array> \
  [--post-condition-mode <deny|allow>] \
  [--post-conditions <json-array>] \
  [--fee <fee>]

选项：

• --contract（必填）— ADDRESS.contract-name 格式的完整合约 ID
• --function（必填）— 要调用的公开函数名称
• --args（可选）— JSON 数组格式的函数参数（默认：[]）。类型化对象使用 {"type":"uint","value":100} 格式。
• --post-condition-mode（可选）— deny（默认）会阻止意外的代币转移；allow 则允许任何转移
• --post-conditions（可选）— JSON 数组格式的后置条件（格式请参阅“备注”）
• --fee（可选）— 费用预设（low|medium|high）或 micro-STX 金额；若省略则自动估算

输出：

{
  "success": true,
  "txid": "abc123...",
  "contract": "SP2...deployer.my-contract",
  "function": "set-value",
  "args": [42],
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet"
}

read

调用已部署的 Stacks 智能合约中的只读函数。不会广播交易；无需钱包。

bun run contract/contract.ts read \
  --contract <contractId> \
  --function <functionName> \
  [--args <json-array>] \
  [--sender <address>]

选项：

• --contract（必填）— ADDRESS.contract-name 格式的完整合约 ID
• --function（必填）— 要调用的只读函数名称
• --args（可选）— JSON 数组格式的函数参数（默认：[]）
• --sender（可选）— 用作只读调用发送方的 Stacks 地址（若省略，则使用当前钱包地址）

输出：

{
  "contract": "SP2...deployer.my-contract",
  "function": "get-value",
  "okay": true,
  "result": "(ok u42)",
  "network": "mainnet"
}

参数

子命令	选项	必填	描述
deploy	--source	是	.clar 源文件路径
deploy	--name	是	合约名称
deploy	--fee	否	费用预设或 micro-STX 金额
call	--contract	是	完整合约 ID（ADDRESS.name）
call	--function	是	公开函数名称
call	--args	否	JSON 数组格式的函数参数
call	--post-condition-mode	否	deny（默认）或 allow
call	--post-conditions	否	JSON 数组格式的后置条件对象
call	--fee	否	费用预设或 micro-STX 金额
read	--contract	是	完整合约 ID（ADDRESS.name）
read	--function	是	只读函数名称
read	--args	否	JSON 数组格式的函数参数
read	--sender	否	只读调用的发送方地址

注意事项

• 合约名称对于每个部署者地址都必须唯一。部署已存在的合约会失败。
• 部署不可撤销——确认后，合约将永久存在于链上。
• 在部署或调用前，先在 stxer.xyz 上模拟合约调用，以便发现 Clarity 错误并估算费用，且无需花费 STX。
• 后置条件格式：STX 使用 {"type":"stx","principal":"SP2...","conditionCode":"eq","amount":"1000000"}；同质化代币使用 {"type":"ft","principal":"SP2...","asset":"SP2....my-token","assetName":"my-token","conditionCode":"eq","amount":"100"}；NFT 使用 {"type":"nft","principal":"SP2...","asset":"SP2....my-nft","assetName":"my-nft","tokenId":1}——NFT 条件是二元的（发送/不发送），因此不适用 conditionCode；使用 "notSend":true 可断言 NFT 不得离开该主体。
• --post-condition-mode allow 会完全跳过后置条件检查——仅当你完全信任合约逻辑并已验证源代码时才使用。
• 钱包操作需要已解锁的钱包（请先运行 bun run wallet/wallet.ts unlock --password <password>）。