clarity-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clarity Audit Skill

Structured security audit for Clarity smart contracts. Produces a comprehensive review covering correctness, security vulnerabilities, design concerns, and deployment readiness. Designed to work both as a standalone skill (structured JSON output) and as the foundation for the

clarity-expert

agent (open-ended reasoning).

针对Clarity智能合约的结构化安全审计。生成涵盖正确性、安全漏洞、设计问题与部署就绪性的全面评审报告。可作为独立Skill（输出结构化JSON）使用，也可作为

clarity-expert

agent（开放式推理）的基础。

Usage

使用方法

This is a doc-only skill. Agents read this file to understand the audit framework and invoke it through the skill framework or

clarity-expert

agent. The CLI interface below documents the planned implementation.

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

这是一个纯文档类Skill。Agents可读取此文件以理解审计框架，并通过Skill框架或

clarity-expert

agent调用它。以下CLI接口记录了规划中的实现方案。

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

Subcommands

子命令

audit

Run a full structured audit on a Clarity contract.

bun run clarity-audit/clarity-audit.ts audit --source <path-to-file.clar> [--contract-id <deployed-contract-id>] [--severity-threshold <level>]

Options:

```
--source
```
(required) — Path to the
```
.clar
```
source file to audit
```
--contract-id
```
(optional) — Deployed contract ID for on-chain verification; enables cross-referencing deployed vs source
```
--severity-threshold
```
(optional) — Minimum severity to report:
```
critical
```
,
```
high
```
,
```
medium
```
,
```
low
```
(default:
```
low
```
)

Output:

json

{
  "file": "contracts/my-contract.clar",
  "summary": "Token transfer contract with admin controls and minting capability",
  "verdict": "CONDITIONAL_PASS",
  "riskLevel": "MEDIUM",
  "stats": {
    "publicFunctions": 5,
    "readOnlyFunctions": 3,
    "privateFunctions": 2,
    "maps": 2,
    "dataVars": 1,
    "constants": 8
  },
  "whatWorksCorrectly": [
    "Transfer function uses try! for error propagation",
    "Admin functions check tx-sender against owner constant",
    "Events follow structured notification/payload format"
  ],
  "bugs": [
    {
      "severity": "high",
      "title": "Unbounded mint allows infinite token supply",
      "location": {"function": "mint", "line": 45},
      "description": "The mint function has no supply cap check. Any admin can mint unlimited tokens.",
      "recommendation": "Add MAX_SUPPLY constant and check (< (+ current-supply amount) MAX_SUPPLY) before minting",
      "category": "logic"
    }
  ],
  "designConcerns": [
    {
      "severity": "medium",
      "title": "Single admin with no succession plan",
      "description": "CONTRACT_OWNER is set at deploy time with no transfer mechanism",
      "recommendation": "Add set-admin function with two-step transfer (propose + accept)"
    }
  ],
  "gasAnalysis": {
    "mostExpensiveFunction": "batch-transfer",
    "concern": "fold over list of 200 recipients may approach block limits"
  }
}

对Clarity合约执行完整的结构化审计。

bun run clarity-audit/clarity-audit.ts audit --source <path-to-file.clar> [--contract-id <deployed-contract-id>] [--severity-threshold <level>]

选项：

```
--source
```
（必填）——待审计的
```
.clar
```
源文件路径
```
--contract-id
```
（可选）——已部署合约的ID，用于链上验证；支持对比已部署版本与源文件的差异
```
--severity-threshold
```
（可选）——报告的最低问题级别：
```
critical
```
、
```
high
```
、
```
medium
```
、
```
low
```
（默认值：
```
low
```
）

输出：

json

{
  "file": "contracts/my-contract.clar",
  "summary": "Token transfer contract with admin controls and minting capability",
  "verdict": "CONDITIONAL_PASS",
  "riskLevel": "MEDIUM",
  "stats": {
    "publicFunctions": 5,
    "readOnlyFunctions": 3,
    "privateFunctions": 2,
    "maps": 2,
    "dataVars": 1,
    "constants": 8
  },
  "whatWorksCorrectly": [
    "Transfer function uses try! for error propagation",
    "Admin functions check tx-sender against owner constant",
    "Events follow structured notification/payload format"
  ],
  "bugs": [
    {
      "severity": "high",
      "title": "Unbounded mint allows infinite token supply",
      "location": {"function": "mint", "line": 45},
      "description": "The mint function has no supply cap check. Any admin can mint unlimited tokens.",
      "recommendation": "Add MAX_SUPPLY constant and check (< (+ current-supply amount) MAX_SUPPLY) before minting",
      "category": "logic"
    }
  ],
  "designConcerns": [
    {
      "severity": "medium",
      "title": "Single admin with no succession plan",
      "description": "CONTRACT_OWNER is set at deploy time with no transfer mechanism",
      "recommendation": "Add set-admin function with two-step transfer (propose + accept)"
    }
  ],
  "gasAnalysis": {
    "mostExpensiveFunction": "batch-transfer",
    "concern": "fold over list of 200 recipients may approach block limits"
  }
}

quick-check

Run a lightweight scan focused on critical and high severity issues only.

bun run clarity-audit/clarity-audit.ts quick-check --source <path-to-file.clar>

Options:

```
--source
```
(required) — Path to the
```
.clar
```
source file

Output:

json

{
  "file": "contracts/my-contract.clar",
  "criticalIssues": 0,
  "highIssues": 1,
  "quickVerdict": "REVIEW_NEEDED",
  "findings": [
    {
      "severity": "high",
      "title": "Unbounded mint allows infinite token supply",
      "line": 45,
      "fix": "Add MAX_SUPPLY cap"
    }
  ]
}

执行轻量级扫描，仅聚焦于critical和high级别的问题。

bun run clarity-audit/clarity-audit.ts quick-check --source <path-to-file.clar>

选项：

```
--source
```
（必填）——待审计的
```
.clar
```
源文件路径

输出：

json

{
  "file": "contracts/my-contract.clar",
  "criticalIssues": 0,
  "highIssues": 1,
  "quickVerdict": "REVIEW_NEEDED",
  "findings": [
    {
      "severity": "high",
      "title": "Unbounded mint allows infinite token supply",
      "line": 45,
      "fix": "Add MAX_SUPPLY cap"
    }
  ]
}

function-review

Audit a single function in detail with color-coded risk assessment.

bun run clarity-audit/clarity-audit.ts function-review --source <path-to-file.clar> --function <function-name>

Options:

```
--source
```
(required) — Path to the
```
.clar
```
source file
```
--function
```
(required) — Function name to review

Output:

json

{
  "function": "transfer",
  "visibility": "public",
  "riskColor": "ORANGE",
  "riskReason": "Token transfer with external call",
  "parameters": [
    {"name": "amount", "type": "uint", "validated": true},
    {"name": "to", "type": "principal", "validated": false}
  ],
  "checks": [
    {"check": "Input validation", "status": "partial", "detail": "amount checked but recipient not validated"},
    {"check": "Proper sender check", "status": "pass", "detail": "Uses tx-sender correctly"},
    {"check": "Error propagation", "status": "pass", "detail": "Uses try! for ft-transfer?"},
    {"check": "Post-condition safe", "status": "warn", "detail": "No post-condition hints in contract"},
    {"check": "Reentrancy safe", "status": "pass", "detail": "State changes before external calls"}
  ],
  "recommendation": "Add recipient validation (not contract principal) if transfers should be restricted to standard principals"
}

对单个函数进行详细审计，并通过颜色标记风险等级。

bun run clarity-audit/clarity-audit.ts function-review --source <path-to-file.clar> --function <function-name>

选项：

```
--source
```
（必填）——待审计的
```
.clar
```
源文件路径
```
--function
```
（必填）——待评审的函数名称

输出：

json

{
  "function": "transfer",
  "visibility": "public",
  "riskColor": "ORANGE",
  "riskReason": "Token transfer with external call",
  "parameters": [
    {"name": "amount", "type": "uint", "validated": true},
    {"name": "to", "type": "principal", "validated": false}
  ],
  "checks": [
    {"check": "Input validation", "status": "partial", "detail": "amount checked but recipient not validated"},
    {"check": "Proper sender check", "status": "pass", "detail": "Uses tx-sender correctly"},
    {"check": "Error propagation", "status": "pass", "detail": "Uses try! for ft-transfer?"},
    {"check": "Post-condition safe", "status": "warn", "detail": "No post-condition hints in contract"},
    {"check": "Reentrancy safe", "status": "pass", "detail": "State changes before external calls"}
  ],
  "recommendation": "Add recipient validation (not contract principal) if transfers should be restricted to standard principals"
}

Risk Color Framework

风险颜色框架

Color	Meaning	Examples
GREEN	Harmless read-only	`get-balance` , `get-stats`
YELLOW	State changes with proper guards	`check-in` with auth, `vote` with snapshot
ORANGE	Token transfers, external calls	`transfer` , `swap` , any `contract-call?`
RED	Critical — admin functions, treasury access	`withdraw` , `mint` , `set-admin` , `upgrade`

颜色	含义	示例
绿色	无害的只读函数	`get-balance` 、 `get-stats`
黄色	带有防护机制的状态变更函数	带权限验证的 `check-in` 、带快照的 `vote`
橙色	代币转账、外部调用函数	`transfer` 、 `swap` 、任何 `contract-call?`
红色	关键函数——管理员操作、金库访问	`withdraw` 、 `mint` 、 `set-admin` 、 `upgrade`

Audit Categories

审计分类

Category	What it covers
`logic`	Incorrect behavior, missing checks, wrong conditions
`security`	Reentrancy, overflow, access control bypass, locked funds
`design`	Architecture issues, missing features, upgrade concerns
`gas`	Functions that may exceed block cost limits
`standards`	SIP compliance, event format, naming conventions

分类	涵盖内容
`logic`	行为错误、缺失检查、条件错误
`security`	重入攻击、溢出、权限绕过、资金锁定
`design`	架构问题、功能缺失、升级隐患
`gas`	可能超出区块成本限制的函数
`standards`	SIP合规性、事件格式、命名规范

Severity Levels

问题严重级别

Level	Criteria
`critical`	Funds at risk, contract can be bricked, exploitable by anyone
`high`	Significant logic errors, access control issues, economic attacks
`medium`	Non-critical issues that affect functionality or user experience
`low`	Best practice violations, code quality, documentation gaps

级别	判断标准
`critical`	资金面临风险、合约可能失效、任何人可利用漏洞
`high`	重大逻辑错误、权限控制问题、经济攻击隐患
`medium`	非关键问题，影响功能或用户体验
`low`	违反最佳实践、代码质量问题、文档缺失

Notes

注意事项

This skill produces structured output for automated processing
For open-ended security reasoning and multi-contract analysis, use the
```
clarity-expert
```
agent
The audit is static analysis only — it does not execute the contract
Always combine with
```
clarity-check
```
for pre-deployment validation
For production-critical contracts, supplement with RV fuzz testing via
```
clarity-test-scaffold
```
Reference: pbtc21/publisher-succession#1 for example audit output

该Skill生成结构化输出，便于自动化处理
如需开放式安全推理和多合约分析，请使用
```
clarity-expert
```
agent
本审计仅为静态分析——不会执行合约
请始终结合
```
clarity-check
```
进行部署前验证
对于生产级关键合约，建议通过
```
clarity-test-scaffold
```
补充RV模糊测试
参考示例审计输出：pbtc21/publisher-succession#1