ContractSpec
in package
Contract specification parser and type converter for Soroban smart contracts
This class parses contract spec entries extracted from contract WASM bytecode and provides utilities for working with contract functions, types, and arguments. It handles conversion between native PHP values and XDR SCVal types based on the contract specification, enabling type-safe contract interactions.
The contract spec includes function signatures, user-defined types (structs, unions, enums), error definitions, and event specifications as defined in SEP-48.
Tags
Table of Contents
Properties
- $entries : array<string|int, mixed>
Methods
- __construct() : mixed
- Creates a new contract spec from parsed spec entries
- events() : array<string|int, XdrSCSpecEventV0>
- Retrieves all event specifications from the contract spec
- findEntry() : XdrSCSpecEntry|null
- Finds a spec entry by name across all entry types
- funcArgsToXdrSCValues() : array<string|int, XdrSCVal>
- Converts native PHP arguments to XDR SCVal values for a contract function call
- funcs() : array<string|int, XdrSCSpecFunctionV0>
- Retrieves all function specifications from the contract spec
- getFunc() : XdrSCSpecFunctionV0|null
- Retrieves the function specification for a specific function name
- nativeToXdrSCVal() : XdrSCVal
- Converts a native PHP value to an XDR SCVal based on the contract spec type
- udtEnums() : array<string|int, XdrSCSpecUDTEnumV0>
- Retrieves all user-defined enum type specifications
- udtErrorEnums() : array<string|int, XdrSCSpecUDTErrorEnumV0>
- Retrieves all user-defined error enum type specifications
- udtStructs() : array<string|int, XdrSCSpecUDTStructV0>
- Retrieves all user-defined struct type specifications
- udtUnions() : array<string|int, XdrSCSpecUDTUnionV0>
- Retrieves all user-defined union type specifications
Properties
$entries
public
array<string|int, mixed>
$entries
Methods
__construct()
Creates a new contract spec from parsed spec entries
public
__construct(array<string|int, XdrSCSpecEntry> $entries) : mixed
Parameters
- $entries : array<string|int, XdrSCSpecEntry>
-
The parsed contract specification entries from the contract bytecode.
events()
Retrieves all event specifications from the contract spec
public
events() : array<string|int, XdrSCSpecEventV0>
Returns event definitions including event names, topics, and data fields for all events that can be emitted by the contract.
Return values
array<string|int, XdrSCSpecEventV0> —Array of event specifications
findEntry()
Finds a spec entry by name across all entry types
public
findEntry(string $name) : XdrSCSpecEntry|null
Searches for a function, struct, union, enum, error enum, or event with the given name and returns the matching spec entry.
Parameters
- $name : string
-
The name of the entry to find
Return values
XdrSCSpecEntry|null —The spec entry or null if not found
funcArgsToXdrSCValues()
Converts native PHP arguments to XDR SCVal values for a contract function call
public
funcArgsToXdrSCValues(string $name, array<string, mixed> $args) : array<string|int, XdrSCVal>
Takes a function name and associative array of named arguments, looks up the function specification, and converts each argument to the appropriate XDR SCVal type based on the function's parameter types. The returned array is ordered by parameter position.
Supported PHP types include primitives (int, string, bool), arrays (for vectors/tuples/maps), Address objects, and BigInt values for large integers. See the Soroban documentation for full type mapping details.
Parameters
- $name : string
-
The name of the function to call
- $args : array<string, mixed>
-
Associative array of argument name to value (e.g., ["amount" => 1000])
Tags
Return values
array<string|int, XdrSCVal> —Array of converted XDR values in parameter order
funcs()
Retrieves all function specifications from the contract spec
public
funcs() : array<string|int, XdrSCSpecFunctionV0>
Returns the XDR function definitions including function names, input parameters, output types, and documentation strings.
Return values
array<string|int, XdrSCSpecFunctionV0> —Array of function specifications
getFunc()
Retrieves the function specification for a specific function name
public
getFunc(string $name) : XdrSCSpecFunctionV0|null
Searches the contract spec for a function with the given name and returns its specification including parameters and return type.
Parameters
- $name : string
-
The name of the function to look up
Return values
XdrSCSpecFunctionV0|null —The function specification or null if not found
nativeToXdrSCVal()
Converts a native PHP value to an XDR SCVal based on the contract spec type
public
nativeToXdrSCVal(mixed $val, XdrSCSpecTypeDef $ty) : XdrSCVal
Performs type-safe conversion from PHP native types to Soroban XDR SCVal types according to the contract specification. Handles primitives, collections, user-defined types, and special types like addresses and big integers.
Supported conversions include:
- Primitives: int, string, bool
- Collections: arrays to vectors, tuples, or maps
- BigInts: GMP resources or numeric strings for 128/256-bit integers
- Addresses: Address objects or G/C-prefixed strings
- UDTs: Custom structs, unions, and enums
Parameters
- $val : mixed
-
The native PHP value to convert
- $ty : XdrSCSpecTypeDef
-
The expected Soroban type from the contract spec
Tags
Return values
XdrSCVal —The converted XDR value
udtEnums()
Retrieves all user-defined enum type specifications
public
udtEnums() : array<string|int, XdrSCSpecUDTEnumV0>
Returns enum definitions including case names and values for all enums defined in the contract.
Return values
array<string|int, XdrSCSpecUDTEnumV0> —Array of enum specifications
udtErrorEnums()
Retrieves all user-defined error enum type specifications
public
udtErrorEnums() : array<string|int, XdrSCSpecUDTErrorEnumV0>
Returns error enum definitions including error codes and messages for all error types defined in the contract.
Return values
array<string|int, XdrSCSpecUDTErrorEnumV0> —Array of error enum specifications
udtStructs()
Retrieves all user-defined struct type specifications
public
udtStructs() : array<string|int, XdrSCSpecUDTStructV0>
Returns struct definitions including field names and types for all structs defined in the contract.
Return values
array<string|int, XdrSCSpecUDTStructV0> —Array of struct specifications
udtUnions()
Retrieves all user-defined union type specifications
public
udtUnions() : array<string|int, XdrSCSpecUDTUnionV0>
Returns union definitions including case names and their associated types for all unions defined in the contract.
Return values
array<string|int, XdrSCSpecUDTUnionV0> —Array of union specifications