pda_buddy/

lib.rs

//! # pda-buddy
//!
//! `pda-buddy` is a small Anchor helper for keeping PDA seed definitions in one
//! place.
//!
//! Anchor already has a good PDA model. This crate does not replace it.
//! Instead, it lets you define the seed ABI once on the PDA account type, then
//! reuse that definition in:
//!
//! - `#[account(...)]` constraints
//! - CPI signer seed arrays
//! - optional helper methods for finding or asserting PDAs
//!
//! The generated account constraints are normal Anchor-compatible
//! `seeds = [...]` and `bump` constraints, so IDL account resolution still works
//! the way Anchor expects.
//!
//! ## Runtime Cost
//!
//! `pda-buddy` is a proc-macro crate. It does not add an on-chain runtime
//! dependency or a second PDA validation layer to your program.
//!
//! Account bindings expand to Anchor's native `seeds = [...]` and `bump`
//! constraints. Signer bindings expand to local stack values and a normal
//! `&[&[&[u8]]]` signer seed slice. In a normal optimized deployment, this
//! should have the same CU and program-size profile as writing the equivalent
//! Anchor code by hand.
//!
//! The extra strict seed checks are Rust type checks generated at compile time.
//! They are emitted as no-op Anchor constraints that evaluate to `true`, so
//! optimized builds should remove them. Unchecked bindings with `!` skip those
//! strict checks entirely.
//!
//! ## Quick Example
//!
//! Define the PDA seed ABI on the account type:
//!
//! ```ignore
//! use anchor_lang::prelude::*;
//! use pda_buddy::pda;
//!
//! #[account]
//! #[pda(seeds = [
//!     prefix = b"message",
//!     from: Pubkey,
//!     to: Pubkey,
//!     id: u64,
//! ])]
//! pub struct Message {
//!     pub id: u64,
//! }
//! ```
//!
//! Use that ABI in an Anchor accounts context:
//!
//! ```ignore
//! use pda_buddy::pda_accounts;
//!
//! #[pda_accounts]
//! #[derive(Accounts)]
//! #[instruction(params: Params)]
//! pub struct Initialize<'info> {
//!     #[account(
//!         init,
//!         payer = payer,
//!         space = 8 + core::mem::size_of::<Message>(),
//!         pda(Message, [
//!             prefix,
//!             from = payer.key(),
//!             to = params.to,
//!             id = params.id,
//!         ])
//!     )]
//!     pub message: Account<'info, Message>,
//!
//!     #[account(mut)]
//!     pub payer: Signer<'info>,
//!
//!     pub system_program: Program<'info, System>,
//! }
//! ```
//!
//! `pda-buddy` expands the `pda(...)` binding into normal Anchor constraints:
//!
//! ```ignore
//! seeds = [
//!     b"message",
//!     payer.key().as_ref(),
//!     params.to.as_ref(),
//!     params.id.to_le_bytes().as_ref(),
//! ],
//! bump
//! ```
//!
//! Bindings may be written in any order. The final generated seed order always
//! follows the original `#[pda(seeds = [...])]` definition.
//!
//! ## Account Constraints
//!
//! Put `#[pda_accounts]` above `#[derive(Accounts)]`:
//!
//! ```ignore
//! #[pda_accounts]
//! #[derive(Accounts)]
//! pub struct MyCtx<'info> {
//!     // fields
//! }
//! ```
//!
//! Inside an Anchor `#[account(...)]` attribute, add a top-level
//! `pda(Type, [...])` item:
//!
//! ```ignore
//! #[account(
//!     mut,
//!     pda(Message, [
//!         prefix,
//!         from = user.key(),
//!         to = params.to,
//!         id = params.id,
//!     ])
//! )]
//! pub message: Account<'info, Message>,
//! ```
//!
//! Static seed bindings are written as just the label:
//!
//! ```ignore
//! prefix
//! ```
//!
//! Dynamic seed bindings are written as `label = expression`:
//!
//! ```ignore
//! from = user.key()
//! id = params.id
//! ```
//!
//! For `Pubkey` seeds, pass a `Pubkey` expression. If the seed value comes from
//! an Anchor account, call `.key()` explicitly:
//!
//! ```ignore
//! from = payer.key()
//! to = params.to
//! ```
//!
//! If you intentionally want to bypass account or signer seed type checks for
//! one binding, append `!` to the value. The generated seed expression is still
//! emitted normally, so the value must still support the generated seed
//! conversion such as `.as_ref()`:
//!
//! ```ignore
//! user = "custom-bytes"!
//! ```
//!
//! ## CPI Signer Seeds
//!
//! Use [`pda_signer!`] when a PDA signs a CPI:
//!
//! ```ignore
//! use pda_buddy::pda_signer;
//!
//! pda_signer!(
//!     let message_signer = Message,
//!     bump = ctx.bumps.message,
//!     [
//!         prefix,
//!         from = ctx.accounts.payer.key(),
//!         to = params.to,
//!         id = params.id,
//!     ]
//! );
//!
//! some_cpi_context.with_signer(message_signer);
//! ```
//!
//! The macro creates the temporary byte arrays needed for numeric seeds and bump
//! bytes in the caller scope. This keeps signer seeds lifetime-safe without heap
//! allocation.
//!
//! Signer seed bindings also support the unchecked marker:
//!
//! ```ignore
//! from = "wrong-but-i-want-this"!
//! ```
//!
//! ## Defining Seeds
//!
//! Seeds are declared in `#[pda(seeds = [...])]`.
//!
//! ```ignore
//! #[pda(seeds = [
//!     prefix = b"message",
//!     authority: Pubkey,
//!     slug: String,
//!     index: u64,
//!     shard: u16(be),
//!     active: bool,
//!     digest: [u8; 32],
//! ])]
//! pub struct Message {
//!     // account fields
//! }
//! ```
//!
//! Static seeds use `=`.
//!
//! ```ignore
//! prefix = b"message"
//! ```
//!
//! Static seeds must be byte-string literals or resolvable byte-string consts:
//!
//! ```ignore
//! impl Message {
//!     pub const PREFIX: &'static [u8] = b"message";
//! }
//!
//! #[pda(seeds = [
//!     prefix = Self::PREFIX,
//!     id: u64,
//! ])]
//! pub struct Message {
//!     pub id: u64,
//! }
//! ```
//!
//! Dynamic seeds use `:`.
//!
//! ```ignore
//! authority: Pubkey
//! id: u64
//! ```
//!
//! Supported dynamic seed types:
//!
//! | Seed type | Encoding |
//! | --- | --- |
//! | `Pubkey` | `pubkey.as_ref()` |
//! | `bytes`, `Bytes`, `[u8]`, `&[u8]`, `Vec<u8>` | `as_ref()` |
//! | `str`, `String` | `as_bytes()` |
//! | `bool` | one byte, `0` or `1` |
//! | `u8`, `i8` | one byte |
//! | `u16`, `u32`, `u64`, `i16`, `i32`, `i64` | little-endian by default |
//! | `u16(be)`, `u32(be)`, `u64(be)`, `i16(be)`, `i32(be)`, `i64(be)` | big-endian |
//! | `[u8; N]` | fixed byte array |
//!
//! `u64` and `u64(le)` are equivalent. `be` is explicit big-endian.
//!
//! ## Program ID
//!
//! By default, generated helper methods use `crate::ID` as the program id.
//!
//! If the PDA belongs to another program, set `program_id`:
//!
//! ```ignore
//! #[pda(
//!     seeds = [
//!         prefix = b"vault",
//!         owner: Pubkey,
//!     ],
//!     program_id = other_program::ID,
//! )]
//! pub struct Vault {
//!     pub owner: Pubkey,
//! }
//! ```
//!
//! The account-constraint rewrite still emits Anchor `seeds` and `bump`
//! constraints. Use Anchor's native `seeds::program = ...` support separately
//! if you need cross-program PDA validation in an accounts context.
//!
//! ## Helper Methods
//!
//! `#[pda(...)]` can generate helper methods:
//!
//! ```ignore
//! #[pda(
//!     seeds = [
//!         prefix = b"message",
//!         id: u64,
//!     ],
//!     features = [find, assert],
//! )]
//! pub struct Message {
//!     pub id: u64,
//! }
//! ```
//!
//! `find` generates:
//!
//! ```ignore
//! let (address, bump) = Message::find_pda(id, None);
//! ```
//!
//! `assert` generates:
//!
//! ```ignore
//! let bump = Message::assert_pda(&address, id, None)?;
//! ```
//!
//! The final argument is an optional program id override:
//!
//! ```ignore
//! let (address, bump) = Message::find_pda(id, Some(&custom_program_id));
//! ```
//!
//! ## Diagnostics
//!
//! The macros validate seed labels and binding kinds. If a label is missing,
//! duplicated, unknown, or bound in the wrong form, the compiler error includes
//! the original PDA seed definition and the expected binding shape.
//!
//! For example, if `from: Pubkey` is accidentally written as just `from`, the
//! error points out that the expected binding is:
//!
//! ```text
//! from = <Pubkey expression>
//! ```
//!
//! ## Notes
//!
//! - `#[pda_accounts]` must appear above `#[derive(Accounts)]`.
//! - `pda(...)` inside `#[account(...)]` must be a top-level account constraint item.
//! - Static seed labels are bound by label only. Dynamic seed labels need `label = value`.
//! - Complex runtime expressions are allowed, but Anchor may not include them in IDL PDA metadata. Simple paths, fields, and common Anchor calls like `.key()` are the most IDL-friendly.
//! - This crate scans the consumer crate's `src/**/*.rs` files to find `#[pda(...)]` definitions. Keep PDA account definitions in normal source files under `src`.
//!
use proc_macro::TokenStream;
use syn::{ItemStruct, parse_macro_input};

use crate::pda::PdaArgs;

mod accounts;
mod binding;
mod pda;
mod registry;
mod signer;
mod spec;

/// The main `#[pda(...)]` attribute macro. This is where the PDA seed ABI is defined.
///
/// usage example:
/// ```ignore
/// #[account]
/// #[pda(
///     seeds = [
///         prefix = b"message",
///         from: Pubkey,
///         to: Pubkey,
///         id: u64,
///     ],
///     // optional, defaults to the current crate ID
///     program_id = crate::ID,
///     // optional, defaults to all disabled
///     features = [
///         find, // generates "find_pda" method for struct
///         assert // generates "assert_pda" method for struct
///     ]
/// )]
/// pub struct Message {
///     pub id: u64,
/// }
/// ```
#[proc_macro_attribute]
pub fn pda(args: TokenStream, input: TokenStream) -> TokenStream {
    let args = parse_macro_input!(args as PdaArgs);
    let item = parse_macro_input!(input as ItemStruct);

    match args.expand(&item) {
        Ok(tokens) => tokens.into(),
        Err(err) => err.to_compile_error().into(),
    }
}

/// The `#[pda_accounts]` attribute macro. This must be placed on any `struct` that contains fields using `pda(...)` bindings.
///
/// usage:
/// ```ignore
/// #[pda_accounts]
/// #[derive(Accounts)]
/// pub struct MyCtx<'info> {
///     // example account using `pda(...)` binding with the `Message` struct defined in the previous example:
///     #[account(pda(Message, [
///         prefix,
///         from = some_pubkey,
///         to = some_other_pubkey,
///         id = some_id,
///         // ...
///     ]))]
///     pub my_pda_account: Account<'info, Message>,
///     // ...
/// }
/// ```
#[proc_macro_attribute]
pub fn pda_accounts(args: TokenStream, input: TokenStream) -> TokenStream {
    if !args.is_empty() {
        return syn::Error::new(
            proc_macro2::Span::call_site(),
            "`#[pda_accounts]` does not take arguments",
        )
        .to_compile_error()
        .into();
    }

    let item = parse_macro_input!(input as ItemStruct);

    match accounts::expand::expand_pda_accounts(item) {
        Ok(tokens) => tokens.into(),
        Err(err) => err.to_compile_error().into(),
    }
}

/// The `pda_signer!(...)` macro for generating CPI signer seeds.
///
/// usage example:
/// ```ignore
/// pda_signer!(
///     let message_signer = Message,
///     bump = ctx.bumps.message,
///     [
///         prefix,
///         from = ctx.accounts.payer.key(),
///         to = params.to,
///         id = params.id,
///     ]
/// );
/// ```
///
/// Then use `message_signer` in a `with_signer` call:
/// ```ignore
/// some_cpi_context.with_signer(message_signer).some_cpi_method(...);
/// ```
#[proc_macro]
pub fn pda_signer(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as signer::SignerInput);

    match input.expand() {
        Ok(tokens) => tokens.into(),
        Err(err) => err.to_compile_error().into(),
    }
}