suffering/Hawk.Sol

# Hawk.Sol **Solana Circuit Breaker Protocol** Hawk.Sol 是一个针对 SPL token 金库的链上流速熔断器。它允许协议将所有金库提款路由到由 PDA 控制的守护程序中，该守护程序会强制执行滑动窗口流出上限，支持守护者紧急止损，并证明被攻陷的 operator 只能提取不超过配置窗口上限的资金。 该命令依然为 `solhawk`。  ## 功能简介 - **保护 SPL 金库**：将金库权限转移至由程序派生的熔断器权限地址。 - **限制流出速度**：通过 12 个桶的滑动窗口计算机制来限制流出量。 - **阻止快速抽水**：当提款将超过上限时，会在执行 transfer CPI 之前触发熔断以拦截。 - **权限分离**：将 operator 提款权限与守护者紧急或治理控制权限分离开来。 - **附带本地演示**：展示正常提款、攻击尝试、熔断触发、熔断后拦截以及汇总计算。 ## 演示结果 使用默认演示参数时： - 金库初始拥有 **1,000 个 token**。 - 正常使用消耗 **50 个 token**。 - 攻击者在第二幕中恰好获得 **50 个 token**。 - 总窗口流出量恰好达到配置上限 **100 个 token**。 - 触发熔断的交易会返回成功，从而使熔断状态得以保留，但在该执行路径上，transfer CPI 是不可达的。 - 后续的提款尝试将因 `6000`（`Tripped`）错误而失败。  在本地运行： ``` solana-test-validator --reset anchor deploy solhawk demo --seed 43 ``` 机器可读输出： ``` solhawk demo --seed 43 --json ``` ## 核心 Instructions | Instruction | 调用者 | 用途 | |---|---|---| | `initialize_breaker` | Payer + 金库权限 | 创建 breaker PDA 并将金库权限转移给 breaker PDA。 | | `guarded_withdraw` | Operator | 记录流出量、检查上限，并且仅在依然安全时，执行由 PDA 签名的 SPL 转账。 | | `trip` | Guardian | 手动紧急止损。 | | `resume` | Guardian，或在冷却时间结束后（如果启用了 `auto_recover`）任何人皆可 | 将状态从 `Tripped` 恢复为 `Active`。 | | `propose_config_change` | Guardian | 开启一个时间锁定的配置更改。 | | `execute_config_change` | Guardian | 应用一个已到期的配置更改。 | | `cancel_config_change` | Guardian | 取消一个挂起的配置更改。 | | `emergency_route_to_safe` | Guardian | 在熔断状态下，将资金路由至不可变的 safe 目的地。 | ## 安全模型 Hawk.Sol 的设计围绕着一个极窄且可审计的转账接口： - **唯一的转账路径**：受保护的金库资金只能通过 `guarded_withdraw` 或仅限 Guardian 的紧急路由（在熔断期间）进行转移。 - **PDA 权限**：breaker 权限 PDA 是初始化后唯一可以从金库发起转账的签名者。 - **CPI 前窗口检查**：窗口计算发生在 token 动账之前。 - **熔断持久化**：达到阈值违规时，程序会设置 `Tripped` 并返回 `Ok(())`；如果返回错误，在 Solana 交易的原子性下会导致熔断状态回滚。 - **熔断时不转账**：速度熔断路径会在执行 transfer CPI 之前返回，因此触发熔断的调用不会转移资金。 - **规范 PDA 验证**：breaker、window、authority 以及待处理配置账户均从固定 seeds 派生并进行验证。 - **治理延迟**：可变的配置更改需通过 Guardian 提案和时间锁定的执行来完成。 ## CLI 该 CLI crate 名为 `solhawk`，并提供了各项操作命令： ``` solhawk status solhawk status --json solhawk init --mint --guardian --operator --safe-destination solhawk trip solhawk resume solhawk demo solhawk demo --json ``` 全局默认设置： - RPC：`http://127.0.0.1:8899` - 本地 program ID：`7Wuw9J1cW8V2R1KAA6T3y3bRDpBYJ5FkQWMj8gDKb1MW` - 默认密钥对：`~/.config/solana/id.json` ## 构建与测试 为了兼容 LiteSVM，本仓库需在 WSL2/Linux 环境下构建。 ``` cd /mnt/c/Users/USAJu/Desktop/SolHawk/Hawk.Sol anchor build cargo test -p circuit_breaker cargo test -p circuit-breaker-tests cargo test -p solhawk ``` 完整测试扫描： ``` cargo test -p circuit_breaker -p circuit-breaker-tests -p solhawk ``` ## 项目布局 ``` Hawk.Sol/ ├── programs/circuit_breaker/ # Anchor on-chain program │ └── src/ │ ├── instructions/ # Instruction handlers │ ├── state/ # BreakerConfig, WindowState, pending config │ ├── window/accounting.rs # Sliding-window accounting │ ├── error.rs # Program errors 6000+ │ └── lib.rs # Accounts + dispatch ├── cli/ # `solhawk` command │ ├── src/commands/ # status/init/trip/resume/demo │ ├── src/ix/ # Instruction builders │ ├── src/rpc/ # RPC fetch/decode/tx helpers │ └── tests/ # CLI render + demo math tests ├── integration-tests/ # LiteSVM integration suite ├── docs/ # Account, CPI, PDA, event, error docs └── Anchor.toml ``` ## 文档 - `docs/PDAs.md` - `docs/CPIs.md` - `docs/events.md` - `docs/errors.md` - `docs/space.md` ## 状态 Hawk.Sol 目前包含核心熔断器、治理控制、CLI 操作以及可复现的本地有效性验证演示。

标签：Anchor, DeFi, Rust, Solana, 区块链, 可视化界面, 安全防护, 文档结构分析, 智能合约, 网络流量审计, 通知系统