clarity-check

Clarity 检查技能

Clarity 智能合约部署前的验证关卡。自动检查语法错误、已弃用关键字、不正确的发送方检查、错误传播问题和缺失的测试。与现有的 contract 技能搭配使用，完成部署操作。

用法

这是一项仅包含文档的技能。Agent 会读取此文件，了解可用的检查项，并通过技能框架调用这些检查。下面的 CLI 接口说明了计划中的实现。

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

子命令

validate

对 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 项目目录；若省略，则根据源文件路径自动检测

输出：

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

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

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

选项：

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

输出：

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

执行的检查

自动检查

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

人工检查（仅限检查清单）

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

备注

• 语法检查需要在本地安装 clarinet CLI
• 如果找不到 clarinet，将跳过语法检查并发出警告
• 仅进行静态分析——不会执行合约或运行测试
• 使用 clarity-test-scaffold 生成测试，然后使用 clarity-audit 进行深入审查
• 通过添加编译器不会强制执行的 Clarity 专属最佳实践检查，对 clarinet check 进行补充