Stellar JS SDK

The Horizon ServerApi uses two primary patterns for retrieving data from the network:

1. CallFunction<T>: Used to fetch a single resource of type T. It returns a Promise<T>.
2. CallCollectionFunction<T>: Used to fetch a paginated collection of resources of type T. It returns a Promise<CollectionPage<T>>.

When calling a collection function, you can pass CallFunctionTemplateOptions to control the results.

// Example of using CallFunctionTemplateOptions with a collection
const collection = await horizonApi.someCollection({ 
  cursor: 'some_token', 
  limit: 10, 
  order: 'desc' 
});

An InvocationTree represents the call stack of Soroban operations. Each node in the tree has a type of either create or execute.

• create type: Uses CreateInvocation details. This can be a custom contract (type: 'wasm') or a Stellar Asset Contract (type: 'sac').
  • For wasm: Requires WasmCreateDetails (address, hash, salt, and optional constructor arguments).
  • For sac: Requires an asset string.
• execute type: Uses ExecuteInvocation details, specifying the contract source, the function name, and the args array.

Each node can contain a list of invocations (sub-invocations) that occur as a result of that node's execution, forming a tree structure.

A Signer bundles a signing function with a specific identity (address). This is preferred over bare signing callbacks because it ensures the SDK knows which address is performing the signature. The address can be a G... account address or a C... contract address for smart accounts.

An interface implementing Signer must provide:

• address: The string address of the signer.
• signTransaction: A function to sign a transaction envelope (matches SEP-43/Freighter shape).
• signAuthEntry (optional): A function to sign an authorization entry preimage (required for multi-party auth).

interface Signer {
  readonly address: string;
  signAuthEntry?: SignAuthEntry;
  signTransaction: SignTransaction;
}

The AssembledTransaction class is the primary tool for managing transactions under construction in the Client. It wraps a transaction and provides high-level interfaces for common workflows (like reading or writing to a contract) while allowing low-level access to the underlying stellar-sdk transaction via the .raw property.

Most developers interact with AssembledTransaction indirectly by calling methods on a Client instance, which returns an AssembledTransaction automatically.

Protocol 27 introduces AddressV2 and AddressWithDelegates. While the SDK is forward-compatible, you can opt-in to ADDRESS_V2 credentials by passing authV2: true to authorizeInvocation.

// Opt-in to AddressV2
const entry = await authorizeInvocation({
  signer,
  validUntilLedgerSeq,
  invocation,
  networkPassphrase,
  authV2: true,
})

// Read the V2 address
const addr = entry.credentials().addressV2()

A TradeRecord in the Horizon API represents a trading pair and can be one of two types:

1. Orderbook: A traditional order book for a trading pair.
2. LiquidityPool: A liquidity pool record used in Stellar's Automated Market Maker (AMM) functionality.

type TradeRecord = TradeRecord.Orderbook | TradeRecord.LiquidityPool

An invoke transaction involves two distinct types of signatures:

Note: If the account being authorized is the transaction source, the envelope signature already covers it, and no separate authorization signature is required.

The Horizon API uses specific response shapes for transaction-related operations:

• FeeBumpTransactionResponse: Returned when bumping a transaction fee. It contains the transaction hash and an array of signatures.
• InnerTransactionResponse: Used for inner transactions, containing the hash, max_fee, and signatures.

interface FeeBumpTransactionResponse {
  hash: string;
  signatures: string[];
}

interface InnerTransactionResponse {
  hash: string;
  max_fee: string;
  signatures: string[];
}

The Horizon.AccountResponse class provides detailed information and links for a single Stellar account. It includes balances (including trust lines), account flags, thresholds, and sequence numbers. It also implements the TransactionSource interface, meaning it can be passed directly to a TransactionBuilder to use its data as a source for new transactions.

Important: Do not instantiate this class directly using new AccountResponse(). Instead, use Horizon.Server#loadAccount to retrieve an instance.

// Correct way to get an AccountResponse
const account = await server.loadAccount(accountId);

// Use it in a transaction builder
const transaction = new TransactionBuilder(account, network)
  .addOperation(operation)
  .build();