Skip to content

chore: refactor airdrop guide #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tilo-14 merged 1 commit into from
Jan 16, 2026
Merged

chore: refactor airdrop guide #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -635,6 +635,6 @@ If `getCompressedTokenBalancesByOwnerV2` returns empty:
title="Create an Airdrop with Compressed Tokens."
icon="chevron-right"
color="#0066ff"
href="/compressed-tokens/advanced-guides/create-an-airdrop"
href="/compressed-tokens/advanced-guides/airdrop"
horizontal
/>
146 changes: 109 additions & 37 deletions ...ens/advanced-guides/create-an-airdrop.mdx → ...ressed-tokens/advanced-guides/airdrop.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,37 @@
---
title: Create an Airdrop without Claim
description: Complete guide to create an airdrop – with or without code. Access to cost calculation and best practices. ZK compression is the most efficient way to distribute SPL tokens.
keywords: ["airdrop infrastructure on solana", "scalable token distribution on solana", "token airdrop for protocols"]
title: Airdrop Guide with ZK Compression
sidebarTitle: Airdrop Guide
description: Complete client and program guides to create an airdrop – with or without code. ZK compression is the most efficient way to distribute SPL tokens.
keywords: ["solana airdrop", "merkle distributor", "merkle airdrop", "airdrop infrastructure on solana", "scalable token distribution on solana", "token airdrop for protocols"]
---

import { TokenAccountCompressedVsSpl } from '/snippets/jsx/token-account-compressed-vs-spl.jsx';
import InstallDependencies from '/snippets/setup/install-dependencies-codegroup.mdx';
import SetupEnvironment from '/snippets/setup/setup-environment-tabs.mdx';
import { TokenAccountCompressedVsSpl } from '/snippets/jsx/token-account-compressed-vs-spl.jsx';

## Guides

There are two ways to use ZK Compression to distribute your SPL tokens.
<CardGroup>
<Card
title="No-Code Airdrop Tool"
href="https://www.helius.dev/docs/airship/getting-started"
icon="laptop-code"
>
Use **Airship by Helius Labs** to airdrop to up to 200,000 recipients via Webapp.
</Card>
<Card
title="Custom Programmatic Airdrop"
href="#programmatic-airdrop"
icon="terminal"
>
Create a programmatic airdrop with this guide for more control.
</Card>
</CardGroup>


### Cost Comparison

<TokenAccountCompressedVsSpl />

## Programmatic Airdrop
---

<Tabs>
<Tab title="Client Side Distribution">

Choose your implementation based on your needs:

| Tab | Best For | What You'll Get | Time |
|:-------------|:-------------|:-------------|:-------------|
| **Implementation Steps** | First-time users, learning | Step-by-step Localnet tutorial | 20 min |
| **Localnet Guide** | First-time users, learning | Step-by-step Localnet tutorial | 20 min |
| **Simple Airdrop** | \<10,000 recipients | Production-ready single script | 10 min |
| **Airdrop with Batched Instructions** | 10,000+ recipients | Batched system with retry logic | 15 min |

<Info>
Via Webapp you can use [Airship by Helius Labs](https://airship.helius.dev/) to airdrop to up to 200,000 recipients.
</Info>

<Tabs>
<Tab title="Implementation Steps">
<Tab title="Localnet Guide">

<Check>
**What you'll build:** A test airdrop sending compressed tokens to 3 recipients on your local validator.
Expand Down Expand Up @@ -298,11 +285,58 @@ MINT_ADDRESS=YOUR_MINT_ADDRESS
<Step>
### Mint SPL Tokens

Mint SPL tokens to your wallet for distribution. See the [mint script example](https://github.com/Lightprotocol/example-token-distribution/blob/main/src/simple-airdrop/mint.ts).
Use your existing mint or mint SPL tokens to your wallet for distribution.

<Info>
You can also use an existing mint if you already have one.
</Info>
```typescript expandable
import { Rpc, createRpc } from '@lightprotocol/stateless.js';
import { createMint } from '@lightprotocol/compressed-token';
import {
getOrCreateAssociatedTokenAccount,
mintTo as mintToSpl,
} from '@solana/spl-token';
import { PAYER_KEYPAIR, RPC_ENDPOINT } from '../constants';

const payer = PAYER_KEYPAIR;
const connection: Rpc = createRpc(RPC_ENDPOINT);
const decimals = 9;
const mintAmount = 100;

(async () => {
// airdrop lamports to pay tx fees
// await confirmTx(
// connection,
// await connection.requestAirdrop(payer.publicKey, 1e7)
// );

const { mint, transactionSignature } = await createMint(
connection,
payer,
payer.publicKey,
decimals,
);
console.log(
`create-mint success! txId: ${transactionSignature}, mint: ${mint.toBase58()}`,
);

const ata = await getOrCreateAssociatedTokenAccount(
connection,
payer,
mint,
payer.publicKey,
);
console.log(`ata: ${ata.address}`);

const mintTxId = await mintToSpl(
connection,
payer,
mint,
ata.address,
payer.publicKey,
mintAmount,
);
console.log(`mint-spl success! txId: ${mintTxId}`);
})();
```
</Step>

<Step>
Expand Down Expand Up @@ -866,9 +900,7 @@ Solana Wallets like Phantom and Backpack already support compressed tokens.
Still, you can let users decompress to SPL via your Frontend to customize claims.
</Info>

* Full Example on Github to [create an Airdrop with Claim](https://github.com/Lightprotocol/program-examples-airdrop-implementations/simple-claim).

* Add decompression of SPL Tokens with this script.
Add decompression of SPL Tokens with this script.

```typescript expandable
import {
Expand Down Expand Up @@ -968,12 +1000,52 @@ Set priority fees dynamically for decompression. Learn more [here](https://docs.

If you have a custom FE, you can let users swap compressed tokens using the Jup-API. A reference implementation is available [here](https://github.com/Lightprotocol/example-jupiter-swap-node).

# Next Steps
## Next Steps

<Card
title="Create an airdrop with claim functionality."
icon="chevron-right"
color="#0066ff"
href="https://github.com/Lightprotocol/program-examples-airdrop-implementations/tree/main/simple-claim"
href="#claim-reference-implementations"
horizontal
/>
</Tab>
<Tab title="Claim Reference Implementations">

Customize token distribution and let users claim.

| | distributor | simple-claim |
|--|-------------|--------------|
| Vesting | Linear Vesting | Cliff at Slot X |
| Partial claims | Yes | No |
| Clawback | Yes | No |
| Frontend | REST API + CLI | None |

<Info>
The programs are not audited and should be before production use.
</Info>

<CardGroup>
<Card
title="Merkle Distributor"
icon="parachute-box"
color="#0066ff"
href="https://github.com/Lightprotocol/distributor"
horizontal
>
Merkle distributor based on jito airdrop and optimized with rent-free PDAs.
Copy link

@coderabbitai coderabbitai bot Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix spellcheck failure for "jito".

The pipeline is failing because "jito" is flagged as an unknown word by the spellchecker. Since "Jito" refers to Jito Labs (a known Solana ecosystem company), consider one of these fixes:

  1. Capitalize it as "Jito" (proper noun)
  2. Add "jito" to the project's spellcheck dictionary/word list
  3. Rephrase to "Jito Labs airdrop"
Suggested fix (option 1 - capitalize) 
-    Merkle distributor based on jito airdrop and optimized with rent-free PDAs.
+    Merkle distributor based on Jito airdrop and optimized with rent-free PDAs.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Merkle distributor based on jito airdrop and optimized with rent-free PDAs.
Merkle distributor based on Jito airdrop and optimized with rent-free PDAs.
🧰 Tools
🪛 GitHub Actions: CI

[error] 1036-1036: Spellcheck failed: Unknown word 'jito'. CSpell: Files checked: 201, Issues found: 1 in 1 file. Command 'npm run spellcheck' exited with code 1.

🤖 Prompt for AI Agents 
In `@compressed-tokens/advanced-guides/airdrop.mdx` at line 1036, The phrase
"Merkle distributor based on jito airdrop and optimized with rent-free PDAs."
triggers a spellcheck failure for "jito"; update the wording to use the proper
noun by capitalizing it (e.g., change "jito airdrop" to "Jito airdrop" or "Jito
Labs airdrop") in the sentence containing "Merkle distributor based on jito
airdrop and optimized with rent-free PDAs." to resolve the pipeline error
(alternatively add "jito" to the project's spellcheck dictionary if preferred).

</Card>

<Card
title="Simple Airdrop with Claim"
icon="hand-holding"
color="#0066ff"
href="https://github.com/Lightprotocol/program-examples/tree/main/airdrop-implementations/simple-claim"
horizontal
>
Simple SPL token airdrop with claim.
</Card>
</CardGroup>

</Tab>
</Tabs>
8 changes: 0 additions & 8 deletions compressed-tokens/advanced-guides/create-an-airdrop-with-claim.mdx
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion compressed-tokens/advanced-guides/how-to-combine-operations-in-one-transaction.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -193,6 +193,6 @@ createPoolAndCompress().catch(console.error);
title="Create an Airdrop with Compressed Tokens."
icon="chevron-right"
color="#0066ff"
href="/compressed-tokens/advanced-guides/create-an-airdrop"
href="/compressed-tokens/advanced-guides/airdrop"
horizontal
/>
2 changes: 1 addition & 1 deletion compressed-tokens/advanced-guides/use-token-2022-with-compression.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -271,7 +271,7 @@ const connection = createRpc(); // defaults to localhost:8899
title="Create an Airdrop with Compressed Tokens."
icon="chevron-right"
color="#0066ff"
href="/compressed-tokens/advanced-guides/create-an-airdrop"
href="/compressed-tokens/advanced-guides/airdrop"
horizontal
/>

2 changes: 1 addition & 1 deletion compressed-tokens/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ import { TokenAccountCompressedVsSpl } from "/snippets/jsx/token-account-compres
title="Create an Airdrop"
icon="chevron-right"
color="#0066ff"
href="/compressed-tokens/advanced-guides/create-an-airdrop"
href="/compressed-tokens/advanced-guides/airdrop"
horizontal
/>
</Card>
Expand Down
4 changes: 3 additions & 1 deletion cspell.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,7 +184,9 @@
"zcash",
"circomlibjs",
"Jotaro",
"Yano"
"Yano",
"jito",
"Jito"
],
"ignorePaths": [
"node_modules",
Expand Down
3 changes: 1 addition & 2 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,7 @@
"group": "Compressed Tokens",
"pages": [
"compressed-tokens/overview",
"compressed-tokens/advanced-guides/airdrop",
{
"group": "Cookbook",
"pages": [
Expand Down Expand Up @@ -160,8 +161,6 @@
"group": "Examples",
"expanded": true,
"pages": [
"compressed-tokens/advanced-guides/create-an-airdrop",
"compressed-tokens/advanced-guides/create-an-airdrop-with-claim",
"compressed-tokens/advanced-guides/example-web-client",
"compressed-tokens/advanced-guides/example-node-js",
"compressed-tokens/advanced-guides/example-token-distribution"
Expand Down
16 changes: 3 additions & 13 deletions home.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,23 +105,13 @@ import WelcomePageInstall from "/snippets/setup/welcome-page-install.mdx";
</Tab>
<Tab title="Compressed Tokens">
<Card
title="Airdrop without Claim"
title="Airdrop Guide"
icon="parachute-box"
color="#0066ff"
href="/compressed-tokens/advanced-guides/create-an-airdrop"
href="/compressed-tokens/advanced-guides/airdrop"
horizontal
>
Distribute tokens directly to recipients.
</Card>

<Card
title="Airdrop with Claim"
icon="hand-holding"
color="#0066ff"
href="/compressed-tokens/advanced-guides/create-an-airdrop-with-claim"
horizontal
>
Distribute tokens and let users claim.
ZK Compression is the most efficient way to distribute SPL tokens.
</Card>

<Card
Expand Down
5 changes: 2 additions & 3 deletions snippets/overview-tables/compressed-tokens-advanced-guides-table.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
| Guide | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| [Create an Airdrop without Claim](/compressed-tokens/advanced-guides/airdrop) | ZK Compression is the most efficient way to distribute SPL tokens. Distribute via Webapp or customize with claim. |
| [Combine Instructions in One Transaction](/compressed-tokens/advanced-guides/how-to-combine-operations-in-one-transaction) | Execute multiple token instructions within a single transaction |
| [Create an Airdrop without Claim](/compressed-tokens/advanced-guides/create-an-airdrop) | Create an airdrop that appears directly in recipients' wallets (with or without code) |
| [Example Airdrop with Claim](https://github.com/Lightprotocol/program-examples-airdrop-implementations/simple-claim) | Demo for time-locked airdrop with compressed tokens |
| [Add Wallet Support for Compressed Tokens](/compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens) | Add compressed token support in your wallet application |
| [For Wallet Applications](/compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens) | Add compressed token support in your wallet application |
| [Use Token-2022 with Compression](/compressed-tokens/advanced-guides/use-token-2022-with-compression) | Create compressed Token-2022 mints with metadata and other extensions |
| [Example Web Client](https://github.com/Lightprotocol/example-web-client) | Demonstrates how to use @lightprotocol/stateless.js in a browser environment to interact with ZK Compression |
| [Example Node.js Client](https://github.com/Lightprotocol/example-nodejs-client) | Script to execute basic compression/decompression/transfers |
Loading