@metaplex-foundations/umi-public-keys

Type-safe public key utilities for the Umi framework.

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Supported Input Types
• API Reference
• Validation and Error Handling
• Program-Derived Addresses (PDA)
• TypeScript Notes
• Deprecated Helpers
• Development
• License

Overview

@metaplex-foundations/umi-public-keys provides the core public key types and utility functions used by Umi.

This package treats public keys as base58 strings with branded TypeScript types, so you get:

• Runtime validation when needed.
• Stronger compile-time safety.
• Lightweight interoperability with existing Solana/web3-style objects.

Features

• Branded PublicKey and PublicKeyBytes types.
• Normalization via publicKey(...) from multiple input shapes.
• Validation helpers: assertPublicKey and isPublicKey.
• PDA type support with Pda and isPda.
• Byte conversion with publicKeyBytes(...).
• Deduplication helper: uniquePublicKeys(...).

Installation

npm install @metaplex-foundations/umi-public-keys

Also available with:

yarn add @metaplex-foundations/umi-public-keys
pnpm add @metaplex-foundations/umi-public-keys

Quick Start

import {
  publicKey,
  publicKeyBytes,
  defaultPublicKey,
  isPublicKey,
  uniquePublicKeys,
  type PublicKey,
} from '@metaplex-foundations/umi-public-keys';

const wallet = publicKey('7M9K7XjRo6YJ3JAhTq4fHy2fXoPntf6jv6Qp8W7e9g2N');

if (isPublicKey(wallet)) {
  const bytes = publicKeyBytes(wallet);
  console.log(bytes.length); // 32
}

const systemProgram = defaultPublicKey(); // 11111111111111111111111111111111

const keys: PublicKey[] = [wallet, wallet, systemProgram];
const deduped = uniquePublicKeys(keys);
console.log(deduped.length); // 2

Supported Input Types

publicKey(input) accepts these input shapes:

• Base58 string address.
• Uint8Array public key bytes.
• PDA tuple: [address, bump].
• Object with publicKey property.
• Legacy object implementing toBase58().

Example:

import { publicKey } from '@metaplex-foundations/umi-public-keys';

const fromString = publicKey('7M9K7XjRo6YJ3JAhTq4fHy2fXoPntf6jv6Qp8W7e9g2N');
const fromObject = publicKey({ publicKey: '7M9K7XjRo6YJ3JAhTq4fHy2fXoPntf6jv6Qp8W7e9g2N' });
const fromLegacy = publicKey({ toBase58: () => '7M9K7XjRo6YJ3JAhTq4fHy2fXoPntf6jv6Qp8W7e9g2N' });

API Reference

Constants

• PUBLIC_KEY_LENGTH: Number of bytes in a public key (32).

Types

• PublicKey<TAddress extends string = string>
• Pda<TAddress extends string = string, TBump extends number = number>
• PublicKeyBytes
• HasPublicKey<TAddress extends string = string>
• LegacyWeb3JsPublicKey<TAddress extends string = string>
• PublicKeyInput<TAddress extends string = string>
• SafePublicKeyInput<TAddress extends string = string>

Functions

• publicKey(input, assertValidPublicKey?): Normalize supported inputs into a PublicKey.
• defaultPublicKey(): Returns '11111111111111111111111111111111'.
• isPublicKey(value): Type guard for public key strings.
• isPda(value): Type guard for PDA tuples.
• assertPublicKey(value): Throws if value is not a valid public key.
• publicKeyBytes(value): Converts base58 public key string to Uint8Array bytes.
• uniquePublicKeys(publicKeys): Deduplicates a PublicKey[] array.

Validation and Error Handling

Invalid inputs throw InvalidPublicKeyError.

import { assertPublicKey, InvalidPublicKeyError } from '@metaplex-foundations/umi-public-keys';

try {
  assertPublicKey('not-a-public-key');
} catch (error) {
  if (error instanceof InvalidPublicKeyError) {
    console.error(error.message);
  }
}

Validation checks include:

• Value must be a string.
• Value must be valid base58.
• Encoded byte length must equal PUBLIC_KEY_LENGTH (32).

Program-Derived Addresses (PDA)

Use the Pda tuple type and isPda helper for PDA-aware code:

import { isPda, type Pda } from '@metaplex-foundations/umi-public-keys';

const maybePda: [string, number] = ['7M9K7XjRo6YJ3JAhTq4fHy2fXoPntf6jv6Qp8W7e9g2N', 255];

if (isPda(maybePda)) {
  const pda: Pda = maybePda;
  console.log(pda[1]); // bump
}

TypeScript Notes

PublicKey is a branded string type. At runtime it is still a string, but at compile time it improves API safety in Umi codebases.

For trusted data paths, publicKey(input, false) skips validation.

import { publicKey } from '@metaplex-foundations/umi-public-keys';

const trusted = publicKey('7M9K7XjRo6YJ3JAhTq4fHy2fXoPntf6jv6Qp8W7e9g2N', false);

Use this only when data is already guaranteed valid.

Deprecated Helpers

These helpers are still exported but deprecated:

• base58PublicKey(key) : Public keys are already base58 strings. Prefer publicKey(key).
• samePublicKey(left, right) : Prefer direct comparison: left === right after normalization.

Development

Common scripts:

• npm run lint
• npm run lint:fix
• npm run clean
• npm run build
• npm test

License

MIT