solana-py

The Solana Cookbook provides a collection of Python-based guides for common Solana development tasks. These guides are categorized into several functional areas to help you build applications using the solana-py client.

Available Guide Categories:

• Development Guides: Connecting to clusters, getting test SOL, subscribing to events, and creating accounts.
• Account Management: Calculating rent exemption costs, creating Program Derived Address (PDA) accounts, and retrieving balances.
• Token Operations: Managing SPL tokens, including creating tokens, minting, burning, transferring, and working with wrapped SOL.
• Transaction Operations: Sending SOL/Tokens, calculating fees, adding memos, adding priority fees, and optimizing compute units.
• Wallet Management: Generating keypairs, restoring from seed phrases, and signing/verifying messages.

The Memo program is a utility for validating UTF-8 encoded strings and verifying that provided accounts are signers of the transaction. It logs the memo text and the verified signer addresses to the transaction log, allowing observers to verify that specific addresses approved the memo.

Operational Rules:

• Unsigned Memos: If zero accounts are provided, the instruction succeeds if the memo is valid UTF-8.
• Signed Memos: If one or more accounts are provided, all provided accounts must be valid signers of the transaction for the instruction to succeed.

Understanding the components of a PDA is essential for managing program state and token accounts on Solana:

• PDA (Program Derived Address): A deterministic address derived from a set of seeds and a program ID. It is not controlled by a private key but by the program itself.
• Seed: A string (or bytes) used as input to derive the PDA address. The same seed always produces the same PDA for a given program.
• Bump: A specific value used during derivation to ensure the resulting address does not lie on the ed25519 curve, making it a valid PDA.
• Program ID: The unique identifier of the program that will own and control the PDA account.
• Deterministic: Because the derivation process is mathematical, the same seeds and program ID will always result in the same address.

When working with Solana transactions, understand these core concepts:

• Lamports: The smallest unit of SOL. 1 SOL is equal to 1,000,000,000 lamports.
• System Program: A built-in Solana program that handles fundamental operations like SOL transfers.
• Versioned Transactions: The modern transaction format that supports features like address lookup tables.
• Blockhash: A recent hash used to ensure transaction validity and prevent replay attacks. You must fetch a recent blockhash from the RPC to include in your transaction message.

The Memo program is subject to the cluster's compute budget. Compute usage is consumed by parsing UTF-8, verifying signers, and logging.

Constraints:

• There is an inverse relationship between memo length/complexity and the number of signers supported.
• As of v1.5.1, an unsigned instruction can support single-byte UTF-8 up to 566 bytes.
• An instruction with a simple 32-byte memo can support up to 12 signers.

The django-solana-payments package provides several high-level features for managing Solana transactions within Django:

• Transaction verification: Automatic payment confirmation and verification.
• Frontend Widget: A reusable widget that includes QR code generation and crypto wallet connection capabilities.
• Token Support: Support for both SOL and SPL token payment flows.
• Model Customization: Customizable models for payments and tokens.
• Framework Integration: Native support for both Django and Django REST Framework.
• Security: Encryption support for one-time payment wallets.

Wrapped SOL (wSOL)

Wraps native SOL into the SPL Token format, allowing it to be used in DeFi protocols, trading pairs, and programs that only support the SPL Token interface.

Native Mint

The special token mint address used for wrapped SOL: So11111111111111111111111111111111111111112.

Sync Native

A mechanism to synchronize the balance of native token accounts. When transferring SOL directly to a wSOL account, sync_native() must be called to update the account's internal token balance to match the SOL amount.

Unwrapping

The process of converting wSOL back to native SOL by closing the associated token account.

Key Concepts

• Keypair: A public-private key pair used for Solana account operations.
• Public Key: The account address that can be safely shared.
• Private Key: The secret key that must be kept secure and never shared.
• Cryptography: Uses Ed25519 elliptic curve cryptography.

Security Best Practices

• Never share your private key: Anyone with the private key has full control of the account.
• Store securely: Save private keys in encrypted storage or hardware wallets.
• Backup safely: Create secure backups of your keypairs.
• Generate offline: For maximum security, generate keypairs on offline systems.

When working with SPL tokens, understand these core abstractions:

• SPL Tokens: The standard token implementation on Solana (similar to ERC-20).
• Token Mint: The unique address that identifies the specific type of token.
• Token Accounts: The specific accounts that hold a balance of a particular token mint.
• Transfer Checked: A secure transfer method that validates the mint and decimals during the transaction to prevent errors.
• Decimals: The number of decimal places used by the token (e.g., USDC uses 6 decimals).

Because AsyncClient is asynchronous, it must be explicitly closed to release resources. You should use one of the following two patterns:

1. Context Manager (Recommended): Use async with AsyncClient(...) as client: to ensure automatic cleanup.
2. Manual Close: Call await client.close() when the client is no longer needed.