diff --git a/.gitignore b/.gitignore index 90c6824..41272ce 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,5 @@ mintlify mintlify-docs/ /CLAUDE.md .windsurf.context/ +.claude +.context diff --git a/compressed-token-program/Extensions/compressible.mdx b/compressed-token-program/Extensions/compressible.mdx new file mode 100644 index 0000000..2f7fcca --- /dev/null +++ b/compressed-token-program/Extensions/compressible.mdx @@ -0,0 +1,251 @@ +--- +title: Compressible +description: The compressible extension sponsors rent-exemption for any type of Solana account except mints. +--- + + + + + + + + + + + + + + + + +
Supported AccountsDescription
**Compressible** + cToken accounts + + * **Sponsored rent-exemption** + * 200x cheaper than SPL tokens + * Must be **added at account creation** +
+ +## Key Points +Compressible accounts maintain the **functionality of Solana accounts** but with **rent-exemption sponsorship**: + +1. The protocol funds the account's rent exemption (rent sponsor) at creation. +2. The account creator top-ups the lamport balance with rent for at least two epochs (12,600 slots / 84 min) +3. The transaction payer top-ups the lamports balance with transactions that write to compressible accounts to keep the account decompressed. +4. The account will be compressed when inactive for a period of 12,600 slots (84 min). +5. When the account is written to, it's automatically decompressed. + +### Cost Comparison +This extension makes cToken accounts 200x cheaper than SPL token accounts + + | | cToken | SPL | + |-----------|--------|-----| + | allocate | 0.000011 | 0.002 | + | rent for 24h | 0.000005 | - | + + + +The **creator of Solana accounts** pays the **rent exemption balance equal to 2 years of rent**. +The rent-exempt balance is proportional to account size (calculated in lamports): + +``` rust +minimum_balance = (ACCOUNT_STORAGE_OVERHEAD + data_len) * lamports_per_byte * exemption_threshold + +/// Example 100 byte account: +/// minimum_balance = (128 + 100) * 6960 = 1,586,880 lamports +``` + +* Most Solana accounts are rarely accessed after creation, but continue to lock up SOL for the account's lifetime. +* The creator still must pay the rent-exemption balance. + + +**Compressible accounts** build on top of Solana's rent system, but use epochs with a length of 6300 slots to calculate rent. +The **creator pays** the account with **rent for at least two epochs**: + +``` rust +rent_per_epoch = base_rent + (data_len * lamports_per_byte_per_epoch) +/// Example 100 byte account: 128 + (100 * 1) = 228 rent per epoch +``` + + + +## Create a cToken Account with Compressible Extension + +Here are the steps to create a compressible account: + +1. **Set the initial lamports balance** to N epochs (must be at least 2 epochs) + * Customize N **based on expected account activity**. + * The account stays decompressed for N epochs. + + * Paid by the **account creator**. +2. **Set the top-up amount** for writes when the account balance falls below the set lamports balance. + * Determines how much lamports are added when the account needs a top-up. + * Top-ups are made by the **transaction fee payer** when the account is written to and is below the set lamports balance. + + +* Accounts become compressible when they advance two epochs without new transactions that add lamports. +* A forester node compresses the account after these two epochs and the protocol can reclaim the rent. + + +```rust +use light_token_client::actions::{ + create_compressible_token_account, + CreateCompressibleTokenAccountInputs, +}; +use light_ctoken_types::state::TokenDataVersion; + +let token_account_pubkey = create_compressible_token_account( + &mut rpc, + CreateCompressibleTokenAccountInputs { + owner: owner_pubkey, + mint: mint_pubkey, + payer: &payer_keypair, + num_prepaid_epochs: 10, // 0 or ≥2 + lamports_per_write: Some(5_000), // lamports added per top-up + token_account_version: TokenDataVersion::ShaFlat, + token_account_keypair: None, // SDK generates keypair + } +).await?; +``` + + +For associated cToken accounts derive the address with [owner, compressed_token_program_id, mint](https://solscan.io/account/cTokenmWW8bLPjZEBAUgYy3zKxQZW6VKi7bqNFEVv3m). + + +### Creation Cost + +Creating a compressible cToken account (260 bytes) incurs these costs: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentAmountPaid ByDescription
Solana rent exemption~2,700,480 lamportsRent sponsor PDARent-exemption balance
Prepaid rent388 × N epochs*Payer
(Account creator)		Rent for N epochs
Compression incentive10,000 lamports
+ 1,000 lamports		Payer
(Account creator)		Base compression cost
+ protocol incentive
Transaction fee5,000-10,000 lamportsPayer
(Account creator)		Standard Solana tx fees
+ +\* `N` = `num_prepaid_epochs` parameter (0 or 2+, set at creation). + +### Top-ups per Transaction + +When creating a compressible account, you can configure `lamports_per_write` to automatically add rent on each write ("Top-Up"). +This keeps accounts decompressed while active. + +The payer's cost depends on the account's funding state: + + + + + + + + + + + + + + + + + + + + + + + + + + +
Account StatePayer CostExample
Funded for 2+ epochs0 lamportsNo top-up required
Funded for less than 2 epochs`lamports_per_write`Configured as 5,000 lamports
→ payer pays 5,000 lamports
Compressible
(ran out of rent)		`lamports_per_write + rent_deficit`Configured top-up: 5,000 lamports
Rent deficit: 3,000 lamports
Total payer cost: 8,000 lamports
+ + +Top-ups are additional to standard Solana transaction fees (typically <10,000 lamports). + + +### Closing compressible accounts + +Compressible accounts can be closed by two parties. How rent and lamports balance are distributed depends on which party closes the account. + +1. The **Account Owner** can close the account at any time, regardless of rent status. The account is not compressed in this case. + + + + + + + + + + + + + + + + + + +
Component and AmountRecipient
Rent exemption + completed epoch rentRent sponsor
Remaining lamports from top-up (partial epoch)Account Owner
+ +2. The **Compression Authority** can compress and close the account when it becomes compressible + + + + + + + + + + + + + + + + + + +
Component and AmountRecipient
Rent exemption + remaining lamports
(all account lamports)		Rent sponsor
Compression incentive
(11,000 lamports)		Forester node
+ +## Next Steps + + + \ No newline at end of file diff --git a/compressed-token-program/Extensions/token-metadata.mdx b/compressed-token-program/Extensions/token-metadata.mdx new file mode 100644 index 0000000..0c5eb60 --- /dev/null +++ b/compressed-token-program/Extensions/token-metadata.mdx @@ -0,0 +1,191 @@ +--- +title: Token Metadata +description: The Token Metadata extension stores information of cMints like name, symbol, URI, and custom fields. + +--- + + + + + + + + + + + + + + + + +
Supported AccountsDescription
**Token Metadata**cMint accounts + * Rent-free mints with Token Metadata + * Stores information like name, symbol, URI, and custom fields. + * Must be added at creation of cMint +
+ +## Key Points + +* cMints with Token Metadata work alongside Token-2022 mints in the same program +* cMint Token Metadata serializes to identical bytes as Token-2022 metadata. +* Token Metadata embeds directly in the cMint account without a MetadataPointer extension +* cMints are rent-free and do not need rent-exempt calculations required by Token-2022 + +```rust +pub struct TokenMetadataInstructionData { + // Authority to modify metadata + pub update_authority: Option, + // Token name + pub name: Vec, + // Token symbol + pub symbol: Vec, + // URI to external metadata + pub uri: Vec, + // Custom fields + pub additional_metadata: Option>, +} +``` + +Find the [source code to the Token Metadata extension here](https://github.com/Lightprotocol/light-protocol/blob/main/programs/compressed-token/program/src/extensions/token_metadata.rs). + + +- `name`: 1-32 characters +- `symbol`: 1-10 characters +- `uri`: 0-200 characters +- `additional_metadata`: Maximum 20 entries with no duplicate keys (keys: 1-20 characters, values: 0-100 characters) + +## Creating cMint with Token Metadata + + +**Fields must be set at cMint creation.** +* Standard fields can be updated freely +* For `additional_metadata`, only existing keys can be modified or removed. + + +```rust expandable +use light_ctoken_types::state::{ + CompressedMint, BaseMint, CompressedMintMetadata, + extensions::{ExtensionStruct, TokenMetadata, AdditionalMetadata} +}; + +let compressed_mint = CompressedMint { + base: BaseMint { + mint_authority: Some(authority_pubkey), + supply: 1_000_000, + decimals: 6, + is_initialized: true, + freeze_authority: Some(freeze_authority_pubkey), + }, + metadata: CompressedMintMetadata { + version: 3, + spl_mint_initialized: false, + mint: spl_mint_pda, + }, + extensions: Some(vec![ + ExtensionStruct::TokenMetadata(TokenMetadata { + update_authority: authority_pubkey, + mint: spl_mint_pda, + name: "Rent-free Tokens".as_bytes().to_vec(), + symbol: "RFT".as_bytes().to_vec(), + uri: "https://mytoken.com/metadata.json".as_bytes().to_vec(), + additional_metadata: vec![ + AdditionalMetadata { + key: b"website".to_vec(), + value: b"https://mytoken.com".to_vec(), + }, + AdditionalMetadata { + key: b"category".to_vec(), + value: b"DeFi".to_vec(), + }, + ], + }) + ]), +}; +``` + +## Updating Token Metadata + +Once set, metadata can be updated with `MintAction`: + +1. [`UpdateMetadataField`](#update-metadata-fields) updates specific fields. +2. [`UpdateMetadataAuthority`](#update-metadata-authority) updates the authority that can modify the extension. +3. [`RemoveMetadataKey`](#remove-metadata-keys) removes a key-value pair from `additional_metadata`. + + +Find the [source code for these actions here](https://github.com/Lightprotocol/light-protocol/blob/main/programs/compressed-token/program/src/mint_action/actions/update_metadata.rs). + + + + + +### Update Metadata Fields + +Update standard fields (name, symbol, URI) or existing keys in `additional_metadata`: + +```rust +use light_ctoken_types::instructions::mint_action::UpdateMetadataFieldAction; + +// Update token name +let action = UpdateMetadataFieldAction { + extension_index: 0, // Index of TokenMetadata extension + field_type: 0, // 0 = Name + key: vec![], // Empty for standard fields + value: b"New Token Name".to_vec(), +}; +``` + + +* For `additional_metadata`, only existing keys can be modified or removed. +* New keys cannot be added after cMint creation. Only keys set during creation can be updated. + + + + + +### Update Metadata Authority + +```rust +use light_ctoken_types::instructions::mint_action::UpdateMetadataAuthorityAction; + +let action = UpdateMetadataAuthorityAction { + extension_index: 0, + new_authority: new_authority_pubkey, +}; +``` + + +To revoke update authority, set `new_authority` to a zero-byte pubkey (`Pubkey::default()`). + + + + + +### Remove Metadata Keys + +Removes a key from `additional_metadata`: + +```rust +use light_ctoken_types::instructions::mint_action::RemoveMetadataKeyAction; + +let action = RemoveMetadataKeyAction { + extension_index: 0, + key: b"category".to_vec(), + idempotent: 0, // 0 = error if key doesn't exist +}; +``` + + + + + +## Next Steps + + + \ No newline at end of file diff --git a/compressed-token-program/c-token-program.mdx b/compressed-token-program/c-token-program.mdx new file mode 100644 index 0000000..142135b --- /dev/null +++ b/compressed-token-program/c-token-program.mdx @@ -0,0 +1,370 @@ +--- +title: Compressed Token Program +sidebarTitle: Overview New +description: Overview of cMints, cTokens, and compressed token accounts. +--- + +import CompressibleVsSolanaRent from '/snippets/compressible-vs-solana-rent.mdx'; + +The [Compressed Token Program](https://github.com/Lightprotocol/light-protocol/tree/main/programs/compressed-token) extends existing Solana token standards with cMints, cTokens and compressed tokens. + + + + + + + + + + + + + + + + + + + + + + + + + + +
Account TypeKey Features
**[cMint](#cmint-accounts)**Compressed account +
    +
  • **Rent-free mint accounts** (similar to SPL mints)
    • +
  • Custom [Token Metadata](#token-metadata) **extension**
    • +
+
**[cToken](#ctoken-account)**Solana account +
    +
  • **Token accounts** derived from cMints (**SPL-compatible**)
    • +
  • **Sponsored rent** exemption via [compressible extension](#compressible) (200x cheaper than SPL tokens)
    • +
  • Use for **active token accounts** with frequent writes (trading, etc.)
    • +
+
**[Compressed Token](#compressed-token-account)**Compressed account +
    +
  • **Compressed account** with `TokenData` field
    • +
  • **Rent-free** and SPL-compatible
    • +
  • Use for **storage of inactive tokens** or **token distribution**
    • +
  • cToken accounts with the **[compressible extension](#compressible) are automatically compressed/decompressed** when active/inactive.
    • +
+
+ +_add graphic of all tokens here_ + + + +**SPL mints and tokens** owned by the [Token Program](https://github.com/solana-program/token) or [Token-2022](https://github.com/solana-program/token-2022) **require rent** by default.
+You can **migrate SPL token accounts to cTokens** with compressible extension for **sponsored rent-exemption** while keeping the **same interoparability**. + + +# cMint Accounts + + +* **cMints are compressed accounts** and **cannot be decompressed**. +* SPL mints can not be compressed to cMints. + + +cMints **uniquely represent a token on Solana and store its global metadata**, similar to SPL mint accounts with few core differences: +1. cMint accounts are **rent-free**. +2. Tokens created from cMints are **cTokens** (fully compatible with SPL tokens). +3. Token metadata (name, symbol, URI) is stored as an extension within the compressed mint account. + + + + + Diagram showing cMint compressed account structure with three components: Hash (identifier for cMint in purple box), Account (struct containing BaseMint with SPL-compatible fields, cMint Data for program state, and optional Extensions for Token Metadata), and BasemintData (containing Supply, Decimals, Mint Authority, and Freeze Authority fields) with Token Metadata extension + + + + ```rust + pub struct CompressedMint { + // SPL mint layout + pub base: BaseMint, + // cMint state used by the Compressed Token Program + pub metadata: CompressedMintMetadata + // Field for Token Metadata extension + pub extensions: Option>, + } + ``` + + + + +Find the [source code of cMints here](https://github.com/Lightprotocol/light-protocol/blob/main/program-libs/ctoken-types/src/state/mint/compressed_mint.rs). + + +The `metadata` field is used by the Compressed Token Program to store the internal state of a cMint. + +The `BaseMint` field replicates the field layout and serialization format of [SPL Mint accounts](https://solana.com/docs/tokens#mint-account). The struct is serialized with Borsh to match the on-chain format of SPL tokens and mints. + +Here is how cMints and SPL mints compare: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldcMintSPL Mint
mint_authority✓✓
supply✓✓
decimals✓✓
is_initialized✓✓
freeze_authority✓✓
cMint Data✓-
Extensions✓via Token-2022
+ + + ```rust + pub struct BaseMint { + /// Optional authority used to mint new tokens. The mint authority may only + /// be provided during mint creation. If no mint authority is present + /// then the mint has a fixed supply and no further tokens may be + /// minted. + pub mint_authority: Option, + /// Total supply of tokens. + pub supply: u64, + /// Number of base 10 digits to the right of the decimal place. + pub decimals: u8, + /// Is initialized - for SPL compatibility + pub is_initialized: bool, + /// Optional authority to freeze token accounts. + pub freeze_authority: Option, + } + ``` + + + +# cToken Account + + +**cToken accounts are Solana accounts**, not compressed accounts. + + +A cToken account holds token balances like SPL Token accounts: +* A wallet needs a cToken account for each cMint it wants to hold, with the wallet address set as the cToken account owner. +* Each wallet can own multiple cToken accounts for the same cMint. +* A cToken account can only have one owner and hold units of one cMint. + + + + + Diagram showing cToken Solana account structure with three components: Address (identifier for cToken account in purple box), Account (struct containing Data bytes, Executable flag, Lamports balance, and Owner set to Compressed Token Program), and AccountData (containing Mint, Owner, Amount, and Extensions fields) + + + + ```rust + /// Ctoken account structure (with extensions). + pub struct CToken { + pub mint: Pubkey, + pub owner: Pubkey, + pub amount: u64, + pub delegate: Option, // instruction not implemented yet + pub state: u8, + pub is_native: Option, + pub delegated_amount: u64, // instruction not implemented yet + pub close_authority: Option, + pub extensions: Option>, // Optional extensions e.g. compressible + } + ``` + + + + +Find the [source code of cToken here](https://github.com/Lightprotocol/light-protocol/blob/main/program-libs/ctoken-types/src/state/ctoken/ctoken_struct.rs). + + +cToken accounts replicate the field layout and serialization format of [SPL Token accounts](https://solana.com/docs/tokens#token-account). The struct is serialized with Borsh to match the on-chain format of SPL tokens. + +Here is how cTokens and SPL tokens compare: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldcTokenSPL Token Account
mint✓✓
owner✓✓
amount✓✓
delegateunimplemented✓
state✓✓
is_native✓✓
delegated_amountunimplemented✓
close_authority✓✓
extensions✓via Token-2022
+ +### Compressible Extension + +Compressible accounts maintain the **functionality of Solana accounts** but with **rent-exemption sponsorship**: + +1. The protocol funds the account's rent exemption at creation. +2. The account creator top-ups the lamport balance with rent for at least two epochs (12,600 slots / 84 min) +3. The transaction payer top-ups the lamports balance when the account's lamports balance is below 2 epochs. +4. The account will be compressed when inactive for a period of 12,600 slots (84 min). +5. When the account is written to, it's automatically decompressed. + +We recommend to create cToken accounts always with the [compressible extension](/compressible/compressible) for sponsored rent exemption. + +This extension makes cToken accounts 200x cheaper than SPL token accounts + + | | cToken | SPL | + |-----------|--------|-----| + | allocate | 0.000011 | 0.002 | + | rent for 24h | 0.000005 | - | + + + +# Associated cToken Account + +**Associated cToken** accounts follow the same pattern as [associated token accounts](https://docs.solana.com/developing/programming-model/associated-token-account) (ATA): +* Each wallet needs its own cToken account to hold tokens from the same cMint. +* It's derived with the owner's address, program ID, and mint address. +* The only **difference** in ATA derivation is the **program ID parameter** used in the seeds. + + +```rust +let seeds = [ + owner.as_ref(), // Wallet address (32 bytes) + program_id.as_ref(), // Compressed Token Program ID (32 bytes) + mint.as_ref(), // cMint address (32 bytes) + bump.as_ref(), // Bump seed (1 byte) +]; +``` + + +Find the [source code to associated cToken accounts here](https://github.com/Lightprotocol/light-protocol/blob/main/programs/compressed-token/program/src/create_associated_token_account.rs). + + + +cToken ATAs can implement the **[compressible extension](/compressible/compressible) for sponsored rent exemption**. + + +# Compressed Token Account + +Compressed token accounts store token balance, owner, and other information like SPL and cTokens. Any cToken or SPL token can be compressed/decompressed at will. + +We recommend to use compressed tokens for **token distribution** or **storage of inactive tokens**. + + +**cToken accounts** with the **[compressible extension](/compressible/compressible) are automatically compressed** with no writes in 12,600 slots (84 min) and decompressed with new writes. + + + + + + Diagram showing compressed token account structure with three components: Hash (identifier for compressed token account in purple box), Account (struct containing Data bytes, Executable flag, Lamports balance, and Address set to None), and AccountData (containing Mint, Owner, Amount, and Extensions fields marked as unimplemented) + + + + ```rust + pub struct TokenData { + pub mint: Pubkey, + pub owner: Pubkey, + pub amount: u64, + pub delegate: Option, + pub state: u8, + /// Placeholder for TokenExtension tlv data (unimplemented) + pub tlv: Option>, + } + ``` + + + +# Next Steps + + + \ No newline at end of file diff --git a/compressed-token-program/cmint/cmint.mdx b/compressed-token-program/cmint/cmint.mdx new file mode 100644 index 0000000..1544166 --- /dev/null +++ b/compressed-token-program/cmint/cmint.mdx @@ -0,0 +1,109 @@ +--- +title: Create cMint with Token Metadata +description: Guide to create a cMint, a rent-free mint account to store global metadata of tokens. +--- + + + + + + + + + + + + + + + + + + + + + + +
TypeKey Features
**[cMint](#cmint-accounts)**Compressed account +
    +
  • **Rent-free mint accounts** (similar to SPL mints)
    • +
+
**Token Metadata**Extension + * Stores information like name, symbol, URI, and custom fields. + * Must be added at creation of cMint +
+ + +Learn the core concepts to cMints [here](/compressed-token-program/c-token-program#cmint-accounts). + +## Get Started + + +These are the steps to create a cMint with metadata: + +1. Generate a mint seed keypair +2. Prepare token metadata +3. Call the `create_mint` action +4. Sign and send the transaction + + + + + + + + ```typescript + // Placeholder - not yet supported in TypeScript SDK + + ``` + + + ```rust + use light_sdk::compressed_account::CompressedAccountWithMerkleContext; + use light_compressed_token::mint_sdk::create_mint; + + // 1. Generate mint seed + let mint_seed = Keypair::new(); + + // 2. Prepare metadata + let metadata = Some(TokenMetadataInstructionData { + name: b"My Compressed Token".to_vec(), + symbol: b"MCT".to_vec(), + uri: b"https://example.com/token-metadata.json".to_vec(), + update_authority: mint_authority.pubkey(), + additional_metadata: vec![ + AdditionalMetadata { + key: b"description".to_vec(), + value: b"A sample compressed token".to_vec(), + } + ], + }); + + // 3. Create the cMint with metadata + create_mint( + &rpc, + &mint_seed, + 9, // decimals + &mint_authority, + None, // freeze_authority + metadata, + &payer, + ).await?; + ``` + + + +**Metadata fields must be set at cMint creation.** +* Standard fields can be updated freely +* For `additional_metadata`, only existing keys can be modified or removed. + +## Next Steps + + + \ No newline at end of file diff --git a/compressed-token-program/cmint/update-metadata.mdx b/compressed-token-program/cmint/update-metadata.mdx new file mode 100644 index 0000000..c048e1c --- /dev/null +++ b/compressed-token-program/cmint/update-metadata.mdx @@ -0,0 +1,89 @@ +--- +title: Update Token Metadata of cMints +sidebarTitle: Update Token Metadata +description: Overview how to update token metadata of cMints. +--- + +Once set, metadata can be updated with `MintAction`: + +1. [`UpdateMetadataField`](#update-metadata-fields) updates specific fields. +2. [`UpdateMetadataAuthority`](#update-metadata-authority) updates the authority that can modify the extension. +3. [`RemoveMetadataKey`](#remove-metadata-keys) removes a key-value pair from `additional_metadata`. + + +Find the [source code for these actions here](https://github.com/Lightprotocol/light-protocol/blob/main/programs/compressed-token/program/src/mint_action/actions/update_metadata.rs). + + + + + +### Update Metadata Fields + +Update standard fields (name, symbol, URI) or existing keys in `additional_metadata`: + +```rust +use light_ctoken_types::instructions::mint_action::UpdateMetadataFieldAction; + +// Update token name +let action = UpdateMetadataFieldAction { + extension_index: 0, // Index of TokenMetadata extension + field_type: 0, // 0 = Name + key: vec![], // Empty for standard fields + value: b"New Token Name".to_vec(), +}; +``` + + +* For `additional_metadata`, only existing keys can be modified or removed. +* New keys cannot be added after cMint creation. Only keys set during creation can be updated. + + + + + +### Update Metadata Authority + +```rust +use light_ctoken_types::instructions::mint_action::UpdateMetadataAuthorityAction; + +let action = UpdateMetadataAuthorityAction { + extension_index: 0, + new_authority: new_authority_pubkey, +}; +``` + + +To revoke update authority, set `new_authority` to a zero-byte pubkey (`Pubkey::default()`). + + + + + +### Remove Metadata Keys + +Removes a key from `additional_metadata`: + +```rust +use light_ctoken_types::instructions::mint_action::RemoveMetadataKeyAction; + +let action = RemoveMetadataKeyAction { + extension_index: 0, + key: b"category".to_vec(), + idempotent: 0, // 0 = error if key doesn't exist +}; +``` + + + + + +## Next Steps + + + \ No newline at end of file diff --git a/compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens.mdx b/compressed-token-program/compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens.mdx similarity index 100% rename from compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens.mdx rename to compressed-token-program/compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens.mdx diff --git a/compressed-tokens/advanced-guides/create-an-airdrop-with-claim.mdx b/compressed-token-program/compressed-tokens/advanced-guides/create-an-airdrop-with-claim.mdx similarity index 100% rename from compressed-tokens/advanced-guides/create-an-airdrop-with-claim.mdx rename to compressed-token-program/compressed-tokens/advanced-guides/create-an-airdrop-with-claim.mdx diff --git a/compressed-tokens/advanced-guides/create-an-airdrop.mdx b/compressed-token-program/compressed-tokens/advanced-guides/create-an-airdrop.mdx similarity index 100% rename from compressed-tokens/advanced-guides/create-an-airdrop.mdx rename to compressed-token-program/compressed-tokens/advanced-guides/create-an-airdrop.mdx diff --git a/compressed-tokens/advanced-guides/example-node-js.mdx b/compressed-token-program/compressed-tokens/advanced-guides/example-node-js.mdx similarity index 100% rename from compressed-tokens/advanced-guides/example-node-js.mdx rename to compressed-token-program/compressed-tokens/advanced-guides/example-node-js.mdx diff --git a/compressed-tokens/advanced-guides/example-web-client.mdx b/compressed-token-program/compressed-tokens/advanced-guides/example-web-client.mdx similarity index 100% rename from compressed-tokens/advanced-guides/example-web-client.mdx rename to compressed-token-program/compressed-tokens/advanced-guides/example-web-client.mdx diff --git a/compressed-tokens/advanced-guides/how-to-combine-operations-in-one-transaction.mdx b/compressed-token-program/compressed-tokens/advanced-guides/how-to-combine-operations-in-one-transaction.mdx similarity index 100% rename from compressed-tokens/advanced-guides/how-to-combine-operations-in-one-transaction.mdx rename to compressed-token-program/compressed-tokens/advanced-guides/how-to-combine-operations-in-one-transaction.mdx diff --git a/compressed-tokens/advanced-guides/use-token-2022-with-compression.mdx b/compressed-token-program/compressed-tokens/advanced-guides/use-token-2022-with-compression.mdx similarity index 100% rename from compressed-tokens/advanced-guides/use-token-2022-with-compression.mdx rename to compressed-token-program/compressed-tokens/advanced-guides/use-token-2022-with-compression.mdx diff --git a/compressed-tokens/guides/how-to-approve-and-revoke-delegate-authority.mdx b/compressed-token-program/compressed-tokens/basic-guides/how-to-approve-and-revoke-delegate-authority.mdx similarity index 100% rename from compressed-tokens/guides/how-to-approve-and-revoke-delegate-authority.mdx rename to compressed-token-program/compressed-tokens/basic-guides/how-to-approve-and-revoke-delegate-authority.mdx diff --git a/compressed-tokens/guides/how-to-compress-and-decompress-spl-tokens.mdx b/compressed-token-program/compressed-tokens/basic-guides/how-to-compress-and-decompress-spl-tokens.mdx similarity index 100% rename from compressed-tokens/guides/how-to-compress-and-decompress-spl-tokens.mdx rename to compressed-token-program/compressed-tokens/basic-guides/how-to-compress-and-decompress-spl-tokens.mdx diff --git a/compressed-tokens/guides/how-to-compress-complete-spl-token-accounts.mdx b/compressed-token-program/compressed-tokens/basic-guides/how-to-compress-complete-spl-token-accounts.mdx similarity index 100% rename from compressed-tokens/guides/how-to-compress-complete-spl-token-accounts.mdx rename to compressed-token-program/compressed-tokens/basic-guides/how-to-compress-complete-spl-token-accounts.mdx diff --git a/compressed-tokens/guides/how-to-create-and-register-a-mint-account-for-compression.mdx b/compressed-token-program/compressed-tokens/basic-guides/how-to-create-and-register-a-mint-account-for-compression.mdx similarity index 100% rename from compressed-tokens/guides/how-to-create-and-register-a-mint-account-for-compression.mdx rename to compressed-token-program/compressed-tokens/basic-guides/how-to-create-and-register-a-mint-account-for-compression.mdx diff --git a/compressed-tokens/guides/how-to-create-compressed-token-accounts.mdx b/compressed-token-program/compressed-tokens/basic-guides/how-to-create-compressed-token-accounts.mdx similarity index 100% rename from compressed-tokens/guides/how-to-create-compressed-token-accounts.mdx rename to compressed-token-program/compressed-tokens/basic-guides/how-to-create-compressed-token-accounts.mdx diff --git a/compressed-tokens/guides/how-to-create-compressed-token-pools-for-mint-accounts.mdx b/compressed-token-program/compressed-tokens/basic-guides/how-to-create-compressed-token-pools-for-mint-accounts.mdx similarity index 100% rename from compressed-tokens/guides/how-to-create-compressed-token-pools-for-mint-accounts.mdx rename to compressed-token-program/compressed-tokens/basic-guides/how-to-create-compressed-token-pools-for-mint-accounts.mdx diff --git a/compressed-tokens/guides/how-to-merge-compressed-token-accounts.mdx b/compressed-token-program/compressed-tokens/basic-guides/how-to-merge-compressed-token-accounts.mdx similarity index 100% rename from compressed-tokens/guides/how-to-merge-compressed-token-accounts.mdx rename to compressed-token-program/compressed-tokens/basic-guides/how-to-merge-compressed-token-accounts.mdx diff --git a/compressed-tokens/guides/how-to-mint-compressed-tokens.mdx b/compressed-token-program/compressed-tokens/basic-guides/how-to-mint-compressed-tokens.mdx similarity index 100% rename from compressed-tokens/guides/how-to-mint-compressed-tokens.mdx rename to compressed-token-program/compressed-tokens/basic-guides/how-to-mint-compressed-tokens.mdx diff --git a/compressed-tokens/guides/how-to-transfer-compressed-token.mdx b/compressed-token-program/compressed-tokens/basic-guides/how-to-transfer-compressed-token.mdx similarity index 100% rename from compressed-tokens/guides/how-to-transfer-compressed-token.mdx rename to compressed-token-program/compressed-tokens/basic-guides/how-to-transfer-compressed-token.mdx diff --git a/compressed-token-program/compressed-tokens/compressed-token-overview.mdx b/compressed-token-program/compressed-tokens/compressed-token-overview.mdx new file mode 100644 index 0000000..cb6e26f --- /dev/null +++ b/compressed-token-program/compressed-tokens/compressed-token-overview.mdx @@ -0,0 +1,96 @@ +--- +title: Overview +description: "Overview to compressed tokens and guides with full code examples. Use for token distribution or storage of inactive token accounts" +--- + +import GuidesTable from '/snippets/compressed-tokens-guides-table.mdx'; +import AdvancedGuidesTable from '/snippets/compressed-tokens-advanced-guides-table.mdx'; +import SetupEnvironment from '/snippets/setup-environment-tabs.mdx'; +import InstallDependencies from '/snippets/install-dependencies-codegroup.mdx'; + + + + + + + + + + + + + + + + +
Account TypeKey Features
**[Compressed Token](#compressed-token-account)**Compressed account +
    +
  • **Compressed account** with `TokenData` field
    • +
  • **Rent-free** and SPL-compatible
    • +
+
+ +Compressed token accounts store token balance, owner, and other information like SPL and cTokens. Any cToken or SPL token can be compressed/decompressed at will. + +## Recommended Usage of Compressed Tokens + + + #### [Token Distribution](#advanced-guides) + * Distribute tokens without paying up front rent per recipient. + * Cost reduction for airdrops, payments, rewards, etc: + + + + + + + + + + + + + + + +
SPL TokenCompressed Token
100,000 Token Accounts~ 200 SOL~ 0.004 SOL
+ + + #### Storage of Inactive Token Accounts + * Most (associated) token accounts are not frequently written to. + * **Store token accounts rent-free** when inactive + * Use or migrate to [cTokens with compressible extension](/compressed-token-program/ctoken/ctoken) for **automatic compression/decompression** when inactive/active. + * The compressible extension allows users to **only pay rent, when token accounts are active**. + + +Leading **wallets** like Phantom and Backpack **support compressed tokens**. The UI does not distinguish between SPL and compressed tokens. + + + + + +### Install dependencies + + + + + + +### Set up your developer environment + + + + + + + +### Get started + + + + +## Basic Guides + + +## Advanced Guides + diff --git a/compressed-token-program/ctoken/SPL-to-ctoken-transfer.mdx b/compressed-token-program/ctoken/SPL-to-ctoken-transfer.mdx new file mode 100644 index 0000000..30dffbb --- /dev/null +++ b/compressed-token-program/ctoken/SPL-to-ctoken-transfer.mdx @@ -0,0 +1,36 @@ +--- +title: Migrate SPL to cToken +description: Guide to migrate SPL tokens into compressed tokens and transfer them to a CToken account. +--- + +Converts SPL tokens into compressed tokens and transfers them to a CToken account. Interacts with a token pool PDA to synchronize supply between SPL and compressed tokens. + +**Use when:** Bridging tokens from the SPL ecosystem to compressed tokens, allowing users to deposit SPL tokens into their CToken accounts. + +**Key parameters:** + +- `source_spl_token_account`: Public key of the source SPL token account +- `to`: Public key of the destination CToken account +- `amount`: Number of tokens to transfer +- `authority`: Authority of the source SPL token account (signer) +- `mint`: Public key of the mint +- `payer`: Transaction fee payer +- `token_pool_pda`: Public key of the token pool PDA +- `token_pool_pda_bump`: Bump seed for the token pool PDA +- `spl_token_program`: Public key of the SPL Token program + +**Example:** + +```rust +use light_token_client::actions::transfer2::spl_to_ctoken_transfer; + +spl_to_ctoken_transfer( + &mut rpc, + spl_token_account_keypair.pubkey(), + associated_token_account, + transfer_amount, + &sender, + &payer, +) +.await?; +``` \ No newline at end of file diff --git a/compressed-token-program/ctoken/close-ctoken.mdx b/compressed-token-program/ctoken/close-ctoken.mdx new file mode 100644 index 0000000..9d8f18d --- /dev/null +++ b/compressed-token-program/ctoken/close-ctoken.mdx @@ -0,0 +1,38 @@ +--- +title: Close cToken +description: Guide to close a cToken, a rent-free mint account to store global metadata of tokens. +--- +Permanently closes a decompressed CToken Solana account. Distributes remaining lamports to a destination account, then zeros out and resizes the account to 0 bytes to prevent revival attacks. Works with both regular and compressible token accounts. + +**Use when:** You want to permanently close a CToken account with a zero token balance and reclaim its rent exemption. + +**Key parameters:** + +- `token_account`: The CToken account to close (must be initialized with zero balance) +- `destination`: Account receiving remaining user funds (non-rent lamports) +- `authority`: Signer (account owner or rent authority for compressible accounts) +- `rent_sponsor`: (Required for compressible accounts) Account receiving rent exemption + +**Example:** + +```rust +use light_compressed_token_sdk::ctoken::close_account::{ + close_account, + close_compressible_account, +}; + +// Close non-compressible account +let close_ix = close_account( + token_account_pubkey, + destination_pubkey, + authority.pubkey(), +)?; + +// Close compressible account +let close_compressible_ix = close_compressible_account( + token_account_pubkey, + destination_pubkey, + authority.pubkey(), + rent_sponsor_pubkey, +)?; +``` \ No newline at end of file diff --git a/compressed-token-program/ctoken/compress-and-close.mdx b/compressed-token-program/ctoken/compress-and-close.mdx new file mode 100644 index 0000000..3c8e05b --- /dev/null +++ b/compressed-token-program/ctoken/compress-and-close.mdx @@ -0,0 +1,33 @@ +### CompressAndClose mode + + +The `Transfer2` instruction provides a `CompressAndClose` mode that compresses the full balance of a CToken account and closes it in a single transaction. + +**Use when:** Optimizing storage and costs by moving tokens off-chain into compressed format while cleaning up the on-chain account. + +**Key parameters:** + +- `amount`: Full balance of the CToken account to compress +- `mode`: Set to `CompressionMode::CompressAndClose` +- `mint`: Index of the mint account +- `source_or_recipient`: Index of the source CToken account +- `authority`: Index of the owner/delegate account (must be signer) +- `pool_account_index`: Used as `rent_sponsor_index` for CompressAndClose +- `pool_index`: Used as `compressed_account_index` for CompressAndClose +- `bump`: Used as `destination_index` for CompressAndClose + +**Example:** + +```rust +use light_token_client::actions::compress_and_close::compress_and_close; + +// Compress full balance and close account +compress_and_close( + &mut rpc, + ctoken_account_pubkey, + compressed_account_index, + &authority, + &payer, +) +.await?; +``` \ No newline at end of file diff --git a/compressed-token-program/ctoken/create-ata.mdx b/compressed-token-program/ctoken/create-ata.mdx new file mode 100644 index 0000000..33ea146 --- /dev/null +++ b/compressed-token-program/ctoken/create-ata.mdx @@ -0,0 +1,103 @@ +--- +title: CreateAssociatedTokenAccount +description: Creates an associated token account (ATA) for compressed tokens +--- + + +1. Creates an associated token account (ATA) for compressed tokens, passing `owner` and `mint` public keys as instruction data. Supports both basic and compressible accounts. Includes idempotent versions that succeed even if the account already exists. + +**Use when:** Creating an ATA where owner and mint public keys are readily available and can be included directly in instruction data. + +2. Creates an associated token account with `owner` and `mint` passed as account infos rather than instruction data. Use when the program needs to perform checks or operations directly on the owner or mint accounts (e.g., signature verification, accessing mint data). + +**Use when:** The program needs to access owner or mint accounts as AccountInfo objects for verification or data access beyond just knowing their public keys. + +**Key parameters:** + +Same as CreateAssociatedTokenAccount, but `owner` and `mint` are passed as `AccountMeta` entries instead of instruction data. + + +### 1. +**Key parameters:** + +- `payer`: Public key of the account paying for transaction and account creation +- `owner`: Public key of the ATA owner +- `mint`: Public key of the mint +- `ata_pubkey`: Derived public key of the ATA (use `derive_ctoken_ata`) +- `bump`: PDA bump seed for ATA derivation + +**Compressible-specific parameters:** + +- `compressible_config`: Public key of the CompressibleConfig account +- `rent_sponsor`: Public key receiving lamports when account is closed by rent authority +- `pre_pay_num_epochs`: Number of epochs of rent to prepay +- `lamports_per_write`: (Optional) Initial lamports for rent top-ups +- `token_account_version`: TokenDataVersion specifying hashing scheme + +**Example:** + +```rust +use light_compressed_token_sdk::ctoken::create_associated_token_account::{ + create_associated_token_account, + create_compressible_associated_token_account, + CreateCompressibleAssociatedTokenAccountInputs, +}; +use light_ctoken_types::state::TokenDataVersion; + +// Basic ATA +let basic_ata_ix = create_associated_token_account( + payer_pubkey, + owner_pubkey, + mint_pubkey, +)?; + +// Compressible ATA +let compressible_ata_ix = create_compressible_associated_token_account( + CreateCompressibleAssociatedTokenAccountInputs { + payer: payer_pubkey, + owner: owner_pubkey, + mint: mint_pubkey, + compressible_config, + rent_sponsor, + pre_pay_num_epochs: 0, + lamports_per_write: Some(150), + token_account_version: TokenDataVersion::ShaFlat, + }, +)?; +``` + + +### 2. +**Key parameters:** + +Same as CreateAssociatedTokenAccount, but `owner` and `mint` are passed as `AccountMeta` entries instead of instruction data. + +**Example:** + +```rust +use light_compressed_token_sdk::ctoken::create_associated_token_account::{ + create_associated_token_account2, + create_compressible_associated_token_account2, +}; + +// Basic ATA (version 2) +let basic_ata2_ix = create_associated_token_account2( + payer_pubkey, + owner_pubkey, + mint_pubkey, +)?; + +// Compressible ATA (version 2) +let compressible_ata2_ix = create_compressible_associated_token_account2( + CreateCompressibleAssociatedTokenAccountInputs { + payer: payer_pubkey, + owner: owner_pubkey, + mint: mint_pubkey, + compressible_config, + rent_sponsor, + pre_pay_num_epochs: 0, + lamports_per_write: Some(150), + token_account_version: TokenDataVersion::ShaFlat, + }, +)?; +``` \ No newline at end of file diff --git a/compressed-token-program/ctoken/create-ctoken.mdx b/compressed-token-program/ctoken/create-ctoken.mdx new file mode 100644 index 0000000..da7cf82 --- /dev/null +++ b/compressed-token-program/ctoken/create-ctoken.mdx @@ -0,0 +1,120 @@ +--- +title: Create a cToken Account with Compressible Extension +description: Guide to create a cToken account with compressible extension. +--- + +import CompressibleVsSolanaRent from '/snippets/compressible-vs-solana-rent.mdx'; + + + + + + + + + + + + + + + + + + + + + +
TypeKey Features
**[cMint](#cmint-accounts)**Solana account +
    +
  • **SPL-compatible**
    • +
  • Use for **active token accounts** with frequent writes (trading, etc.)
    • +
+
**[Compressible](#compressible)**Extension +
    +
  • **Sponsored rent-exemption** makes cTokens 200x cheaper than SPL tokens
    • +
  • Must be added at creation of cToken
    • +
+
+ + + +Learn the core concepts to cTokens and compressible extension [here](/compressed-token-program/c-token-program#ctoken-accounts). + + + + +## Get Started + + + + +### Initialize cToken Account + + + + + +### Configure Compressible Extension +1. **Set the initial lamports balance** to N epochs (must be at least 2 epochs) + * Customize N **based on expected account activity**. + * You will top-up the account with rent for N epochs and it stays decompressed. +``` rust +rent_per_epoch = base_rent + (data_len * lamports_per_byte_per_epoch) + +// For 260-byte cToken account: +// 128 + (260 * 1) = 388 lamports per epoch +``` + +2. **Set the top-up amount** for writes when the account balance falls below the set lamports balance. + * Determines how much lamports are added when the account needs a top-up. + * Top-ups are made by the **transaction fee payer** when the account is written to and is below the set lamports balance. + + +* Accounts become compressible when they advance two epochs without new transactions that add lamports. +* A forester node compresses the account after these two epochs and the protocol can reclaim the rent. + + + + +### Full Code Example + +```rust +use light_token_client::actions::{ + create_compressible_token_account, + CreateCompressibleTokenAccountInputs, +}; +use light_ctoken_types::state::TokenDataVersion; + +let token_account_pubkey = create_compressible_token_account( + &mut rpc, + CreateCompressibleTokenAccountInputs { + owner: owner_pubkey, + mint: mint_pubkey, + payer: &payer_keypair, + num_prepaid_epochs: 10, // 0 or ≥2 + lamports_per_write: Some(5_000), // lamports added per top-up + token_account_version: TokenDataVersion::ShaFlat, + token_account_keypair: None, // SDK generates keypair + } +).await?; +``` + + +For associated cToken accounts derive the address with [owner, compressed_token_program_id, mint](https://solscan.io/account/cTokenmWW8bLPjZEBAUgYy3zKxQZW6VKi7bqNFEVv3m). + + + + + + +## Next Steps + + + \ No newline at end of file diff --git a/compressed-token-program/ctoken/ctoken-to-spl-decompress.mdx b/compressed-token-program/ctoken/ctoken-to-spl-decompress.mdx new file mode 100644 index 0000000..98e27c7 --- /dev/null +++ b/compressed-token-program/ctoken/ctoken-to-spl-decompress.mdx @@ -0,0 +1,49 @@ +--- +title: Transfer cToken to SPL account +description: Transfer compressed tokens from a cToken account to an SPL token account. +--- + + +Converts compressed tokens back to SPL tokens and transfers them to an SPL token account. Compresses the CToken balance into the token pool, then decompresses to the SPL account. + +**Use when:** Users want to withdraw compressed tokens from a CToken account back into the standard SPL token ecosystem. + +**Key parameters:** + +- `source_ctoken_account`: Public key of the source CToken account +- `destination_spl_token_account`: Public key of the destination SPL token account +- `amount`: Number of tokens to transfer +- `authority`: Authority of the source CToken account (signer) +- `mint`: Public key of the mint +- `payer`: Transaction fee payer +- `token_pool_pda`: Public key of the token pool PDA +- `token_pool_pda_bump`: Bump seed for the token pool PDA +- `spl_token_program`: Public key of the SPL Token program + +**Example:** + +```rust +use light_compressed_token_sdk::ctoken::transfer_interface::TransferCtokenToSpl; +use light_compressed_token_sdk::token_pool::find_token_pool_pda_with_index; + +let (token_pool_pda, token_pool_pda_bump) = find_token_pool_pda_with_index(&mint, 0); + +let transfer_ix = TransferCtokenToSpl { + source_ctoken_account, + destination_spl_token_account, + amount, + authority: authority.pubkey(), + mint, + payer: payer.pubkey(), + token_pool_pda, + token_pool_pda_bump, + spl_token_program: Pubkey::new_from_array(SPL_TOKEN_PROGRAM_ID), +} +.instruction()?; + +rpc.create_and_send_transaction( + &[transfer_ix], + &payer.pubkey(), + &signers +).await?; +``` diff --git a/compressed-token-program/ctoken/ctoken-transfer.mdx b/compressed-token-program/ctoken/ctoken-transfer.mdx new file mode 100644 index 0000000..b0b88a9 --- /dev/null +++ b/compressed-token-program/ctoken/ctoken-transfer.mdx @@ -0,0 +1,53 @@ +--- +title: Transfer cToken to cToken account +description: Transfer tokens between two cToken accounts. +--- + + +Transfers tokens between two cToken accounts. Follows SPL Token semantics and includes automatic rent top-ups for compressible accounts. + +**Use when:** Performing standard token transfers between users who both hold decompressed CToken accounts. + +**Key parameters:** + +- `source`: Public key of the source CToken account +- `destination`: Public key of the destination CToken account +- `amount`: Number of tokens to transfer (u64) +- `authority`: Public key of the authority (owner or delegate) that can spend from source +- `payer`: (Optional) Public key paying for transaction fees and rent top-ups + +**Example:** + +```rust +use light_client::rpc::Rpc; +use light_token_client::actions::ctoken_transfer::create_transfer_ctoken_instruction; + +async fn example_ctoken_transfer( + rpc: &mut R, + source_pubkey: Pubkey, + destination_pubkey: Pubkey, + amount: u64, + authority_keypair: &Keypair, + payer_keypair: &Keypair, +) -> Result<(), RpcError> { + let transfer_instruction = create_transfer_ctoken_instruction( + source_pubkey, + destination_pubkey, + amount, + authority_keypair.pubkey(), + )?; + + let mut signers = vec![payer_keypair]; + if authority_keypair.pubkey() != payer_keypair.pubkey() { + signers.push(authority_keypair); + } + + rpc.create_and_send_transaction( + &[transfer_instruction], + &payer_keypair.pubkey(), + &signers + ).await?; + + Ok(()) +} +``` \ No newline at end of file diff --git a/compressed-token-program/ctoken/mint-actions.mdx b/compressed-token-program/ctoken/mint-actions.mdx new file mode 100644 index 0000000..3bc6980 --- /dev/null +++ b/compressed-token-program/ctoken/mint-actions.mdx @@ -0,0 +1,43 @@ +--- +title: Mint actions overview +description: Builder instructions for creating and managing compressed token accounts and transfers. +--- + +The CToken SDK provides builder instructions for managing compressed token accounts. These instructions follow a consistent builder pattern and handle account creation, minting, transfers, and conversions between compressed and SPL token formats. + +## Account creation + +### CreateCTokenAccount + + + +### CreateAssociatedTokenAccount + +### CreateAssociatedTokenAccount2 + + +## Mint operations + +### CreateCMint + + +### MintToCTokenTransfer + +## Transfer operations + +### CtokenTransfer + + +### SplToCtokenTransfer + + +### CtokenToSpl + +### CtokenToSplTransferAndClose + +## Account management + +### Close Token Account + +### CompressAndClose mode + diff --git a/compressed-token-program/ctoken/mint-ctokens.mdx b/compressed-token-program/ctoken/mint-ctokens.mdx new file mode 100644 index 0000000..8c17201 --- /dev/null +++ b/compressed-token-program/ctoken/mint-ctokens.mdx @@ -0,0 +1,33 @@ +--- +title: Mint cTokens +description: Mint new tokens directly to decompressed CToken accounts. +--- + +Part of the MintAction batch instruction. + +**Use when:** Issuing new tokens of a specific compressed mint to users holding CToken accounts. + +**Key parameters:** + +- `account_index`: Index into remaining accounts for the recipient token account (u8) +- `amount`: Number of tokens to mint (u64) + +**Example:** + +```rust +use light_compressed_token_sdk::compressed_token::mint_action::{ + MintActionCompressedInstructionData, + MintToCTokenAction, +}; + +let instruction_data = MintActionCompressedInstructionData::new_mint( + input.compressed_mint_with_context.address, + input.compressed_mint_with_context.root_index, + compressed_proof, + input.compressed_mint_with_context.mint.clone(), +) +.with_mint_to_ctoken(MintToCTokenAction { + account_index: 0, // First account in remaining accounts + amount: 1_000_000, +}); +``` \ No newline at end of file diff --git a/compressed-tokens/overview.mdx b/compressed-token-program/overview.mdx similarity index 73% rename from compressed-tokens/overview.mdx rename to compressed-token-program/overview.mdx index 1a9614a..dcb7699 100644 --- a/compressed-tokens/overview.mdx +++ b/compressed-token-program/overview.mdx @@ -8,14 +8,10 @@ import AdvancedGuidesTable from '/snippets/compressed-tokens-advanced-guides-tab import SetupEnvironment from '/snippets/setup-environment-tabs.mdx'; import InstallDependencies from '/snippets/install-dependencies-codegroup.mdx'; -| Creation | Regular SPL Token | Compressed Token | Cost Reduction | +| Creation | SPL Token | Compressed Token | Cost Reduction | |:---------------------|:------------------|:----------------------|:---------------| | 100 Token Accounts | ~ 0.2 SOL | **~ 0.00004 SOL** | **5000x** | -Compressed token accounts store information about an individual's ownership of a specific token (mint). Different from regular token accounts, they don't require an Associated Token Account (ATA) per token holder. - -For example, this simplifies [token distribution](https://github.com/Lightprotocol/developer-content/blob/main/zk-compression-docs/compressed-tokens/implementation-guides/create-an-airdrop.md), since you don't need to allocate a token account per recipient. - #### Compressed Tokens at a Glance diff --git a/compressed-tokens/advanced-guides.mdx b/compressed-tokens/advanced-guides.mdx deleted file mode 100644 index 34b0cd5..0000000 --- a/compressed-tokens/advanced-guides.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Advanced Guides -description: "Reference table to advanced guides. Includes guides for airdrops, using token-2022, wallet support for compressed tokens, and client examples." -sidebarTitle: "Overview" ---- - -import AdvancedGuidesTable from '/snippets/compressed-tokens-advanced-guides-table.mdx'; - - diff --git a/compressed-tokens/guides.mdx b/compressed-tokens/guides.mdx deleted file mode 100644 index 4d0a1c6..0000000 --- a/compressed-tokens/guides.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Guides -description: "Overview of guides to compressed token operations and reference table with descriptions. Guides include full code examples, troubleshooting, and advanced configurations." -sidebarTitle: "Overview" ---- - -import GuidesTable from '/snippets/compressed-tokens-guides-table.mdx'; - - diff --git a/docs.json b/docs.json index 3b50878..b8e85ef 100644 --- a/docs.json +++ b/docs.json @@ -36,35 +36,79 @@ ] }, { - "group": "Compressed Tokens", + "group": "Compressed Token Program", "pages": [ - "compressed-tokens/overview", + "compressed-token-program/overview", + "compressed-token-program/c-token-program", { - "group": "Guides", + "group": "cMint", "pages": [ - "compressed-tokens/guides", - "compressed-tokens/guides/how-to-create-compressed-token-accounts", - "compressed-tokens/guides/how-to-mint-compressed-tokens", - "compressed-tokens/guides/how-to-transfer-compressed-token", - "compressed-tokens/guides/how-to-compress-and-decompress-spl-tokens", - "compressed-tokens/guides/how-to-compress-complete-spl-token-accounts", - "compressed-tokens/guides/how-to-create-and-register-a-mint-account-for-compression", - "compressed-tokens/guides/how-to-create-compressed-token-pools-for-mint-accounts", - "compressed-tokens/guides/how-to-merge-compressed-token-accounts", - "compressed-tokens/guides/how-to-approve-and-revoke-delegate-authority" + "compressed-token-program/cmint/cmint", + "compressed-token-program/cmint/update-metadata" ] }, { - "group": "Advanced Guides", + "group": "cToken", "pages": [ - "compressed-tokens/advanced-guides", - "compressed-tokens/advanced-guides/how-to-combine-operations-in-one-transaction", - "compressed-tokens/advanced-guides/create-an-airdrop", - "compressed-tokens/advanced-guides/create-an-airdrop-with-claim", - "compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens", - "compressed-tokens/advanced-guides/use-token-2022-with-compression", - "compressed-tokens/advanced-guides/example-web-client", - "compressed-tokens/advanced-guides/example-node-js" + "compressed-token-program/ctoken/mint-actions", + { + "group": "Guides", + "expanded": true, + "pages": [ + "compressed-token-program/ctoken/create-ctoken", + "compressed-token-program/ctoken/mint-ctokens", + "compressed-token-program/ctoken/create-ata", + "compressed-token-program/ctoken/ctoken-transfer", + "compressed-token-program/ctoken/SPL-to-ctoken-transfer", + "compressed-token-program/ctoken/ctoken-to-spl-decompress", + "compressed-token-program/ctoken/compress-and-close", + "compressed-token-program/ctoken/close-ctoken" + ] + } + ] + }, + { + "group": "Compressed Token", + "pages": [ + "compressed-token-program/compressed-tokens/compressed-token-overview", + { + "group": "Basic Guides", + "pages": [ + "compressed-token-program/compressed-tokens/basic-guides/how-to-create-compressed-token-accounts", + "compressed-token-program/compressed-tokens/basic-guides/how-to-mint-compressed-tokens", + "compressed-token-program/compressed-tokens/basic-guides/how-to-transfer-compressed-token", + "compressed-token-program/compressed-tokens/basic-guides/how-to-compress-and-decompress-spl-tokens", + "compressed-token-program/compressed-tokens/basic-guides/how-to-compress-complete-spl-token-accounts", + "compressed-token-program/compressed-tokens/basic-guides/how-to-create-and-register-a-mint-account-for-compression", + "compressed-token-program/compressed-tokens/basic-guides/how-to-create-compressed-token-pools-for-mint-accounts", + "compressed-token-program/compressed-tokens/basic-guides/how-to-merge-compressed-token-accounts", + "compressed-token-program/compressed-tokens/basic-guides/how-to-approve-and-revoke-delegate-authority" + ] + }, + { + "group": "Advanced Guides", + "pages": [ + { + "group": "Integration", + "expanded": true, + "pages": [ + "compressed-token-program/compressed-tokens/advanced-guides/how-to-combine-operations-in-one-transaction", + "compressed-token-program/compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens", + "compressed-token-program/compressed-tokens/advanced-guides/use-token-2022-with-compression" + ] + }, + { + "group": "Examples", + "expanded": true, + "pages": [ + "compressed-token-program/compressed-tokens/advanced-guides/create-an-airdrop", + "compressed-token-program/compressed-tokens/advanced-guides/create-an-airdrop-with-claim", + "compressed-token-program/compressed-tokens/advanced-guides/example-web-client", + "compressed-token-program/compressed-tokens/advanced-guides/example-node-js" + ] + } + ] + } ] } ] @@ -163,33 +207,78 @@ ] }, { - "tab": "Compressed Tokens", + "tab": "Compressed Token Program", "pages": [ - "compressed-tokens/overview", + "compressed-token-program/overview", + "compressed-token-program/c-token-program", { - "group": "Guides", + "group": "cMint", "pages": [ - "compressed-tokens/guides/how-to-create-compressed-token-accounts", - "compressed-tokens/guides/how-to-mint-compressed-tokens", - "compressed-tokens/guides/how-to-transfer-compressed-token", - "compressed-tokens/guides/how-to-compress-and-decompress-spl-tokens", - "compressed-tokens/guides/how-to-compress-complete-spl-token-accounts", - "compressed-tokens/guides/how-to-create-and-register-a-mint-account-for-compression", - "compressed-tokens/guides/how-to-create-compressed-token-pools-for-mint-accounts", - "compressed-tokens/guides/how-to-merge-compressed-token-accounts", - "compressed-tokens/guides/how-to-approve-and-revoke-delegate-authority" + "compressed-token-program/cmint/cmint", + "compressed-token-program/cmint/update-metadata" ] }, { - "group": "Advanced Guides", + "group": "cToken", "pages": [ - "compressed-tokens/advanced-guides/how-to-combine-operations-in-one-transaction", - "compressed-tokens/advanced-guides/create-an-airdrop", - "compressed-tokens/advanced-guides/create-an-airdrop-with-claim", - "compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens", - "compressed-tokens/advanced-guides/use-token-2022-with-compression", - "compressed-tokens/advanced-guides/example-web-client", - "compressed-tokens/advanced-guides/example-node-js" + "compressed-token-program/ctoken/mint-actions", + { + "group": "Guides", + "pages": [ + "compressed-token-program/ctoken/ctoken", + "compressed-token-program/ctoken/create-ctoken", + "compressed-token-program/ctoken/create-ata", + "compressed-token-program/ctoken/ctoken-transfer", + "compressed-token-program/ctoken/SPL-to-ctoken-transfer", + "compressed-token-program/ctoken/ctoken-to-spl-decompress", + "compressed-token-program/ctoken/compress-and-close", + "compressed-token-program/ctoken/close-ctoken" + ] + } + ] + }, + { + "group": "Compressed Token", + "pages": [ + "compressed-token-program/compressed-tokens/compressed-token-overview", + { + "group": "Basic Guides", + "pages": [ + "compressed-token-program/compressed-tokens/basic-guides/how-to-create-compressed-token-accounts", + "compressed-token-program/compressed-tokens/basic-guides/how-to-mint-compressed-tokens", + "compressed-token-program/compressed-tokens/basic-guides/how-to-transfer-compressed-token", + "compressed-token-program/compressed-tokens/basic-guides/how-to-compress-and-decompress-spl-tokens", + "compressed-token-program/compressed-tokens/basic-guides/how-to-compress-complete-spl-token-accounts", + "compressed-token-program/compressed-tokens/basic-guides/how-to-create-and-register-a-mint-account-for-compression", + "compressed-token-program/compressed-tokens/basic-guides/how-to-create-compressed-token-pools-for-mint-accounts", + "compressed-token-program/compressed-tokens/basic-guides/how-to-merge-compressed-token-accounts", + "compressed-token-program/compressed-tokens/basic-guides/how-to-approve-and-revoke-delegate-authority" + ] + }, + { + "group": "Advanced Guides", + "pages": [ + { + "group": "Integration", + "expanded": true, + "pages": [ + "compressed-token-program/compressed-tokens/advanced-guides/how-to-combine-operations-in-one-transaction", + "compressed-token-program/compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens", + "compressed-token-program/compressed-tokens/advanced-guides/use-token-2022-with-compression" + ] + }, + { + "group": "Examples", + "expanded": true, + "pages": [ + "compressed-token-program/compressed-tokens/advanced-guides/create-an-airdrop", + "compressed-token-program/compressed-tokens/advanced-guides/create-an-airdrop-with-claim", + "compressed-token-program/compressed-tokens/advanced-guides/example-web-client", + "compressed-token-program/compressed-tokens/advanced-guides/example-node-js" + ] + } + ] + } ] } ] diff --git a/mintlify-docs/docs b/mintlify-docs/docs index 89f3ae6..d872c7a 160000 --- a/mintlify-docs/docs +++ b/mintlify-docs/docs @@ -1 +1 @@ -Subproject commit 89f3ae6014495a18f8ef8696ababacd867dc7ed1 +Subproject commit d872c7a0de0cfcc70c81292064b8968fb8809c2e diff --git a/snippets/compressed-tokens-advanced-guides-table.mdx b/snippets/compressed-tokens-advanced-guides-table.mdx index 049e422..875692c 100644 --- a/snippets/compressed-tokens-advanced-guides-table.mdx +++ b/snippets/compressed-tokens-advanced-guides-table.mdx @@ -1,9 +1,49 @@ -| Guide | Description | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | -| [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](/compressed-tokens/advanced-guides/create-an-airdrop-with-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 | -| [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](/compressed-tokens/advanced-guides/example-web-client) | Demonstrates how to use @lightprotocol/stateless.js in a browser environment to interact with ZK Compression | -| [Example Node.js Client](/compressed-tokens/advanced-guides/example-node-js) | Script to execute basic compression/decompression/transfers | + + + + + + + + + + + + + + + + + + + + + +
[Combine Instructions in One Transaction](/compressed-token-program/compressed-tokens/advanced-guides/how-to-combine-operations-in-one-transaction)Execute multiple token instructions within a single transaction
[Add Wallet Support for Compressed Tokens](/compressed-token-program/compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens)Add compressed token support in your wallet application
[Use Token-2022 with Compression](/compressed-token-program/compressed-tokens/advanced-guides/use-token-2022-with-compression)Create compressed Token-2022 mints with metadata and other extensions
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
[Create an Airdrop without Claim](/compressed-token-program/compressed-tokens/advanced-guides/create-an-airdrop)Distribute tokens that appear directly in recipients' wallets
(via WebApp or CLI)
[Example Airdrop with Claim](/compressed-token-program/compressed-tokens/advanced-guides/create-an-airdrop-with-claim)Demo for time-locked airdrop. Users can claim after vesting.
[Example Web Client](/compressed-token-program/compressed-tokens/advanced-guides/example-web-client)Demo to @lightprotocol/stateless.js in a browser environment
[Example Node.js Client](/compressed-token-program/compressed-tokens/advanced-guides/example-node-js)Script to execute basic compression/decompression/transfers
diff --git a/snippets/compressed-tokens-guides-table.mdx b/snippets/compressed-tokens-guides-table.mdx index 4248fd8..1717665 100644 --- a/snippets/compressed-tokens-guides-table.mdx +++ b/snippets/compressed-tokens-guides-table.mdx @@ -1,11 +1,46 @@ -| Guide | Description | -| :---------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | -| [Create Compressed Token Accounts](/compressed-tokens/guides/how-to-create-compressed-token-accounts) | Create compressed and learn difference to regular token accounts | -| [Mint Compressed Tokens](/compressed-tokens/guides/how-to-mint-compressed-tokens) | Create new compressed tokens to existing mint | -| [Transfer Compressed Tokens](/compressed-tokens/guides/how-to-transfer-compressed-token) | Move compressed tokens between compressed accounts | -| [Decompress and Compress Tokens](/compressed-tokens/guides/how-to-compress-and-decompress-spl-tokens) | Convert SPL tokens between regular and compressed format | -| [Compress Complete SPL Token Accounts](/compressed-tokens/guides/how-to-compress-complete-spl-token-accounts) | Compress complete SPL token accounts and reclaim rent afterwards | -| [Create and Register a Mint Account for Compression](/compressed-tokens/guides/how-to-create-and-register-a-mint-account-for-compression) | Create new SPL mint with token pool for compression | -| [Create Token Pools for Mint Accounts](/compressed-tokens/guides/how-to-create-compressed-token-pools-for-mint-accounts) | Create token pool for compression for existing SPL mints | -| [Merge Compressed Accounts](/compressed-tokens/guides/how-to-merge-compressed-token-accounts) | Consolidate multiple compressed accounts of the same mint into one | -| [Approve and Revoke Delegate Authority](/compressed-tokens/guides/how-to-approve-and-revoke-delegate-authority) | Approve or revoke delegates for compressed token accounts | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Create Compressed Token Accounts](/compressed-token-program/compressed-tokens/basic-guides/how-to-create-compressed-token-accounts)Create compressed and learn difference to regular token accounts
[Mint Compressed Tokens](/compressed-token-program/compressed-tokens/basic-guides/how-to-mint-compressed-tokens)Create new compressed tokens to existing mint
[Transfer Compressed Tokens](/compressed-token-program/compressed-tokens/basic-guides/how-to-transfer-compressed-token)Move compressed tokens between compressed accounts
[Decompress and Compress Tokens](/compressed-token-program/compressed-tokens/basic-guides/how-to-compress-and-decompress-spl-tokens)Convert SPL tokens between regular and compressed format
[Compress Complete SPL Token Accounts](/compressed-token-program/compressed-tokens/basic-guides/how-to-compress-complete-spl-token-accounts)Compress complete SPL token accounts and reclaim rent afterwards
[Create a Mint Account with Token Pool for Compression](/compressed-token-program/compressed-tokens/basic-guides/how-to-create-and-register-a-mint-account-for-compression)Create new SPL mint with token pool for compression
[Create Token Pools for Mint Accounts](/compressed-token-program/compressed-tokens/basic-guides/how-to-create-compressed-token-pools-for-mint-accounts)Create token pool for compression for existing SPL mints
[Merge Compressed Accounts](/compressed-token-program/compressed-tokens/basic-guides/how-to-merge-compressed-token-accounts)Consolidate multiple compressed accounts of the same mint into one
[Approve and Revoke Delegate Authority](/compressed-token-program/compressed-tokens/basic-guides/how-to-approve-and-revoke-delegate-authority)Approve or revoke delegates for compressed token accounts
\ No newline at end of file diff --git a/snippets/compressible-vs-solana-rent.mdx b/snippets/compressible-vs-solana-rent.mdx new file mode 100644 index 0000000..6022f6d --- /dev/null +++ b/snippets/compressible-vs-solana-rent.mdx @@ -0,0 +1,145 @@ + + +### Initial Rent Top-Up +The **creator of compressible accounts** tops-up the account with **rent for at least two epochs**. +Two epochs for compressible accounts have a length of **12,600 slots**. + +``` rust +rent_per_epoch = base_rent + (data_len * lamports_per_byte_per_epoch) + +// For 260-byte cToken account: +// 128 + (260 * 1) = 388 lamports per epoch +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentAmountDescription
Prepaid rent388 × N epochs*Rent for N epochs
Compression cost & incentive10,000 lamports
+ 1,000 lamports		Transaction cost for compression
+ protocol incentive
Transaction fee5,000-10,000 lamportsStandard Solana tx fees
+ +\* _`N` = `num_prepaid_epochs` parameter (0 or ≥ 2, set at creation)._ + +Normally, the **creator of Solana accounts** pays the **rent exemption balance equal to 2 years of rent** proportional to account size: + +``` rust +minimum_balance = (ACCOUNT_STORAGE_OVERHEAD + data_len) * lamports_per_byte * exemption_threshold + +/// Example 165 byte SPL token account: +/// minimum_balance = (128 + 165) * 6960 = 2,039,280 lamports +``` + +* Most Solana accounts are rarely accessed after creation, but continue to lock up SOL for the account's lifetime. +* The creator of Solana accounts still must pay the rent-exemption balance. +* The creator of compressible accounts only needs to pay the rent for the first two epochs. + + + +### Top-ups per Transaction + +The **transaction payer tops-up** the account with rent **when the account's lamports balance is below 2 epochs**. This keeps accounts decompressed while active. + + + + + + + + + + + + + + + + + + + + + + + + + + +
Account StatePayer CostExample
Funded for 2+ epochs0 lamportsNo top-up required
Funded for less than 2 epochs`lamports_per_write`Configured as 5,000 lamports
→ payer pays 5,000 lamports
Compressible
(ran out of rent)		`lamports_per_write + rent_deficit`Configured top-up: 5,000 lamports
Rent deficit: 3,000 lamports
Total payer cost: 8,000 lamports
+ + +Top-ups are additional to standard Solana transaction fees (typically <10,000 lamports). + + +### Closing compressible accounts + +Compressible accounts can be closed by two parties. How rent and lamports balance are distributed depends on which party closes the account. + +1. The **Account Owner** can close the account at any time, regardless of rent status. The account is not compressed in this case. + + + + + + + + + + + + + + + + + + +
Component and AmountRecipient
Rent exemption + completed epoch rentRent sponsor
Remaining lamports from top-up (partial epoch)Account Owner
+ +2. The **Compression Authority** can compress and close the account when it becomes compressible + + + + + + + + + + + + + + + + + + +
Component and AmountRecipient
Rent exemption + remaining epoch rent
Rent sponsor
Compression incentive
(11,000 lamports)		Forester node
+ +