@solana/addresses

@solana/addresses

This package contains utilities for generating account addresses. It can be used standalone, but it is also exported as part of the Solana JavaScript SDK @solana/web3.js@experimental.

Types

Base58EncodedAddress

This type represents a string that validates as a Solana address. Functions that require well-formed addresses should specify their inputs in terms of this type.

Whenever you need to validate an arbitrary string as a base58-encoded address, use the address(), assertIsAddress(), or isAddress() functions in this package.

Functions

address()

This helper combines asserting that a string is an address with coercing it to the Base58EncodedAddress type. It's best used with untrusted input.

import { address } from '@solana/addresses';

await transfer(address(fromAddress), address(toAddress), lamports(100000n));

When starting from a known-good address as a string, it's more efficient to typecast it rather than to use the address() helper, because the helper unconditionally performs validation on its input.

import { Base58EncodedAddress } from '@solana/addresses';

const MEMO_PROGRAM_ADDRESS =
    'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr' as Base58EncodedAddress<'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr'>;

assertIsAddress()

Client applications primarily deal with addresses and public keys in the form of base58-encoded strings. Addresses returned from the RPC API conform to the type Base58EncodedAddress. You can use a value of that type wherever a base58-encoded address is expected.

From time to time you might acquire a string, that you expect to validate as an address, from an untrusted network API or user input. To assert that such an arbitrary string is a base58-encoded address, use the assertIsAddress function.

import { assertIsAddress } from '@solana/addresses';

// Imagine a function that fetches an account's balance when a user submits a form.
function handleSubmit() {
    // We know only that what the user typed conforms to the `string` type.
    const address: string = accountAddressInput.value;
    try {
        // If this type assertion function doesn't throw, then
        // Typescript will upcast `address` to `Base58EncodedAddress`.
        assertIsAddress(address);
        // At this point, `address` is a `Base58EncodedAddress` that can be used with the RPC.
        const balanceInLamports = await rpc.getBalance(address).send();
    } catch (e) {
        // `address` turned out not to be a base58-encoded address
    }
}

getAddressDecoder()

Returns a decoder that you can use to convert an array of 32 bytes representing an address to the base58-encoded representation of that address. Returns a tuple of the Base58EncodedAddress and the offset within the byte array at which the decoder stopped reading.

import { getAddressDecoder } from '@solana/addresses';

const addressBytes = new Uint8Array([
    150, 183, 190, 48, 171, 8, 39, 156, 122, 213, 172, 108, 193, 95, 26, 158, 149, 243, 115, 254, 20, 200, 36, 30, 248,
    179, 178, 232, 220, 89, 53, 127,
]);
const addressDecoder = getAddressDecoder();
const [address, offset] = addressDecoder.decode(address); // [B9Lf9z5BfNPT4d5KMeaBFx8x1G4CULZYR1jA2kmxRDka, 32]

getAddressEncoder()

Returns an encoder that you can use to encode a base58-encoded address to a byte array.

import { getAddressEncoder } from '@solana/addresses';

const address = 'B9Lf9z5BfNPT4d5KMeaBFx8x1G4CULZYR1jA2kmxRDka' as Base58EncodedAddress;
const addressEncoder = getAddressEncoder();
const addressBytes = addressEncoder.encode(address);
// Uint8Array(32) [
//   150, 183, 190,  48, 171,   8, 39, 156,
//   122, 213, 172, 108, 193,  95, 26, 158,
//   149, 243, 115, 254,  20, 200, 36,  30,
//   248, 179, 178, 232, 220,  89, 53, 127
// ]

getAddressFromPublicKey()

Given a public CryptoKey, this method will return its associated Base58EncodedAddress.

import { getAddressFromPublicKey } from '@solana/addresses';

const address = await getAddressFromPublicKey(publicKey);

getProgramDerivedAddress()

Given a program's Base58EncodedAddress and up to 16 Seeds, this method will return the program derived address (PDA) associated with each.

import { getAddressEncoder, getProgramDerivedAddress } from '@solana/addresses';

const addressEncoder = getAddressEncoder();
const { bumpSeed, pda } = await getProgramDerivedAddress({
    programAddress: 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL' as Base58EncodedAddress,
    seeds: [
        // Owner
        addressEncoder.encode('9fYLFVoVqwH37C3dyPi6cpeobfbQ2jtLpN5HgAYDDdkm' as Base58EncodedAddress),
        // Token program
        addressEncoder.encode('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' as Base58EncodedAddress),
        // Mint
        addressEncoder.encode('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' as Base58EncodedAddress),
    ],
});

isAddress()

This is a type guard that accepts a string as input. It will both return true if the string conforms to the Base58EncodedAddress type and will refine the type for use in your program.

import { isAddress } from '@solana/addresses';

if (isAddress(ownerAddress)) {
    // At this point, `ownerAddress` has been refined to a
    // `Base58EncodedAddress` that can be used with the RPC.
    const { value: lamports } = await rpc.getBalance(ownerAddress).send();
    setBalanceLamports(lamports);
} else {
    setError(`${ownerAddress} is not an address`);
}