refactor: change export structure of releases

docs: draft README and CONTRIBUTING guide
refactor: rename queries to sablier
refactor: fewer default exports

Author: PaulRBerg

CONTRIBUTING.md

@@ -0,0 +1,41 @@
+## Contributing
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org) (v20+)
+- [Bun](https://bun.sh) (package manager)
+- [Just](https://github.com/casey/just) (task runner)
+
+### Setup
+
+```bash
+git clone https://github.com/sablier-labs/deployments.git
+cd deployments
+just install
+```
+
+### Available Commands
+
+```bash
+just --list                 # Show all available commands
+just build                  # Build the TypeScript package
+just full-check             # Run all code quality checks
+just full-write             # Auto-fix formatting and linting
+just test                   # Run test suite
+```
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run `just full-check` to verify code quality
+5. Submit a pull request
+
+### Adding New Chains
+
+TODO
+
+### Adding New Deployments
+
+TODO

README.md

@@ -1,91 +1,155 @@
-# Sablier Deployments
+# Sablier Deployments 🚀
 
-TODO: rewrite this
+Deployment data for the [Sablier Protocol](https://sablier.com), the token distribution protocol for Ethereum and
+EVM-compatible chains.
 
-This repository keeps track of Sablier deployment bundles, each of which includes:
+This package provides:
 
-1. Contract artifacts and ABIs.
-2. The [broadcast](https://book.getfoundry.sh/guides/scripting-with-solidity) directories generated by Foundry upon
-   running the deploy scripts.
+- **Contract addresses** across all supported protocols and chains
+- **Release management** for multiple protocol versions
+- **Chain data** with RPC endpoints and explorer URLs
+- **TypeScript SDK** for accessing deployment data programmatically
 
-The deployments are indexed by:
+## Installation 📦
 
-1. Repository ("lockup" or "flow")
-2. Version name (e.g. "v1.0.0")
-3. Artifacts
-4. Broadcasts, which in turn are indexed by chain name.
+```bash
+npm install @sablier/deployments
+# or
+yarn add @sablier/deployments
+# or
+bun add @sablier/deployments
+```
 
-If you need the deployment addresses, you can find them in the [docs](https://docs.sablier.com).
+## Protocol Overview 🎯
 
-## Background
+Sablier supports multiple protocols across versions:
 
-Sablier Protocols have been built, tested, formatted, and deployed with the [Foundry](https://getfoundry.sh) smart
-contract development toolchain.
+### Current Protocols
 
-To learn more about Foundry, see the [Foundry Book](https://book.getfoundry.sh).
+- **💧 Sablier Airdrops** - Merkle-based airdrop distributions with an optional vesting module
+- **🔒 Sablier Lockup** - Time-locked token vesting with cliffs
+- **🔄 Sablier Flow** - Token streaming with continuous payments
+- **⚡ Sablier Legacy** - Old release similar to Lockup, deployed between 2019-2021
 
-To learn more about Sablier, see the [Sablier Docs](https://docs.sablier.com).
+### Supported Chains
 
-## Addresses
+**Mainnets**: Ethereum, Arbitrum, Optimism, Polygon, Base, BSC, Avalanche, and 20+ more.
 
-To view the deployment addresses, use the links below.
+**Testnets**: Sepolia, Base Sepolia, Optimism Sepolia, and more.
 
-- [Airdrops deployment addresses](https://docs.sablier.com/guides/airdrops/deployments)
-- [Lockup deployment addresses](https://docs.sablier.com/guides/lockup/deployments)
-- [Flow deployment addresses](https://docs.sablier.com/guides/flow/deployments)
+### Addresses
 
-### Packages
+The addresses are provided in this package, but you can also view the deployment addresses on the
+[Sablier Docs](https://docs.sablier.com) website:
 
-The contract artifacts and the ABIs are published as NPM packages:
+- [Sablier Airdrops addresses](https://docs.sablier.com/guides/airdrops/deployments)
+- [Sablier Lockup addresses](https://docs.sablier.com/guides/lockup/deployments)
+- [Sablier Flow addresses](https://docs.sablier.com/guides/flow/deployments)
 
-- [@sablier/airdrops](https://npmjs.com/package/@sablier/airdrops)
-- [@sablier/lockup](https://npmjs.com/package/@sablier/lockup)
-- [@sablier/flow](https://npmjs.com/package/@sablier/flow)
+## API Reference 📖
 
-Older versions of Lockup (before v2.0.0) and Airdrops (before v1.3.0) have been published through these packages:
+### Chains
 
-- [@sablier/v2-core](https://npmjs.com/package/@sablier/v2-core)
-- [@sablier/v2-periphery](https://npmjs.com/package/@sablier/v2-periphery)
+Our chain types extend upon Viem's [Chain](https://viem.sh/docs/chains/introduction).
 
-## Scripts
+```typescript
+import { chains } from "@sablier/deployments";
 
-The contracts have been deployed using these scripts:
+// Get by name
+const ethereum = chains.ethereum;
 
-- [airdrops/script](https://github.com/sablier-labs/airdrops/tree/main/script)
-- [lockup/script](https://github.com/sablier-labs/lockup/tree/main/script)
-- [flow/script](https://github.com/sablier-labs/flow/tree/main/script)
+// Get chain by ID
+const arbitrum = chains.queries.get({ chainId: 42161 });
 
-Specifically, with the "DeployDeterministic" scripts, which rely upon this CREATE2 factory:
+// Get chain by slug
+const polygon = chains.queries.get({ slug: "polygon" });
 
-- https://github.com/Arachnid/deterministic-deployment-proxy
+// Check if chain supports Sablier UI
+if (ethereum.isSupportedByUI) {
+  console.log("Available on app.sablier.com");
+}
+```
 
-### Differentiation
+### Contracts
 
-The rationale for using CREATE2 is not to generate deterministic deployment addresses - quite the opposite. The goal is
-to have different addresses on each chain. By using CREATE2, we can systematically differentiate the contract addresses
-by passing a salt, whereas if we had used CREATE, the deployer's nonce would have impacted the resulting deployment
-address.
+```typescript
+import { releases, sablier } from "@sablier/deployments";
 
-## Logging
+// Get contract by name and chain
+const lockup = sablier.contracts.get({
+  name: "SablierLockup",
+  release: releases.lockup["v2.0"],
+});
+```
 
-This project uses Winston for logging. By default, logs are output to the console, but they can also be written to a
-file by setting the following environment variables:
+### Releases
 
-- `LOG_FILE_PATH`: Path to the log file (e.g., `./logs/deployments.log`). When set, logs will be written to this file in
-  addition to the console.
-- `LOG_LEVEL`: Set the logging level (default: `info`). Valid values are: `error`, `warn`, `info`, `verbose`, `debug`,
-  and `silly`.
+```typescript
+import { releases, sablier } from "@sablier/deployments";
 
-Example usage:
+// Get specific releases
+const airdropsV1_3 = releases.airdrops["v1.3"];
+const lockupV2_0 = releases.lockup["v2.0"];
+const flowV1_1 = releases.flow["v1.1"]";
 
-```bash
-# Log to both console and file
-LOG_FILE_PATH=./logs/deployments.log bun run build
+// Get all Lockup releases
+const allLockups = sablier.releases.getAll({ protocol: "lockup" });
+```
+
+## Data Structure 📊
+
+### Release Object
+
+See the [types](./src/types.ts) for more information.
 
-# Set a custom log level
-LOG_LEVEL=debug LOG_FILE_PATH=./logs/debug.log bun run test
+```typescript
+interface Release {
+  protocol: "flow" | "lockup" | "airdrops" | "legacy";
+  version: "v1.0" | "v1.1" | "v2.0" | ...;
+  isLatest: boolean;
+  contractNames: string[];
+  deployments: Deployment[];
+}
 ```
 
-## License
+### Deployment Broadcasts
+
+The deployment broadcasts (generated with [Foundry](https://book.getfoundry.sh/reference/cheatcodes/broadcast/)) are
+located under the [`data`](./data) directory.
+
+Each deployment is stored as JSON with a structure like this, which is generated by Foundry:
+
+```json
+{
+  "transactions": [...],      // Deployment transactions
+  "receipts": [...],          // Transaction receipts
+  "libraries": [...],         // Linked libraries
+  "returns": {                // Deployed contract addresses
+    "flow": "0x...",
+    "nftDescriptor": "0x..."
+  },
+  "timestamp": 1738015038,    // Deployment timestamp
+  "chain": 1,                 // Chain ID
+  "commit": "a0fa33d"         // Git commit hash
+}
+```
+
+## Contributing 🤝
+
+We welcome contributions!
+
+- 🐛 [Bug reports](https://github.com/sablier-labs/deployments/issues/new)
+- 💬 [Discussions](https://github.com/sablier-labs/deployments/discussions/new)
+- 💬 [Discord](https://discord.gg/bSwRCwWRsT)
+
+For guidance on how to make PRs, see the [CONTRIBUTING](./CONTRIBUTING.md) guide.
+
+## Links 📚
+
+- 📖 [Protocol Docs](https://docs.sablier.com)
+- 🔗 [API Reference](https://docs.sablier.com/api/overview)
+- ⏳ [Sablier App](https://app.sablier.com)
+
+## License 📄
 
-This repo is licensed under GPL 3-0 or later.
+This project is licensed under [GPL-3.0-or-later](./LICENSE.md).

TODOs.md

@@ -1,8 +1,3 @@
 # Priority 1
 
-- [ ] Add instructions in the README
 - [ ] Refactor `data` broadcasts to get rid of `mainnets` and `testnets` dichotomy
-
-# Priority 2
-
-- [ ] Add `@unimplemented` tag for `compilerSettings`

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sablier/deployments",
   "description": "Deployment data for the Sablier Protocol",
-  "version": "1.0.0-alpha.45",
+  "version": "1.0.0-alpha.46",
   "author": {
     "name": "Sablier Labs Ltd",
     "url": "https://sablier.com"
@@ -30,6 +30,9 @@
     "vitest": "^3.1",
     "winston": "^3.17"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "files": [
     "dist"
   ],

scripts/check-broadcast.ts

@@ -1,4 +1,4 @@
-import path from "node:path";
+import * as path from "node:path";
 import type { Sablier } from "@src/types";
 import * as fs from "fs-extra";
 import { logInfo } from "./logger";

scripts/print-aliases.ts

@@ -1,6 +1,6 @@
-import { releases } from "@src/releases";
+import { sablier } from "@src/sablier";
 import _ from "lodash";
-import logger, { logAndThrow } from "./logger";
+import logger from "./logger";
 
 type AliasRow = {
   alias: string;
@@ -11,7 +11,7 @@ type AliasRow = {
 async function main(): Promise<void> {
   const rows: AliasRow[] = [];
 
-  for (const release of releases) {
+  for (const release of sablier.releases.getAll()) {
     const releaseName = `${release.protocol} ${release.version}`;
     if (!release.aliases) {
       logger.verbose(`Skipping ${releaseName} because it has no aliases`);
@@ -55,6 +55,4 @@ async function main(): Promise<void> {
   }
 }
 
-main().catch((error) => {
-  logAndThrow({ msg: `Error printing aliases: ${error.message}` });
-});
+main();

scripts/print-missing.ts

@@ -4,16 +4,15 @@
  * for all chains, only the ones listed in the releases.
  *
  * Usage:
- *   bun run scripts/print-missing-broadcasts.ts airdrops
- *   bun run scripts/print-missing-broadcasts.ts flow
- *   bun run scripts/print-missing-broadcasts.ts lockup
+ *   bun run scripts/print-missing.ts airdrops
+ *   bun run scripts/print-missing.ts flow
+ *   bun run scripts/print-missing.ts lockup
  */
-import queries from "@src/queries";
-import { releasesByProtocol } from "@src/releases";
+import { sablier } from "@src/sablier";
 import type { Sablier } from "@src/types";
 import _ from "lodash";
 import { checkBroadcast } from "./check-broadcast";
-import logger, { logAndThrow } from "./logger";
+import logger from "./logger";
 
 const EMOJIS = {
   check: "✅",
@@ -35,9 +34,10 @@ async function main(): Promise<void> {
 
   logger.info(`\n${EMOJIS.folder} Checking ${protocol} broadcasts...\n`);
 
-  for (const release of releasesByProtocol[protocol]) {
+  const allReleases = sablier.releases.getAll({ protocol });
+  for (const release of allReleases) {
     for (const deployment of release.deployments) {
-      const chain = queries.chains.getOrThrow(deployment.chainId);
+      const chain = sablier.chains.getOrThrow(deployment.chainId);
 
       let hasValidBroadcasts = false;
 
@@ -117,9 +117,7 @@ async function main(): Promise<void> {
   console.log(`${EMOJIS.testnet} Missing testnet broadcasts: ${testnetCount}\n`);
 }
 
-main().catch((error) => {
-  logAndThrow({ msg: `Error checking missing broadcasts: ${error.message}` });
-});
+main();
 
 /* -------------------------------------------------------------------------- */
 /*                                   HELPERS                                  */

src/chains/config.ts

@@ -23,7 +23,7 @@ export const config = {
       [viem.taiko.id]: true,
     } as ConfigBool,
   },
-  // These chains have the artifacts under the `artifacts-zk` directory
+  // These chains have the artifacts under the `artifacts-zk` directory.
   zk: {
     [viem.abstract.id]: true,
     [viem.sophon.id]: true,

src/chains/index.ts

@@ -9,4 +9,3 @@
  * @see https://chainlist.org
  */
 export * from "./data";
-export { default as queries } from "./queries";

src/chains/queries.ts

@@ -2,15 +2,15 @@ import type { Sablier } from "@src/types";
 import _ from "lodash";
 import { chains as allChains } from "./data";
 
-const queries = {
+export const chainsQueries = {
   get: (chainId: number): Sablier.Chain | undefined => {
     return _.find(allChains, { id: chainId });
   },
   getAll: (): Sablier.Chain[] => {
     return _.values(allChains);
   },
-  getName: (chainId: number): string | undefined => {
-    return _.find(allChains, { id: chainId })?.name;
+  getBySlug: (slug: string): Sablier.Chain | undefined => {
+    return _.find(allChains, { slug });
   },
   getOrThrow: (chainId: number): Sablier.Chain => {
     const chain = _.find(allChains, { id: chainId });
@@ -20,5 +20,3 @@ const queries = {
     return chain;
   },
 };
-
-export default queries;