sablier-labs Protocol Handbook
Protocol concepts essential for writing contracts and understanding business logic.
Protocol Registry
| Protocol | Purpose | Key Concept | Reference |
|---|---|---|---|
| Lockup | Fixed-term token vesting | Deposit upfront, stream over defined period | .claude/skills/handbook/references/lockup.md |
| Flow | Open-ended streaming | Rate-per-second with debt tracking, no end time | .claude/skills/handbook/references/flow.md |
| Airdrops | Merkle-based distribution | Recipients claim via proofs, optional vesting | .claude/skills/handbook/references/airdrops.md |
| Comptroller | Cross-protocol admin | Governance, fees, hook allowlisting | .claude/skills/handbook/references/comptroller.md |
Adding a new protocol? See Protocol Template below.
Protocol Comparison
| Aspect | Lockup | Flow | Airdrops |
|---|---|---|---|
| End time | Fixed at creation | Open-ended | Campaign expiry |
| Funding | Upfront deposit required | Flexible, anytime | Upfront in campaign |
| Cancelation | Refunds unstreamed tokens | Void forfeits uncovered debt | Clawback after grace |
| NFT | Yes (stream ID = token) | Yes (stream ID = token) | No |
| Use cases | Vesting, airdrops | Payroll, subscriptions | Token launches, rewards |
Core Patterns Across Protocols
Value Conservation
All protocols maintain: total_in = total_out + total_remaining
| Protocol | Invariant |
|---|---|
| Lockup | deposited = withdrawn + refunded + (streamed - withdrawn) |
| Flow | balance + totalWithdrawn = totalDeposited |
| Airdrops | campaignAmount = claimed + unclaimed + clawedBack |
Status State Machines
Each protocol has defined status transitions. See individual references for diagrams.
NFT Mechanics (Lockup & Flow)
- Token ID = Stream ID
- Owner = Recipient
- Transfer changes recipient
- Transferability set at creation (Lockup) or always transferable (Flow)
References
- Lockup Protocol - Vesting streams, shapes (Linear, Dynamic, Tranched), hooks
- Flow Protocol - Debt model, rate adjustments, solvency
- Airdrops Protocol - Merkle campaigns, claiming, clawback
- Comptroller - Admin contract, governance, Comptrollerable base
Adding a New Protocol
When implementing a new Sablier protocol, create a reference file following this template:
Reference File Template
Create .claude/skills/handbook/references/{protocol-name}.md:
# {Protocol Name} Protocol
{One-line description of what this protocol does.}
## Core Formula
{The mathematical model driving the protocol}
## Key Concepts
| Concept | Description |
| ----------- | ------------ |
| **{Term1}** | {Definition} |
| **{Term2}** | {Definition} |
## Statuses
| Status | Condition |
| ------------- | -------------------------- |
| **{STATUS1}** | {When this status applies} |
## Status Transitions
{ASCII diagram of valid state transitions}
## Key Operations
| Operation | Effect on State |
| --------- | --------------- |
| **{op1}** | {What it does} |
## Invariants
{List of properties that must always hold}
## NFT Mechanics (if applicable)
{How NFTs relate to protocol entities}
## References
Refer to https://docs.sablier.com/llms-{protocol}.txt for up-to-date documentation.
Checklist for New Protocol
- Create
.claude/skills/handbook/references/{protocol}.mdfollowing template - Add to Protocol Registry table above
- Add to Protocol Comparison table
- Update agent's package structure in
solidity-engineer.md - Add protocol-specific BTT conventions to
.claude/skills/btt-testing/references/sablier-conventions.md - Add test conventions to
.claude/skills/foundry-testing/references/sablier-conventions.md
Example Invocations
Test this skill with these prompts:
- Concept question: "Explain the difference between Lockup Linear and Lockup Dynamic streams"
- Formula question: "How is the withdrawable amount calculated in Flow when a stream is insolvent?"
- State machine: "What are the valid status transitions for a Lockup stream?"
- Business logic: "How does the clawback mechanism work in Airdrops campaigns?"