coral_xyz library
Dart client for Solana programs — Anchor, Quasar, and Pinocchio.
Provides runtime IDL parsing, Borsh serialization, zero-copy account decoding, PDA derivation, and fluent method builders for interacting with on-chain programs.
import 'package:coral_xyz/coral_xyz.dart';
final idl = Idl.fromJson(jsonDecode(idlString));
final program = Program(idl, programId, provider);
await program.methods['initialize']!([])
.accounts({'counter': counterAddress})
.rpc();
final data = await program.account['Counter']!.fetch(counterAddress);
Classes
- AccountAlreadyInitialized
- AccountBorrowFailed
-
AccountClient<
T> - Client for fetching and managing accounts of a specific type
- AccountDataTooSmall
- AccountDefBuilder
- Builder for defining an account data layout.
- AccountErrorCode
- Account error codes (3000-3999)
-
AccountFetcher<
T> - Enhanced account fetcher with caching and batch operations
- AccountFetcherConfig
- Configuration for the account fetcher
- AccountLayout
- Account layout with discriminator and type definition
- AccountMeta
- Account meta for instruction execution
- AccountNameOrigin
- Account name origin implementation
- AccountNamespace
- The account namespace provides handles to AccountClient objects for each account type in a program.
- AccountNotRentExempt
- AccountResolverFactory
- Factory for creating account resolvers
-
AccountsCoder<
A extends String> - Interface for encoding and decoding program accounts matching TypeScript AccountsCoder
- AccountsCoderFactory
- Create the appropriate accounts coder for the given IDL.
- AccountsResolver
- Resolves account addresses for instruction contexts
-
AccountSubscription<
T> - Account subscription management
-
AccountWithContext<
T> - Account data with RPC context
- AddressFormatter
- Address formatting and display utilities
- AddressResolver
- Address resolution utilities for account management
- AddressUtils
- Address utilities for Solana and Anchor programs
- AnchorBorsh
- Anchor-specific Borsh serialization extensions
- AnchorConstants
- Common constants used throughout the Anchor client
- AnchorProgram
- Annotation for Anchor program code generation
- AnchorProvider
- The main provider implementation that combines Connection and Wallet
- AnchorTransaction
- Transaction containing multiple instructions
- ArithmeticOverflow
-
AutoCoder<
A extends String, T extends String> - Auto-detecting Coder that dispatches to the correct implementations based on the IDL format.
- BasicTransactionSimulationResult
- Transaction simulation result
- BinaryReader
- Binary reader for deserializing data in little-endian format
- BinaryWriter
- Binary writer for serializing data in little-endian format
-
BorshAccountsCoder<
A extends String> - Enhanced Borsh-based implementation of AccountsCoder
-
BorshCoder<
A extends String, T extends String> - Borsh-based implementation of the main Coder interface
-
BorshDeserializable<
T> - Interface for Borsh-deserializable types
- BorshDeserializer
- Borsh deserializer
- BorshEventCoder
- Borsh-based implementation of EventCoder
- BorshInstructionCoder
- Borsh-based implementation of InstructionCoder
- BorshIoError
- BorshSerializable
- Interface for Borsh-serializable types
- BorshSerializer
- Main Borsh serializer and deserializer
- BorshStruct
- A Borsh-serializable struct base class
-
BorshTypesCoder<
N extends String> - Enhanced Borsh-based implementation of TypesCoder with generics support
- BorshUtils
- Borsh utilities for Anchor-specific serialization
- Build
- Build information from registry
- BytesSeed
- Bytes seed implementation
- ByteUtils
- Utility functions for working with bytes
-
CachedAccountData<
T> - Cached account data with metadata
- CacheStatistics
- Cache performance statistics
- Clock
- CodamaParser
- Parser that converts Codama JSON into the flat Idl model.
-
Coder<
A extends String, T extends String> - Main coder interface for all serialization/deserialization operations
- CoderFactory
- Factory for creating the appropriate Coder based on the IDL.
- CommitmentConfig
- Configuration for commitment in RPC requests
- CommitmentConfigs
- Convenience constructors for common commitment configurations
- ComparedAccountNames
- Account names compared values implementation
- ComparedPublicKeys
- Public keys compared values implementation
- ComparedValues
- Union type for compared values in error messages
- ComputeBudgetExceeded
- ConfirmOptions
- Default confirmation options for transactions
- Connection
- Connection to a Solana cluster for RPC communication
- ConnectionConfig
- Configuration for Solana RPC connection
- ConstraintErrorCode
- Constraint error codes (2000-2499)
-
Context<
T> - Context for instruction execution
- ContextAccountResolver
- Utility for resolving accounts from context
- ContextSplitResult
- Result of splitting arguments and context
- CustomError
- DeploymentResult
- Deployment result
- DeprecatedErrorCode
- Deprecated error codes (5000)
- DiscriminatorComputer
- Core discriminator computation engine that matches TypeScript Anchor client discriminator computation byte-for-byte.
- DynamicAccounts
- Implementation of Accounts that uses a dynamic map structure
- EnhancedWorkspaceBuilder
- Enhanced workspace builder with TypeScript-like features
- EpochSchedule
- ErrorCode
- Represents an error code with both string and numeric representations
- ErrorInfo
- Error information container
-
Event<
E extends IdlEvent, T> - Represents a decoded program event
- EventAuthority
- Utility for deriving and working with EventAuthority PDAs.
- EventCoder
- Interface for parsing and decoding program events
- EventInstructionErrorCode
- Event instruction error codes (1500)
- EventLayout
- Internal event layout information
- EventManager
- Event management system matching TypeScript Anchor's EventManager exactly
- EventParser
- Parser for extracting events from transaction logs
- EventStats
- Statistics about event processing
- ExecutedInstruction
- ExecutionFailure
- ExecutionResult
-
Result returned by
QuasarSvm.processInstructionandprocessInstructionChain. - ExecutionStatus
- ExecutionSuccess
- ExecutionTrace
- FeaturesConfig
- Features configuration section
- FeaturesUtils
- Feature flag management utilities
- FileLine
- Represents a file and line location for error reporting
- FileLineOrigin
- File line origin implementation
- Idl
- The Main IDL Class
- IdlAccount
- Program account definition
- IdlAccountAnnotation
- Annotation for custom account definitions
- IdlConst
- Constant definition
- IdlDefinedType
- Defined type with optional generic parameters
- IdlDependency
- Program dependency information
- IdlDeployments
- Program deployment addresses for different networks
- IdlEnumVariant
- Enum variant definition
- IdlErrorAnnotation
- Annotation for custom error definitions
- IdlErrorCode
- Program error code definition
- IdlEvent
- Program event definition
- IdlField
- Field definition for structs, enums, and instruction arguments
- IdlInstruction
- Program instruction definition
- IdlInstructionAccount
- Single instruction account with PDA support
- IdlInstructionAccountItem
- Base class for instruction account items (supports both single accounts and account groups)
- IdlInstructionAccounts
- Group of instruction accounts (composite accounts)
- IdlInstructionAnnotation
- Annotation for custom instruction definitions
- IdlInstructionErrorCode
- IDL instruction error codes (1000-1999)
- IdlMetadata
- IDL metadata containing program information
- IdlPda
- PDA (Program Derived Address) specification
- IdlProgramAccount
- IDL Program Account structure for on-chain IDL storage
- IdlRepr
- Representation attribute for type definitions
- IdlSeed
- Base class for PDA seeds
- IdlSeedAccount
- Account-based seed for PDA derivation
- IdlSeedArg
- Argument-based seed for PDA derivation
- IdlSeedConst
- Constant seed for PDA derivation
- IdlType
- Type specification for fields and arguments
- IdlTypeAnnotation
- Annotation for custom IDL type definitions
- IdlTypeDef
- Type definition
- IdlTypeDefGeneric
- Generic type parameter definition for type definitions
- IdlTypeDefType
- Type definition type (struct, enum, type alias)
- IdlTypeGeneric
- Generic parameter specification for defined types
- IdlUtils
- Utilities for fetching and processing IDLs from the blockchain
- IllegalOwner
- Immutable
- IncorrectAuthority
- IncorrectProgramId
- Instruction
- A decoded program instruction
- InstructionAccount
- Formatted instruction account
- InstructionArg
- Formatted instruction argument
- InstructionBuilder
- Builder for creating individual transaction instructions
- InstructionCoder
- Interface for encoding and decoding program instructions
- InstructionDefBuilder
- Builder for defining a single instruction.
- InstructionDisplay
- Formatted instruction display for debugging and analysis
- InstructionErrorCode
- Instruction error codes (100-999)
- InstructionLayout
- Internal instruction layout information
- InstructionNamespace
- The instruction namespace provides functions to build TransactionInstruction objects for each method of a program.
- InsufficientFunds
- InvalidAccountData
- InvalidAccountOwner
- InvalidArgument
- InvalidInstructionData
- InvalidRealloc
- InvalidSeeds
- KeyedAccount
- An account with an address — the universal type for passing state into the VM.
- Keypair
- A Solana keypair containing both public and private keys
- KeypairWallet
- A wallet implementation backed by espresso-cash Ed25519HDKeyPair
- LangErrorCode
- Combined error code constants matching TypeScript LangErrorCode
- LogMessage
- Log message from transaction simulation or execution
- MaxAccountsDataAllocationsExceeded
- MaxInstructionTraceLengthExceeded
- MaxSeedLengthExceeded
- MethodsNamespace
- The methods namespace provides a fluent interface for building and executing program methods with type-safe parameters.
- MintOpts
- Options for creating a mint account.
- MiscellaneousErrorCode
- Miscellaneous error codes (4100-4999)
- MissingAccount
- MissingRequiredSignature
- NamespaceFactory
- Factory for creating namespace instances for a program
- NamespaceSet
- Container for all namespace types
- NodeWallet
- Node wallet functionality - matches TypeScript NodeWallet
- NumberSeed
- Number seed implementation (supports various integer types)
- NumberUtils
- Utility functions for working with numbers and precision
- Origin
- Union type for error origin (either string account name or file location)
- PdaDerivationEngine
- Core engine for PDA derivation with optimization and validation
- PdaResult
- Result of PDA derivation containing address and bump seed
- PdaSeed
- Represents a seed used in PDA derivation
- PdaSeedResolver
- Resolves Quasar/Anchor IDL PDA definitions into derivable seed byte arrays.
- PdaUtils
- Utilities for working with Program Derived Addresses (PDAs)
-
Program<
T extends Idl> - Core Program Class for Anchor Program Interactions
-
ProgramAccount<
T> - Program account with address and data
- ProgramCommon
- Translation utilities for addresses - matches TypeScript program/common
- ProgramConfig
- Configuration for a single program in the workspace
- ProgramData
- Program data from upgradeable loader
- ProgramEntry
- Program entry configuration with optional IDL path and address
- ProgramErrorStack
- Stack of programs being executed, used for tracking CPI calls
- ProgramInterface
- Entry point for manually defining a program interface.
- ProgramInterfaceBuilder
- Builder for constructing a complete Idl from manual definitions.
- ProviderConfig
- Provider configuration section from Anchor.toml
- PublicKeySeed
- PublicKey seed implementation
- PublicKeyUtils
- Static utilities for PublicKey operations
- QuasarSvm
- In-process Solana Virtual Machine for deterministic program testing.
- QuasarSvmConfig
- Configuration for QuasarSvm creation.
- RegistryUtils
- Registry utilities for program verification and builds
- RequireErrorCode
- Require error codes (2500-2999)
-
Result<
T, E> - Result type for operations that can fail
- RpcFunction
- Function for sending a signed transaction for a specific instruction
- RpcNamespace
- The RPC namespace provides async methods to send signed transactions for each method of a program.
- RpcResponseContext
- RPC response context information
- RuntimeError
- ScriptsConfig
- Scripts configuration section
- SendTransactionConfig
- Configuration for transaction sending
- Signature
- Solana transaction signature
- Signer
- Signer interface for accounts that can sign transactions
- SimulateFunction
- Function for simulating a transaction for a specific instruction
- SimulateNamespace
- The simulation namespace provides functions to simulate transactions for each method of a program without sending them to the blockchain.
- SimulationResult
- Simulation result for transactions
- StringSeed
- String seed implementation
- StringUtils
- Utility functions for working with strings
- SvmProgramError
- Base class for all program errors returned by the SVM.
- SystemProgram
- Solana System Program utilities
- TestConfig
- Test configuration section from Anchor.toml
- TokenAccountOpts
- Options for creating a token account.
- TokenBalance
- TokenUtils
- Token program utilities
- TransactionBuilder
- Builder for creating transactions with specific instructions
- TransactionConfirmation
- Transaction confirmation status
- TransactionError
- Transaction error information
- TransactionInstruction
- Transaction instruction for Solana programs
- TransactionNamespace
- The transaction namespace provides functions to build Transaction objects for each method of a program.
- TransactionRecord
- Record of a completed transaction
- TransactionResult
- Transaction result containing signature
- TransactionSimulationConfig
- Transaction simulation configuration matching TypeScript SDK
- TransactionSimulator
- Production-ready transaction simulator using espresso-cash components PHASE 0 IMPLEMENTATION: Zero manual RPC code, 100% battle-tested components
- TransactionStatus
- Status of a transaction confirmation
- TransactionWithSigners
- A transaction bundled with its additional signers
- TypeConverter
- Unified type conversion utilities
- TypeDefBuilder
- Builder for defining a custom type (struct or enum).
- TypeSafeMethodBuilder
- Type-safe method builder with fluent API
-
TypesCoder<
N extends String> - Interface for encoding and decoding user-defined types
- UninitializedAccount
- UnsupportedSysvar
- UpgradeResult
- Upgrade result
- ValidatorAccount
- Validator account configuration for testing
- ViewFunction
- A view function that can be called to get read-only data from a program
- ViewsNamespace
- The views namespace provides read-only method calls that return data without modifying blockchain state.
- Wallet
- Abstract wallet interface matching TypeScript SDK exactly
- Workspace
- TypeScript-like workspace for managing multiple Anchor programs with lazy loading
- WorkspaceBuilder
- Workspace builder for fluent API
- WorkspaceConfig
- Complete workspace configuration from Anchor.toml
- WorkspaceConfigTemplate
- Workspace configuration template detection
- WorkspaceDiscovery
- Advanced workspace discovery and initialization tools
- WorkspaceHealthReport
- Workspace health report with validation results
- WorkspaceInitializationTemplate
- Workspace initialization template
- WorkspaceIssue
- Individual workspace issue
- WorkspaceProxy
- Proxy that provides dynamic program access from workspace configuration.
- WorkspaceStats
- Statistics about the workspace
- WorkspaceTemplate
- Workspace template for initialization
- WorkspaceValidationResult
- Workspace validation result
-
ZeroCopyAccountsCoder<
A extends String> -
Zero-copy accounts coder for Quasar
#[repr(C)]accounts.
Enums
- Commitment
- Commitment level for Solana transactions and queries
- IdlFormat
- Identifies which Solana framework generated an IDL.
- ProgramStatus
- Program status enumeration
- WebSocketState
- WebSocket connection state
- WorkspaceComplexity
- Workspace complexity levels
- WorkspaceIssueType
- Workspace issue types
- WorkspaceType
- Workspace types
Mixins
- BorshSerializableMixin
- A helper for creating Borsh-serializable data classes
Extensions
- AnchorBorshDeserializer on BorshDeserializer
- Extension methods for BorshDeserializer to add Anchor-specific types
- AnchorBorshSerializer on BorshSerializer
- Extension methods for BorshSerializer to add Anchor-specific types
- BorshDeserializerExtensions on BorshDeserializer
- BorshSerializerExtensions on BorshSerializer
- Extension methods for common Borsh operations
- IdlTypeConversion on IdlType
- Extension methods for IdlType to add conversion utilities
- PublicKeyBorsh on PublicKey
- Extension methods for PublicKey to add Borsh serialization support
- PublicKeyExtensions on PublicKey
- Extensions for PublicKey to maintain API compatibility
Constants
- lamportsPerSol → const int
- Lamports per SOL.
-
langErrorMessage
→ const Map<
int, String> - Error code to message mapping matching TypeScript LangErrorMessage
- loaderV2 → const int
- BPF Loader v2 (used by SPL Token, SPL Associated Token).
- loaderV3 → const int
- BPF Loader v3 (used by most programs, including SPL Token-2022).
- mintSize → const int
- SPL Mint account data size (82 bytes).
- packageVersion → const String
- Package version.
- quasarSvmConfigFull → const QuasarSvmConfig
- Default config that loads all SPL programs.
- supportedIdlVersion → const String
- Supported Anchor IDL specification version.
- tokenAccountSize → const int
- SPL Token Account data size (165 bytes).
Properties
- splAssociatedTokenProgramId → PublicKey
-
SPL Associated Token Account program ID.
final
- splToken2022ProgramId → PublicKey
-
SPL Token-2022 program ID.
final
- splTokenProgramId → PublicKey
-
SPL Token program ID.
final
- systemProgramId → PublicKey
-
System program ID.
final
- workspace → WorkspaceProxy
-
Global workspace instance for TypeScript-like lazy program loading.
no setter
Functions
-
createIdlErrorMap(
Idl idl) → Map< int, String> - Creates a map of error codes to error messages from an IDL
-
createKeyedAssociatedTokenAccount(
PublicKey wallet, PublicKey mint, int amount, {PublicKey? tokenProgramId}) → KeyedAccount - Create a pre-initialized associated token account. The address is derived from wallet, mint, and token program.
-
createKeyedMintAccount(
PublicKey address, {MintOpts opts = const MintOpts(), PublicKey? tokenProgramId}) → KeyedAccount - Create a pre-initialized mint account.
-
createKeyedSystemAccount(
PublicKey address, {int lamports = lamportsPerSol}) → KeyedAccount - Create a system-owned account with the given lamports. Defaults to 1 SOL if omitted.
-
createKeyedTokenAccount(
PublicKey address, {required TokenAccountOpts opts, PublicKey? tokenProgramId}) → KeyedAccount - Create a pre-initialized token account.
-
getErrorMessage(
int errorCode) → String - Helper function to get error message for a given error code
-
getProvider(
) → AnchorProvider - Get current global provider instance.
-
idlTypeArray(
IdlType inner, int size) → IdlType -
idlTypeBool(
) → IdlType -
idlTypeDefined(
String name) → IdlType -
idlTypeDynString(
int maxLength) → IdlType -
idlTypeDynVec(
IdlType items, int maxLength) → IdlType -
idlTypeI16(
) → IdlType -
idlTypeI32(
) → IdlType -
idlTypeI64(
) → IdlType -
idlTypeI8(
) → IdlType -
idlTypeOption(
IdlType inner) → IdlType -
idlTypePubkey(
) → IdlType -
idlTypeString(
) → IdlType -
idlTypeTail(
String element) → IdlType -
idlTypeU16(
) → IdlType -
idlTypeU32(
) → IdlType -
idlTypeU64(
) → IdlType -
idlTypeU8(
) → IdlType -
idlTypeVec(
IdlType inner) → IdlType -
isCompositeAccounts(
IdlInstructionAccountItem accountItem) → bool - Utility function to check if an account item is a composite accounts group
-
loadElf(
String name) → Uint8List - Load a program ELF file by name from the known program directory.
-
rentMinimumBalance(
int dataLen) → int - Default Solana rent: minimum_balance(dataLen) = (dataLen + 128) * 3480 * 2
-
setProvider(
AnchorProvider provider) → void - Set the global provider instance.
-
splitArgsAndContext(
IdlInstruction idlInstruction, List args) → ContextSplitResult - Helper function to split arguments and context from method parameters
-
svmProgramErrorFromStatus(
int status, String? errorMessage) → SvmProgramError -
Map a wire status code to a SvmProgramError.
Codes match Rust
program_error_to_i32: known errors are negative, Custom(n) is positive. -
translateError(
dynamic err, Map< int, String> idlErrors) → dynamic - Error translation function matching TypeScript translateError
Typedefs
-
AccountMap<
I extends List< IdlAccount> > = Map<String, IdlAccount> - Returns a type map of account name to the IdlAccount
-
Accounts
= Map<
String, dynamic> - Generic accounts type for instruction contexts. Accepts PublicKey, String (base58), or null values — the AccountsResolver converts them to PublicKey during resolution.
-
AllAccounts<
I extends Idl> = List< IdlAccount> - All accounts for an IDL
-
AllEvents<
I extends Idl> = List< IdlEvent> - All events for an IDL
-
AllInstructions<
I extends Idl> = List< IdlInstruction> - Type definitions for namespace generation system
- ErrorOrigin = Origin
- Error origin type (placeholder for compatibility)
-
EventCallback<
T> = void Function(T event, int slot, String signature) - TypeScript-compatible event callback type
-
IdlDiscriminator
= List<
int> - Discriminator for identifying different types on-chain
-
InstructionMap<
I extends List< IdlInstruction> > = Map<String, IdlInstruction> - Returns a type map of instruction name to the IdlInstruction
- PublicKey = Ed25519HDPublicKey
- Re-export Ed25519HDPublicKey as PublicKey for compatibility
- TransactionSignature = String
- Transaction signature (base-58 encoded string)
- VersionedTransaction = CompiledMessage
- VersionedTransaction typedef — delegates to espresso-cash CompiledMessage.
Exceptions / Errors
- AccountCoderError
- Error thrown when account coder operations fail
- AccountDidNotDeserializeError
- Account did not deserialize error (3003)
- AccountDiscriminatorMismatchError
- Account discriminator mismatch error (3002)
- AccountError
- Base class for all account-specific errors
- AccountNotFoundException
- Exception thrown when an account is not found
- AccountNotInitializedError
- Account not initialized error (3012)
- AnchorError
- Base Anchor error class matching TypeScript AnchorError
- AnchorException
- Exception base class for Anchor-related errors
- BorshException
- Exception thrown by Borsh operations
- EventCoderException
- Exception thrown by event coder operations
- EventException
- Exception thrown by event system operations
- EventParseException
- Exception thrown during event parsing
- IdlError
- Base exception class for IDL-related errors
- InstructionCoderException
- Exception thrown by instruction coder operations
- InvalidPublicKeyException
- Exception thrown when a public key is invalid
- PdaDerivationException
- Exception thrown during PDA derivation operations
- ProgramError
- Error from a user-defined program
- ProviderException
- Exception thrown by provider operations
- ProviderTransactionException
- Exception thrown when a transaction fails to send
- SerializationException
- Exception thrown when serialization fails
- TransactionException
- Exception thrown when a transaction fails
- TypesCoderException
- Exception thrown by types coder operations
- WorkspaceConfigException
- Exception thrown when workspace configuration is invalid