clarity-check

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clarity Check Skill

Pre-deployment validation gate for Clarity smart contracts. Runs automated checks for syntax errors, deprecated keywords, incorrect sender checks, error propagation issues, and missing tests. Pairs with the existing

contract

skill for deploy operations.

Clarity智能合约的预部署验证关卡。自动运行语法错误、废弃关键词、错误发送者校验、错误传播问题及缺失测试的检查。可与现有

contract

skill配合完成部署操作。

Usage

使用说明

This is a doc-only skill. Agents read this file to understand available checks and invoke them through the skill framework. The CLI interface below documents the planned implementation.

bun run clarity-check/clarity-check.ts <subcommand> [options]

这是一个纯文档型Skill。Agents可读取此文件了解可用的检查项，并通过技能框架调用它们。以下CLI接口记录了规划中的实现方案。

bun run clarity-check/clarity-check.ts <subcommand> [options]

Subcommands

子命令

validate

Run all automated checks against a Clarity contract file.

bun run clarity-check/clarity-check.ts validate --source <path-to-file.clar> [--project-dir <clarinet-project-dir>]

Options:

```
--source
```
(required) — Path to the
```
.clar
```
source file to validate
```
--project-dir
```
(optional) — Clarinet project directory for
```
clarinet check
```
integration; auto-detected from source path if omitted

Output:

json

{
  "file": "contracts/my-contract.clar",
  "passed": false,
  "checks": [
    {
      "name": "syntax",
      "status": "pass",
      "description": "clarinet check passes"
    },
    {
      "name": "deprecated-keywords",
      "status": "fail",
      "description": "Deprecated keywords found",
      "findings": [
        {
          "line": 15,
          "keyword": "block-height",
          "replacement": "stacks-block-height",
          "severity": "warning"
        }
      ]
    },
    {
      "name": "sender-checks",
      "status": "warn",
      "description": "Sender check analysis",
      "findings": [
        {
          "line": 22,
          "issue": "Token transfer uses contract-caller instead of tx-sender",
          "recommendation": "Use tx-sender for token operations to preserve human identity through proxies",
          "severity": "warning"
        }
      ]
    }
  ],
  "summary": {
    "total": 7,
    "pass": 5,
    "fail": 1,
    "warn": 1
  }
}

对Clarity合约文件运行所有自动化检查。

bun run clarity-check/clarity-check.ts validate --source <path-to-file.clar> [--project-dir <clarinet-project-dir>]

选项：

```
--source
```
（必填）—— 待验证的
```
.clar
```
源文件路径
```
--project-dir
```
（可选）—— 用于集成
```
clarinet check
```
的Clarinet项目目录；若省略，将从源文件路径自动检测

输出：

json

{
  "file": "contracts/my-contract.clar",
  "passed": false,
  "checks": [
    {
      "name": "syntax",
      "status": "pass",
      "description": "clarinet check passes"
    },
    {
      "name": "deprecated-keywords",
      "status": "fail",
      "description": "Deprecated keywords found",
      "findings": [
        {
          "line": 15,
          "keyword": "block-height",
          "replacement": "stacks-block-height",
          "severity": "warning"
        }
      ]
    },
    {
      "name": "sender-checks",
      "status": "warn",
      "description": "Sender check analysis",
      "findings": [
        {
          "line": 22,
          "issue": "Token transfer uses contract-caller instead of tx-sender",
          "recommendation": "Use tx-sender for token operations to preserve human identity through proxies",
          "severity": "warning"
        }
      ]
    }
  ],
  "summary": {
    "total": 7,
    "pass": 5,
    "fail": 1,
    "warn": 1
  }
}

checklist

Generate a human-readable pre-deployment checklist for a contract, combining automated checks with manual verification items.

bun run clarity-check/clarity-check.ts checklist --source <path-to-file.clar> [--project-dir <clarinet-project-dir>]

Options:

```
--source
```
(required) — Path to the
```
.clar
```
source file
```
--project-dir
```
(optional) — Clarinet project directory

Output:

json

{
  "file": "contracts/my-contract.clar",
  "automated": [
    {"check": "clarinet check passes", "status": "pass"},
    {"check": "No deprecated keywords", "status": "fail", "details": "Found: block-height on line 15"},
    {"check": "Correct sender checks", "status": "warn", "details": "1 finding"},
    {"check": "Error propagation uses try!", "status": "pass"},
    {"check": "No dead code or unused features", "status": "pass"},
    {"check": "Events follow structured format", "status": "pass"},
    {"check": "Error codes are unique", "status": "pass"}
  ],
  "manual": [
    "Verify tests exist and pass (npm test)",
    "Check execution costs in clarinet console (::get_costs)",
    "Review post-conditions for all token operations",
    "Verify trait whitelisting if external contracts are called",
    "Test on testnet before mainnet deployment",
    "Document contract address after deployment"
  ]
}

为合约生成易读的预部署检查清单，结合自动化检查项与人工验证项。

bun run clarity-check/clarity-check.ts checklist --source <path-to-file.clar> [--project-dir <clarinet-project-dir>]

选项：

```
--source
```
（必填）——
```
.clar
```
源文件路径
```
--project-dir
```
（可选）—— Clarinet项目目录

输出：

json

{
  "file": "contracts/my-contract.clar",
  "automated": [
    {"check": "clarinet check passes", "status": "pass"},
    {"check": "No deprecated keywords", "status": "fail", "details": "Found: block-height on line 15"},
    {"check": "Correct sender checks", "status": "warn", "details": "1 finding"},
    {"check": "Error propagation uses try!", "status": "pass"},
    {"check": "No dead code or unused features", "status": "pass"},
    {"check": "Events follow structured format", "status": "pass"},
    {"check": "Error codes are unique", "status": "pass"}
  ],
  "manual": [
    "Verify tests exist and pass (npm test)",
    "Check execution costs in clarinet console (::get_costs)",
    "Review post-conditions for all token operations",
    "Verify trait whitelisting if external contracts are called",
    "Test on testnet before mainnet deployment",
    "Document contract address after deployment"
  ]
}

Checks Performed

执行的检查项

Automated

自动化检查

Check	What it detects
Syntax	`clarinet check` errors and warnings
Deprecated keywords	`block-height` (use `stacks-block-height` ), other legacy keywords
Sender checks	`tx-sender` vs `contract-caller` misuse in token operations
Error propagation	`unwrap!` used where `try!` is more appropriate for recoverable errors
Dead code	Unused private functions, unreachable branches
Event format	Events missing `notification` / `payload` structure
Error code uniqueness	Duplicate error code constants
Public function returns	Functions missing `(response ok err)` return type

检查项	检测内容
语法检查	`clarinet check` 检测到的错误与警告
废弃关键词	`block-height` （应使用 `stacks-block-height` ）及其他旧版关键词
发送者校验	代币操作中 `tx-sender` 与 `contract-caller` 的误用
错误传播	在可恢复错误场景下使用 `unwrap!` 而非更合适的 `try!`
死代码	未使用的私有函数、不可达分支
事件格式	缺少 `notification` / `payload` 结构的事件
错误码唯一性	重复的错误码常量
公共函数返回值	未使用 `(response ok err)` 返回类型的函数

Manual (Checklist Only)

人工检查（仅清单包含）

Check	Why it matters
Tests exist and pass	Ensures behavior is verified
Execution costs	Prevents exceeding block limits
Post-conditions	Protects users from unexpected token transfers
Trait whitelisting	Prevents unauthorized contract interactions
Testnet deployment	Catches issues before mainnet

检查项	重要性
测试存在且通过	确保合约行为符合预期
执行成本检查	避免超出区块限制
后置条件审查	保护用户免受意外代币转账影响
特征白名单验证	防止未授权的合约交互
测试网部署	在主网部署前发现问题

Notes

注意事项

Requires
```
clarinet
```
CLI installed locally for syntax checking
If
```
clarinet
```
is not found, syntax check is skipped with a warning
Static analysis only — does not execute the contract or run tests
Use
```
clarity-test-scaffold
```
to generate tests, then
```
clarity-audit
```
for deep review
Complements
```
clarinet check
```
by adding Clarity-specific best practice checks that the compiler doesn't enforce

语法检查需本地安装
```
clarinet
```
CLI
若未找到
```
clarinet
```
，语法检查将被跳过并发出警告
仅执行静态分析——不会运行合约或测试
使用
```
clarity-test-scaffold
```
生成测试，再通过
```
clarity-audit
```
进行深度审查
通过添加Clarity专属最佳实践检查（编译器未强制要求），补充
```
clarinet check
```
的能力