#[repr(transparent)]
pub struct Pubkey(_);

Implementations

👎 Deprecated since 1.3.9:

Please use ‘Pubkey::new_unique’ instead

unique Pubkey for tests and benchmarks.

Find a valid program derived address and its corresponding bump seed.

Program derived addresses (PDAs) are account keys that only the program, program_id, has the authority to sign. The address is of the same form as a Solana Pubkey, except they are ensured to not be on the ed25519 curve and thus have no associated private key. When performing cross-program invocations the program can “sign” for the key by calling invoke_signed and passing the same seeds used to generate the address, along with the calculated bump seed, which this function returns as the second tuple element. The runtime will verify that the program associated with this address is the caller and thus authorized to be the signer.

The seeds are application-specific, and must be carefully selected to uniquely derive accounts per application requirements. It is common to use static strings and other pubkeys as seeds.

Because the program address must not lie on the ed25519 curve, there may be seed and program id combinations that are invalid. For this reason, an extra seed (the bump seed) is calculated that results in a point off the curve. The bump seed must be passed as an additional seed when calling invoke_signed.

The processes of finding a valid program address is by trial and error, and even though it is deterministic given a set of inputs it can take a variable amount of time to succeed across different inputs. This means that when called from an on-chain program it may incur a variable amount of the program’s compute budget. Programs that are meant to be very performant may not want to use this function because it could take a considerable amount of time. Programs that are already at risk of exceeding their compute budget should call this with care since there is a chance that the program’s budget may be occasionally and unpredictably exceeded.

As all account addresses accessed by an on-chain Solana program must be explicitly passed to the program, it is typical for the PDAs to be derived in off-chain client programs, avoiding the compute cost of generating the address on-chain. The address may or may not then be verified by re-deriving it on-chain, depending on the requirements of the program. This verification may be performed without the overhead of re-searching for the bump key by using the create_program_address function.

Warning: Because of the way the seeds are hashed there is a potential for program address collisions for the same program id. The seeds are hashed sequentially which means that seeds {“abcdef”}, {“abc”, “def”}, and {“ab”, “cd”, “ef”} will all result in the same program address given the same program id. Since the chance of collision is local to a given program id, the developer of that program must take care to choose seeds that do not collide with each other. For seed schemes that are susceptible to this type of hash collision, a common remedy is to insert separators between seeds, e.g. transforming {“abc”, “def”} into {“abc”, “-”, “def”}.

Panics

Panics in the statistically improbable event that a bump seed could not be found. Use try_find_program_address to handle this case.

Panics if any of the following are true:

  • the number of provided seeds is greater than, or equal to, MAX_SEEDS,
  • any individual seed’s length is greater than MAX_SEED_LEN.
Examples

This example illustrates a simple case of creating a “vault” account which is derived from the payer account, but owned by an on-chain program. The program derived address is derived in an off-chain client program, which invokes an on-chain Solana program that uses the address to create a new account owned and controlled by the program itself.

By convention, the on-chain program will be compiled for use in two different contexts: both on-chain, to interpret a custom program instruction as a Solana transaction; and off-chain, as a library, so that clients can share the instruction data structure, constructors, and other common code.

First the on-chain Solana program:

// The custom instruction processed by our program. It includes the
// PDA's bump seed, which is derived by the client program. This
// definition is also imported into the off-chain client program.
// The computed address of the PDA will be passed to this program via
// the `accounts` vector of the `Instruction` type.
#[derive(BorshSerialize, BorshDeserialize, Debug)]
pub struct InstructionData {
    pub vault_bump_seed: u8,
    pub lamports: u64,
}

// The size in bytes of a vault account. The client program needs
// this information to calculate the quantity of lamports necessary
// to pay for the account's rent.
pub static VAULT_ACCOUNT_SIZE: u64 = 1024;

// The entrypoint of the on-chain program, as provided to the
// `entrypoint!` macro.
fn process_instruction(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    instruction_data: &[u8],
) -> ProgramResult {
    let account_info_iter = &mut accounts.iter();
    let payer = next_account_info(account_info_iter)?;
    // The vault PDA, derived from the payer's address
    let vault = next_account_info(account_info_iter)?;

    let mut instruction_data = instruction_data;
    let instr = InstructionData::deserialize(&mut instruction_data)?;
    let vault_bump_seed = instr.vault_bump_seed;
    let lamports = instr.lamports;
    let vault_size = VAULT_ACCOUNT_SIZE;

    // Invoke the system program to create an account while virtually
    // signing with the vault PDA, which is owned by this caller program.
    invoke_signed(
        &system_instruction::create_account(
            &payer.key,
            &vault.key,
            lamports,
            vault_size,
            &program_id,
        ),
        &[
            payer.clone(),
            vault.clone(),
        ],
        // A slice of seed slices, each seed slice being the set
        // of seeds used to generate one of the PDAs required by the
        // callee program, the final seed being a single-element slice
        // containing the `u8` bump seed.
        &[
            &[
                b"vault",
                payer.key.as_ref(),
                &[vault_bump_seed],
            ],
        ]
    )?;

    Ok(())
}

The client program:

fn create_vault_account(
    client: &RpcClient,
    program_id: Pubkey,
    payer: &Keypair,
) -> Result<()> {
    // Derive the PDA from the payer account, a string representing the unique
    // purpose of the account ("vault"), and the address of our on-chain program.
    let (vault_pubkey, vault_bump_seed) = Pubkey::find_program_address(
        &[b"vault", payer.pubkey().as_ref()],
        &program_id
    );

    // Get the amount of lamports needed to pay for the vault's rent
    let vault_account_size = usize::try_from(VAULT_ACCOUNT_SIZE)?;
    let lamports = client.get_minimum_balance_for_rent_exemption(vault_account_size)?;

    // The on-chain program's instruction data, imported from that program's crate.
    let instr_data = InstructionData {
        vault_bump_seed,
        lamports,
    };

    // The accounts required by both our on-chain program and the system program's
    // `create_account` instruction, including the vault's address.
    let accounts = vec![
        AccountMeta::new(payer.pubkey(), true),
        AccountMeta::new(vault_pubkey, false),
        AccountMeta::new(system_program::ID, false),
    ];

    // Create the instruction by serializing our instruction data via borsh
    let instruction = Instruction::new_with_borsh(
        program_id,
        &instr_data,
        accounts,
    );

    let blockhash = client.get_latest_blockhash()?;

    let transaction = Transaction::new_signed_with_payer(
        &[instruction],
        Some(&payer.pubkey()),
        &[payer],
        blockhash,
    );

    client.send_and_confirm_transaction(&transaction)?;

    Ok(())
}

Find a valid program derived address and its corresponding bump seed.

The only difference between this method and find_program_address is that this one returns None in the statistically improbable event that a bump seed cannot be found; or if any of find_program_address’s preconditions are violated.

See the documentation for find_program_address for a full description.

Create a valid program derived address without searching for a bump seed.

Because this function does not create a bump seed, it may unpredictably return an error for any given set of seeds and is not generally suitable for creating program derived addresses.

However, it can be used for efficiently verifying that a set of seeds plus bump seed generated by find_program_address derives a particular address as expected. See the example for details.

See the documentation for find_program_address for a full description of program derived addresses and bump seeds.

Examples

Creating a program derived address involves iteratively searching for a bump seed for which the derived Pubkey does not lie on the ed25519 curve. This search process is generally performed off-chain, with the find_program_address function, after which the client passes the bump seed to the program as instruction data.

Depending on the application requirements, a program may wish to verify that the set of seeds, plus the bump seed, do correctly generate an expected address.

The verification is performed by appending to the other seeds one additional seed slice that contains the single u8 bump seed, calling create_program_address, checking that the return value is Ok, and that the returned Pubkey has the expected value.

let (expected_pda, bump_seed) = Pubkey::find_program_address(&[b"vault"], &program_id);
let actual_pda = Pubkey::create_program_address(&[b"vault", &[bump_seed]], &program_id)?;
assert_eq!(expected_pda, actual_pda);

Log a Pubkey from a program

Trait Implementations

Converts this type into a mutable reference of the (usually inferred) input type.

Converts this type into a shared reference of the (usually inferred) input type.

Deserializes this instance from a given slice of bytes. Updates the buffer to point at the remaining bytes. Read more

Deserialize this instance from a slice of bytes.

Get the name of the type without brackets.

Recursively, using DFS, add type definitions required for this type. For primitive types this is an empty map. Type definition explains how to serialize/deserialize a type. Read more

Helper method to add a single type definition to the map.

Serialize this instance into a vector of bytes.

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Deserialize this value from the given Serde deserializer. Read more

Formats the value using the given formatter. Read more

Converts to this type from the input type.

The associated error which can be returned from parsing.

Parses a string s to return a value of this type. Read more

The wasm ABI type that this converts from when coming back out from the ABI boundary. Read more

Recover a Self from Self::Abi. Read more

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

The wasm ABI type that this converts into when crossing the ABI boundary. Read more

Convert self into Self::Abi so that it can be sent across the wasm ABI boundary. Read more

Tests whether the argument is a “none” instance. If so it will be deserialized as None, and otherwise it will be passed to FromWasmAbi. Read more

Returns an ABI instance indicating “none”, which JS will interpret as the None branch of this option. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

The wasm ABI type references to Self are recovered from.

The type that holds the reference to Self for the duration of the invocation of the function that has an &Self parameter. This is required to ensure that the lifetimes don’t persist beyond one function call, and so that they remain anonymous. Read more

Recover a Self::Anchor from Self::Abi. Read more

Same as RefFromWasmAbi::Abi

Same as RefFromWasmAbi::Anchor

Same as RefFromWasmAbi::ref_from_abi

Serialize this value into the given Serde serializer. Read more

The type returned in the event of a conversion error.

Performs the conversion.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Self must have the same layout as the specified Bits except for the possible invalid bit patterns being checked during is_valid_bit_pattern. Read more

If this function returns true, then it must be valid to reinterpret bits as &Self.

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The alignment of pointer.

The type for initializers.

Initializes a with the given initializer. Read more

Dereferences the given pointer. Read more

Mutably dereferences the given pointer. Read more

Drops the object pointed to by the given pointer. Read more

Same as IntoWasmAbi::Abi

Same as IntoWasmAbi::into_abi, except that it may throw and never return in the case of Err. Read more

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.