Core Primitives

/**
 * Branded string type for Solana addresses ensuring type safety
 */
type Address<TAddress = string> = TAddress & { readonly __brand: unique symbol };

/**
 * Create and validate a Solana address from string
 * @param input - Base58-encoded address string
 * @returns Validated Address type
 * @throws SolanaError if input is not a valid address
 */
function address<TAddress extends string>(input: TAddress): Address<TAddress>;

/**
 * Type guard to check if a value is a valid Address
 * @param input - Value to check
 * @returns True if input is an Address
 */
function isAddress(input: unknown): input is Address;

/**
 * Assert that a value is a valid Address, throwing if not
 * @param input - Value to assert
 * @throws SolanaError if input is not a valid Address
 */
function assertIsAddress(input: unknown): asserts input is Address;

import { address, isAddress } from "@solana/web3.js";

// Create address from string
const myAddress = address("11111111111111111111111111111112");

// Type guard usage
if (isAddress(someValue)) {
  // someValue is now typed as Address
  console.log("Valid address:", someValue);
}

// Assertion usage
assertIsAddress(userInput); // Throws if invalid
console.log("Definitely an address:", userInput);

/**
 * Program derived address with its bump seed
 */
type ProgramDerivedAddress<TAddress = Address> = readonly [TAddress, ProgramDerivedAddressBump];

/**
 * Bump seed value for PDA derivation (0-255)
 */
type ProgramDerivedAddressBump = number & { readonly __brand: unique symbol };

/**
 * Derive a Program Derived Address from seeds and program ID
 * @param config - Seeds and program ID for derivation
 * @returns PDA tuple with address and bump
 */
function getProgramDerivedAddress(config: {
  seeds: Uint8Array[];
  programId: Address;
}): Promise<ProgramDerivedAddress>;

/**
 * Type guard for Program Derived Addresses
 * @param input - Value to check
 * @returns True if input is a PDA
 */
function isProgramDerivedAddress(input: unknown): input is ProgramDerivedAddress;

/**
 * Create address using seed derivation
 * @param config - Base address, seed, and program ID
 * @returns Derived address
 */
function createAddressWithSeed(config: {
  baseAddress: Address;
  seed: string;
  programId: Address;
}): Address;

/**
 * Branded string type for Ed25519 signatures
 */
type Signature = string & { readonly __brand: unique symbol };

/**
 * Raw signature bytes (64 bytes for Ed25519)
 */
type SignatureBytes = Uint8Array & { readonly __brand: unique symbol };

/**
 * Type guard to check if a value is a valid Signature
 * @param input - Value to check
 * @returns True if input is a Signature
 */
function isSignature(input: unknown): input is Signature;

/**
 * Assert that a value is a valid Signature
 * @param input - Value to assert
 * @throws SolanaError if input is not a valid Signature
 */
function assertIsSignature(input: unknown): asserts input is Signature;

/**
 * Branded bigint type for lamport amounts ensuring precision
 */
type Lamports = bigint & { readonly __brand: unique symbol };

/**
 * Create lamports amount from number or bigint
 * @param input - Amount in lamports
 * @returns Branded Lamports type
 */
function lamports(input: bigint | number): Lamports;

import { lamports } from "@solana/web3.js";

// Create lamport amounts
const oneSOL = lamports(1_000_000_000n);
const halfSOL = lamports(500_000_000);

// Arithmetic operations preserve type safety
const total = lamports(BigInt(oneSOL) + BigInt(halfSOL));

/**
 * Branded bigint for Solana slot numbers
 */
type Slot = bigint & { readonly __brand: unique symbol };

/**
 * Branded bigint for Unix timestamps
 */
type UnixTimestamp = bigint & { readonly __brand: unique symbol };

/**
 * Branded string type for block hashes
 */
type Blockhash = string & { readonly __brand: unique symbol };

/**
 * Commitment level for RPC requests
 */
type Commitment = "processed" | "confirmed" | "finalized";

/**
 * Commitment configuration object
 */
interface CommitmentConfig {
  commitment?: Commitment;
}

import { createSolanaRpc } from "@solana/web3.js";

const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");

// Use different commitment levels
const processedInfo = await rpc.getAccountInfo(address, {
  commitment: "processed"
}).send();

const finalizedInfo = await rpc.getAccountInfo(address, {
  commitment: "finalized"
}).send();

/**
 * Get encoder for Address types
 * @returns Codec encoder for addresses
 */
function getAddressEncoder(): Encoder<Address, Uint8Array>;

/**
 * Get decoder for Address types
 * @returns Codec decoder for addresses
 */
function getAddressDecoder(): Decoder<Uint8Array, Address>;

/**
 * Get combined codec for Address types
 * @returns Full address codec for encoding/decoding
 */
function getAddressCodec(): Codec<Address, Uint8Array>;

/**
 * Get comparison function for addresses
 * @returns Function to compare two addresses
 */
function getAddressComparator(): (a: Address, b: Address) => number;

/**
 * Check if compressed point bytes represent a valid curve point
 * @param bytes - 32-byte compressed point
 * @returns True if bytes are on the Ed25519 curve
 */
function compressedPointBytesAreOnCurve(bytes: Uint8Array): boolean;

/**
 * Convert CryptoKey public key to Address
 * @param publicKey - CryptoKey containing public key
 * @returns Solana address derived from public key
 */
function getAddressFromPublicKey(publicKey: CryptoKey): Promise<Address>;

/**
 * Configuration for address validation
 */
interface AddressConfig {
  /**
   * Whether to perform strict validation
   * @default true
   */
  strict?: boolean;
}

/**
 * Result of address operations
 */
interface AddressResult<T = Address> {
  /**
   * The validated address
   */
  address: T;
  /**
   * Whether validation was successful
   */
  valid: boolean;
  /**
   * Error message if validation failed
   */
  error?: string;
}