contract

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Contract Skill

合约工具

Provides Clarity smart contract deployment and interaction on the Stacks blockchain. Deploy contracts from

.clar

source files, call public functions (with optional post conditions), and call read-only functions to query on-chain state.

read — Read-only, no wallet required.
deploy and call — Write operations that broadcast transactions; require an unlocked wallet.

在Stacks区块链上提供Clarity智能合约的部署与交互功能。支持从

.clar

源文件部署合约，调用（可带后置条件的）公共函数，以及调用只读函数查询链上状态。

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

Usage

使用方法

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

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

Subcommands

子命令

deploy

Deploy a Clarity smart contract to the Stacks blockchain. Reads the contract source from a

.clar

file and broadcasts a

smart_contract

transaction.

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

Options:

```
--source
```
(required) — Path to the
```
.clar
```
source file to deploy
```
--name
```
(required) — Contract name (lowercase, hyphens allowed, max 128 chars)
```
--fee
```
(optional) — Fee preset (
```
low|medium|high
```
) or micro-STX amount; auto-estimated if omitted

Output:

json

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

将Clarity智能合约部署到Stacks区块链。从

.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金额；若省略则自动估算

输出：

json

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

call

Call a public function on a deployed Stacks smart contract. Signs and broadcasts a

contract_call

transaction.

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

Options:

```
--contract
```
(required) — Full contract ID in
```
ADDRESS.contract-name
```
format
```
--function
```
(required) — Public function name to call
```
--args
```
(optional) — Function arguments as a JSON array (default:
```
[]
```
). Typed objects use
```
{"type":"uint","value":100}
```
format.
```
--post-condition-mode
```
(optional) —
```
deny
```
(default) blocks unexpected token transfers;
```
allow
```
permits any
```
--post-conditions
```
(optional) — Post conditions as a JSON array (see Notes for format)
```
--fee
```
(optional) — Fee preset (
```
low|medium|high
```
) or micro-STX amount; auto-estimated if omitted

Output:

json

{
  "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"
}

调用已部署在Stacks区块链上的Clarity智能合约的公共函数。签名并广播

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
```
（必填）—— 完整合约ID，格式为
```
ADDRESS.contract-name
```
```
--function
```
（必填）—— 要调用的公共函数名称
```
--args
```
（可选）—— 函数参数，为JSON数组（默认值：
```
[]
```
）。带类型的对象使用
```
{"type":"uint","value":100}
```
格式。
```
--post-condition-mode
```
（可选）——
```
deny
```
（默认值）会阻止意外的代币转账；
```
allow
```
允许任意转账
```
--post-conditions
```
（可选）—— 后置条件，为JSON数组（格式见注意事项）
```
--fee
```
（可选）—— 手续费预设值（
```
low|medium|high
```
）或micro-STX金额；若省略则自动估算

输出：

json

{
  "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

Call a read-only function on a deployed Stacks smart contract. Does not broadcast a transaction; no wallet required.

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

Options:

```
--contract
```
(required) — Full contract ID in
```
ADDRESS.contract-name
```
format
```
--function
```
(required) — Read-only function name to call
```
--args
```
(optional) — Function arguments as a JSON array (default:
```
[]
```
)
```
--sender
```
(optional) — Stacks address to use as the read-only call sender (uses active wallet address if omitted)

Output:

json

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

调用已部署在Stacks区块链上的Clarity智能合约的只读函数。不会广播交易；无需钱包。

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

选项：

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

输出：

json

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

Arguments

参数说明

Subcommand	Option	Required	Description
`deploy`	`--source`	yes	Path to `.clar` source file
`deploy`	`--name`	yes	Contract name
`deploy`	`--fee`	no	Fee preset or micro-STX amount
`call`	`--contract`	yes	Full contract ID ( `ADDRESS.name` )
`call`	`--function`	yes	Public function name
`call`	`--args`	no	JSON array of function arguments
`call`	`--post-condition-mode`	no	`deny` (default) or `allow`
`call`	`--post-conditions`	no	JSON array of post condition objects
`call`	`--fee`	no	Fee preset or micro-STX amount
`read`	`--contract`	yes	Full contract ID ( `ADDRESS.name` )
`read`	`--function`	yes	Read-only function name
`read`	`--args`	no	JSON array of function arguments
`read`	`--sender`	no	Sender address for the read-only call

子命令	选项	是否必填	描述
`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`	否	只读调用的发送方地址

Notes

注意事项

Contract names must be unique per deployer address. Deploying a contract that already exists will fail.
Deployment is irreversible — the contract lives on-chain permanently once confirmed.
Pre-simulate contract calls on stxer.xyz before deploying or calling to catch Clarity errors and estimate fees without spending STX.

Post condition format:

{"type":"stx","principal":"SP2...","conditionCode":"eq","amount":"1000000"}

for STX;

{"type":"ft","principal":"SP2...","asset":"SP2....my-token","assetName":"my-token","conditionCode":"eq","amount":"100"}

for fungible tokens;

{"type":"nft","principal":"SP2...","asset":"SP2....my-nft","assetName":"my-nft","tokenId":1}

for NFTs — NFT conditions are binary (send/not-send), so

conditionCode

is not applicable; use

"notSend":true

to assert the NFT must NOT leave the principal.

```
--post-condition-mode allow
```
skips post condition checks entirely — use only when you fully trust the contract logic and have verified the source code.
Wallet operations require an unlocked wallet (use
```
bun run wallet/wallet.ts unlock --password <password>
```
first).

每个部署者地址下的合约名称必须唯一。部署已存在的合约会失败。
部署操作不可逆——合约一旦确认就会永久存在于链上。
在部署或调用合约前，可在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>

）。