Skip to content
@stellar/stellar-sdk

Core / Soroban Primitives

Address

class Address {
  constructor(address: string);
  static account(buffer: Uint8Array): Address;
  static claimableBalance(buffer: Uint8Array): Address;
  static contract(buffer: Uint8Array): Address;
  static fromScAddress(scAddress: ScAddress): Address;
  static fromScVal(scVal: ScVal): Address;
  static fromString(address: string): Address;
  static liquidityPool(buffer: Uint8Array): Address;
  static muxedAccount(buffer: Uint8Array): Address;
  readonly type: AddressType;
  toBuffer(): Uint8Array;
  toScAddress(): ScAddress;
  toScVal(): ScVal;
  toString(): string;
}

Source: src/base/address.ts:32

new Address(address)

constructor(address: string);

Parameters

  • address — string (required) — a StrKey of the address value

Source: src/base/address.ts:39

Address.account(buffer)

Creates a new account Address object from raw bytes.

static account(buffer: Uint8Array): Address;

Parameters

  • buffer — Uint8Array (required) — The bytes of an address to parse.

Source: src/base/address.ts:74

Address.claimableBalance(buffer)

Creates a new claimable balance Address object from raw bytes.

static claimableBalance(buffer: Uint8Array): Address;

Parameters

  • buffer — Uint8Array (required) — The bytes of a claimable balance ID to parse.

Source: src/base/address.ts:92

Address.contract(buffer)

Creates a new contract Address object from raw bytes.

static contract(buffer: Uint8Array): Address;

Parameters

  • buffer — Uint8Array (required) — The bytes of an address to parse.

Source: src/base/address.ts:83

Address.fromScAddress(scAddress)

Convert this from an xdr.ScAddress type

static fromScAddress(scAddress: ScAddress): Address;

Parameters

  • scAddress — ScAddress (required) — The xdr.ScAddress type to parse

Source: src/base/address.ts:131

Address.fromScVal(scVal)

Convert this from an xdr.ScVal type.

static fromScVal(scVal: ScVal): Address;

Parameters

  • scVal — ScVal (required) — The xdr.ScVal type to parse

Source: src/base/address.ts:119

Address.fromString(address)

Parses a string and returns an Address object.

static fromString(address: string): Address;

Parameters

  • address — string (required) — The address to parse. ex. GB3KJPLFUYN5VL6R3GU3EGCGVCKFDSD7BEDX42HWG5BWFKB3KQGJJRMA

Source: src/base/address.ts:65

Address.liquidityPool(buffer)

Creates a new liquidity pool Address object from raw bytes.

static liquidityPool(buffer: Uint8Array): Address;

Parameters

  • buffer — Uint8Array (required) — The bytes of an LP ID to parse.

Source: src/base/address.ts:101

Address.muxedAccount(buffer)

Creates a new muxed account Address object from raw bytes.

static muxedAccount(buffer: Uint8Array): Address;

Parameters

  • buffer — Uint8Array (required) — The bytes of an address to parse.

Source: src/base/address.ts:110

address.type

Return the type of this address.

readonly type: AddressType;

Source: src/base/address.ts:232

address.toBuffer()

Return the raw public key bytes for this address.

toBuffer(): Uint8Array;

Source: src/base/address.ts:225

address.toScAddress()

Convert this Address to an xdr.ScAddress type.

toScAddress(): ScAddress;

Source: src/base/address.ts:193

address.toScVal()

Convert this Address to an xdr.ScVal type.

toScVal(): ScVal;

Source: src/base/address.ts:186

address.toString()

Serialize an address to string.

toString(): string;

Source: src/base/address.ts:166

Contract

Create a new Contract object.

Contract represents a single contract in the Stellar network, embodying the interface of the contract. See Contracts for more information about how contracts work in Stellar.

class Contract {
  constructor(contractId: string);
  address(): Address;
  call(method: string, ...params: ScVal[]): Operation;
  contractId(): string;
  getFootprint(): LedgerKey;
  toString(): string;
}

Source: src/base/contract.ts:20

new Contract(contractId)

constructor(contractId: string);

Parameters

  • contractId — string (required) — ID of the contract (ex. CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE).

Source: src/base/contract.ts:27

contract.address()

Returns the wrapped address of this contract.

address(): Address;

Source: src/base/contract.ts:50

contract.call(method, params)

Returns an operation that will invoke this contract call.

call(method: string, ...params: ScVal[]): Operation;

Parameters

  • method — string (required) — name of the method to call
  • ...params — ScVal[] (required) — arguments to pass to the method, as an array of xdr.ScVal

See also

    • Operation.invokeHostFunction
  • Operation.invokeContractFunction
  • Operation.createCustomContract
  • Operation.createStellarAssetContract
  • Operation.uploadContractWasm

Source: src/base/contract.ts:66

contract.contractId()

Returns Stellar contract ID as a strkey, ex. CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE.

contractId(): string;

Source: src/base/contract.ts:40

contract.getFootprint()

Returns the read-only footprint entries necessary for any invocations to this contract, for convenience when manually adding it to your transaction’s overall footprint or doing bump/restore operations.

getFootprint(): LedgerKey;

Source: src/base/contract.ts:79

contract.toString()

Returns the ID as a strkey (C…).

toString(): string;

Source: src/base/contract.ts:45

Soroban

Helper class to assist with formatting and parsing token amounts.

class Soroban {
  constructor();
  static formatTokenAmount(amount: string, decimals: number): string;
  static parseTokenAmount(value: string, decimals: number): string;
}

Source: src/base/soroban.ts:2

new Soroban()

constructor();

Soroban.formatTokenAmount(amount, decimals)

Given a whole number smart contract amount of a token and an amount of decimal places (if the token has any), it returns a “display” value.

All arithmetic inside the contract is performed on integers to avoid potential precision and consistency issues of floating-point.

static formatTokenAmount(amount: string, decimals: number): string;

Parameters

  • amount — string (required) — the token amount you want to display
  • decimals — number (required) — specify how many decimal places a token has

Throws

  • a TypeError if the given amount has a decimal point already

Example

formatTokenAmount("123000", 4) === "12.3";
formatTokenAmount("123000", 3) === "123.0";
formatTokenAmount("123", 3) === "0.123";

Source: src/base/soroban.ts:21

Soroban.parseTokenAmount(value, decimals)

Parse a token amount to use it on smart contract

This function takes the display value and its decimals (if the token has any) and returns a string that’ll be used within the smart contract.

Returns the whole number token amount represented by the display value with the decimal places shifted over.

static parseTokenAmount(value: string, decimals: number): string;

Parameters

  • value — string (required) — the token amount you want to use on a smart contract which you’ve been displaying in a UI
  • decimals — number (required) — the number of decimal places expected in the display value (different than the “actual” number, because suffix zeroes might not be present)

Example

const displayValueAmount = "123.4560"
const parsedAmtForSmartContract = parseTokenAmount(displayValueAmount, 5);
parsedAmtForSmartContract === "12345600"

Source: src/base/soroban.ts:77

SorobanDataBuilder

Supports building xdr.SorobanTransactionData structures with various items set to specific values.

This is recommended for when you are building Operation.extendFootprintTtl / Operation.restoreFootprint operations and need to TransactionBuilder.setSorobanData to avoid (re)building the entire data structure from scratch.

class SorobanDataBuilder {
  constructor(sorobanData?: string | Uint8Array<ArrayBufferLike> | SorobanTransactionData);
  static fromXdr(data: string | Uint8Array<ArrayBufferLike>): SorobanTransactionData;
  static fromXDR(data: string | Uint8Array<ArrayBufferLike>): SorobanTransactionData;
  appendFootprint(readOnly: LedgerKey[], readWrite: LedgerKey[]): SorobanDataBuilder;
  build(): SorobanTransactionData;
  getFootprint(): LedgerFootprint;
  getReadOnly(): LedgerKey[];
  getReadWrite(): LedgerKey[];
  setFootprint(readOnly?: LedgerKey[] | null, readWrite?: LedgerKey[] | null): SorobanDataBuilder;
  setReadOnly(readOnly?: LedgerKey[]): SorobanDataBuilder;
  setReadWrite(readWrite?: LedgerKey[]): SorobanDataBuilder;
  setResourceFee(fee: IntLike): SorobanDataBuilder;
  setResources(cpuInstrs: number, diskReadBytes: number, writeBytes: number): SorobanDataBuilder;
}

Example

// You want to use an existing data blob but override specific parts.
const newData = new SorobanDataBuilder(existing)
  .setReadOnly(someLedgerKeys)
  .setResourceFee("1000")
  .build();


// You want an instance from scratch
const newData = new SorobanDataBuilder()
  .setFootprint([someLedgerKey], [])
  .setResourceFee("1000")
  .build();

Source: src/base/sorobandata_builder.ts:36

new SorobanDataBuilder(sorobanData)

constructor(sorobanData?: string | Uint8Array<ArrayBufferLike> | SorobanTransactionData);

Parameters

  • sorobanData — string | Uint8Array<ArrayBufferLike> | SorobanTransactionData (optional) — either a base64-encoded string that represents an xdr.SorobanTransactionData instance or an XDR instance itself (it will be copied); if omitted or “falsy” (e.g. an empty string), it starts with an empty instance

Source: src/base/sorobandata_builder.ts:45

SorobanDataBuilder.fromXdr(data)

Decodes and builds a xdr.SorobanTransactionData instance.

static fromXdr(data: string | Uint8Array<ArrayBufferLike>): SorobanTransactionData;

Parameters

  • data — string | Uint8Array<ArrayBufferLike> (required) — raw input to decode

Source: src/base/sorobandata_builder.ts:76

SorobanDataBuilder.fromXDR(data)

Deprecated. Use SorobanDataBuilder.fromXdr instead. Deprecated in version v17.0.0

static fromXDR(data: string | Uint8Array<ArrayBufferLike>): SorobanTransactionData;

Parameters

  • data — string | Uint8Array<ArrayBufferLike> (required)

Source: src/base/sorobandata_builder.ts:88

sorobanDataBuilder.appendFootprint(readOnly, readWrite)

Appends the given ledger keys to the existing storage access footprint.

appendFootprint(readOnly: LedgerKey[], readWrite: LedgerKey[]): SorobanDataBuilder;

Parameters

  • readOnly — LedgerKey[] (required) — read-only keys to add
  • readWrite — LedgerKey[] (required) — read-write keys to add

Source: src/base/sorobandata_builder.ts:147

sorobanDataBuilder.build()

Returns a copy of the final data structure.

build(): SorobanTransactionData;

Source: src/base/sorobandata_builder.ts:228

sorobanDataBuilder.getFootprint()

Returns the storage access pattern.

getFootprint(): LedgerFootprint;

Source: src/base/sorobandata_builder.ts:247

sorobanDataBuilder.getReadOnly()

Returns the read-only storage access pattern.

getReadOnly(): LedgerKey[];

Source: src/base/sorobandata_builder.ts:237

sorobanDataBuilder.getReadWrite()

Returns the read-write storage access pattern.

getReadWrite(): LedgerKey[];

Source: src/base/sorobandata_builder.ts:242

sorobanDataBuilder.setFootprint(readOnly, readWrite)

Sets the storage access footprint to be a certain set of ledger keys.

You can also set each field explicitly via SorobanDataBuilder.setReadOnly and SorobanDataBuilder.setReadWrite or add to the existing footprint via SorobanDataBuilder.appendFootprint.

Passing null|undefined to either parameter will IGNORE the existing values. If you want to clear them, pass [], instead.

setFootprint(readOnly?: LedgerKey[] | null, readWrite?: LedgerKey[] | null): SorobanDataBuilder;

Parameters

  • readOnly — LedgerKey[] | null (optional) — the set of ledger keys to set in the read-only portion of the transaction’s sorobanData, or null | undefined to keep the existing keys
  • readWrite — LedgerKey[] | null (optional) — the set of ledger keys to set in the read-write portion of the transaction’s sorobanData, or null | undefined to keep the existing keys

Source: src/base/sorobandata_builder.ts:171

sorobanDataBuilder.setReadOnly(readOnly)

Sets the read-only keys in the access footprint.

setReadOnly(readOnly?: LedgerKey[]): SorobanDataBuilder;

Parameters

  • readOnly — LedgerKey[] (optional) — read-only keys in the access footprint

Source: src/base/sorobandata_builder.ts:190

sorobanDataBuilder.setReadWrite(readWrite)

Sets the read-write keys in the access footprint.

setReadWrite(readWrite?: LedgerKey[]): SorobanDataBuilder;

Parameters

  • readWrite — LedgerKey[] (optional) — read-write keys in the access footprint

Source: src/base/sorobandata_builder.ts:210

sorobanDataBuilder.setResourceFee(fee)

Sets the resource fee portion of the Soroban data.

setResourceFee(fee: IntLike): SorobanDataBuilder;

Parameters

  • fee — IntLike (required) — the resource fee to set (int64)

Source: src/base/sorobandata_builder.ts:105

sorobanDataBuilder.setResources(cpuInstrs, diskReadBytes, writeBytes)

Sets up the resource metrics.

You should almost NEVER need this, as its often generated / provided to you by transaction simulation/preflight from a Soroban RPC server.

setResources(cpuInstrs: number, diskReadBytes: number, writeBytes: number): SorobanDataBuilder;

Parameters

  • cpuInstrs — number (required) — number of CPU instructions
  • diskReadBytes — number (required) — number of bytes being read from disk
  • writeBytes — number (required) — number of bytes being written to disk/memory

Source: src/base/sorobandata_builder.ts:124

authorizeEntry

Actually authorizes an existing authorization entry using the given credentials and expiration details, returning a signed copy.

This “fills out” the authorization entry with a signature, indicating to the Operation.invokeHostFunction its attached to that:

  • a particular identity (i.e. signing Keypair or other signer)
  • approving the execution of an invocation tree (i.e. a simulation-acquired xdr.SorobanAuthorizedInvocation or otherwise built)
  • on a particular network (uniquely identified by its passphrase, see Networks)
  • until a particular ledger sequence is reached.

This one lets you pass either a Keypair (or, more accurately, anything with a sign(Uint8Array): Uint8Array method) or a callback function (see SigningCallback) to handle signing the envelope hash.

authorizeEntry(entry: SorobanAuthorizationEntry, signer: Keypair | SigningCallback, validUntilLedgerSeq: number, networkPassphrase: string, forAddress?: string): Promise<SorobanAuthorizationEntry>

Parameters

  • entry — SorobanAuthorizationEntry (required) — an unsigned authorization entry

  • signer — Keypair | SigningCallback (required) — either a Keypair instance or a function (see SigningCallback) which receives the xdr.HashIdPreimage input payload plus its 32-byte signing hash and returns EITHER

     (a) an object containing a `signature` of the hash of the raw payload
         bytes as a `Uint8Array` and a `publicKey` string representing who just
         created this signature,
     (b) just the naked signature of the hash of the raw payload bytes (where
         the signing key is implied to be the address in the `entry`), or
     (c) an object containing a `signatureScVal` — an arbitrary, caller-built
         `xdr.ScVal` written verbatim as the credentials' signature,
         for custom account contracts (smart wallets, passkey/WebAuthn
         signers) whose `__check_auth` expects a non-Ed25519 signature shape.

    Option (b) is JUST for backwards compatibility and will be removed in the future.

  • validUntilLedgerSeq — number (required) — the (exclusive) future ledger sequence number until which this authorization entry should be valid (if currentLedgerSeq==validUntil, this is expired)

  • networkPassphrase — string (required) — the network passphrase is incorporated into the signature (see Networks for options)

    If using the SigningCallback variation, the signer is assumed to be the entry’s credential address unless you use the variant that returns the object.

  • forAddress — string (optional) — which credential node the signature should be written to. Only relevant for SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES, where a single entry can be signed by the top-level account and/or any of its (possibly nested) delegates. Per CAP-71-01 every one of these signers signs the same payload (bound to the top-level address), so the signature produced here is written to whichever node(s) carry forAddress. When omitted, the signature is written to the top-level credentials, which preserves the behavior for SOROBAN_CREDENTIALS_ADDRESS / SOROBAN_CREDENTIALS_ADDRESS_V2 and for accounts whose signing key differs from the credential address (e.g. multisig).

Example

import {
  rpc,
  Operation,
  Transaction,
  Networks,
  authorizeEntry
} from '@stellar/stellar-sdk';


// Assume signPayloadCallback is a well-formed signing callback.
//
// It might, for example, pop up a modal from a browser extension, send the
// transaction to a third-party service for signing, or just do simple
// signing via Keypair like it does here:
async function signPayloadCallback(preimage, payload) {
   // `payload` is hash(preimage.toXdr()) — inspect `preimage` if you want
   // to display/verify what is being authorized before signing.
   return signer.sign(payload);
}


async function multiPartyAuth(
   server: rpc.Server,
   // assume this involves multi-party auth
   tx: Transaction,
) {
   const sim = await server.simulateTransaction(tx);
   if (!rpc.Api.isSimulationSuccess(sim)) {
     throw new Error('simulation failed');
   }


   const invoke = tx.operations[0];
   if (invoke.type !== 'invokeHostFunction') {
     throw new Error('expected an invokeHostFunction operation');
   }


   // Simulation supplies the entries to authorize. `authorizeEntry` returns
   // a signed *copy*, so collect the results rather than discarding them.
   const auth = await Promise.all(
     (sim.result?.auth ?? []).map((entry) =>
       authorizeEntry(
         entry,
         signPayloadCallback,
         currentLedger + 1000,
         Networks.TESTNET,
       ),
     ),
   );


   // Replace the operation rather than mutating it: a built `Transaction`'s
   // operations must not be changed. `assembleTransaction` applies the
   // resources and fee from simulation, and keeps auth that is already
   // present. Call `build()` once — each call consumes a sequence number.
   const built = rpc.assembleTransaction(tx, sim)
     .clearOperations()
     .addOperation(Operation.invokeHostFunction({
       source: invoke.source,
       func: invoke.func,
       auth,
     }))
     .build();


   built.sign(source);
   return server.sendTransaction(built);
}

See also

  • authorizeInvocation

Source: src/base/auth.ts:220

authorizeInvocation

authorizeInvocation(params: AuthorizeInvocationParams): Promise<SorobanAuthorizationEntry>

Parameters

  • params — AuthorizeInvocationParams (required)

Source: src/base/auth.ts:433

buildAuthorizationEntryPreimage

Builds the xdr.HashIdPreimage whose hash a signer must sign to authorize entry. This is the low-level signature payload used by authorizeEntry, exposed for callers that drive signing themselves — most notably for SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES, where the client (not simulation) decides which delegates sign and how.

For SOROBAN_CREDENTIALS_ADDRESS this is the legacy, non-address-bound ENVELOPE_TYPE_SOROBAN_AUTHORIZATION preimage. For SOROBAN_CREDENTIALS_ADDRESS_V2 and SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES it is the address-bound ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS preimage (CAP-71). For the delegates variant this single payload — bound to the top-level address — is what the top-level account and every (nested) delegate each sign.

To get the raw bytes to sign, hash the XDR: hash(preimage.toXdr()).

buildAuthorizationEntryPreimage(entry: SorobanAuthorizationEntry, validUntilLedgerSeq: number, networkPassphrase: string): HashIdPreimage

Parameters

  • entry — SorobanAuthorizationEntry (required) — the authorization entry to build the payload for
  • validUntilLedgerSeq — number (required) — the expiration ledger committed into the payload (must match the signatureExpirationLedger on the credentials you submit)
  • networkPassphrase — string (required) — the network passphrase mixed into the payload

Throws

  • Error if entry carries source-account or otherwise non-address credentials

Source: src/base/auth.ts:499

buildInvocationTree

Turns a raw invocation tree into a human-readable format.

This is designed to make the invocation tree easier to understand in order to inform users about the side-effects of their contract calls. This will help make informed decisions about whether or not a particular invocation will result in what you expect it to.

buildInvocationTree(root: SorobanAuthorizedInvocation): InvocationTree

Parameters

  • root — SorobanAuthorizedInvocation (required) — the raw XDR of the invocation, likely acquired from transaction simulation. this is either from the Operation.invokeHostFunction itself (the func field), or from the authorization entries (xdr.SorobanAuthorizationEntry, the rootInvocation field)

Example

Here, we show a browser modal after simulating an arbitrary transaction, tx, which we assume has an Operation.invokeHostFunction inside of it:

import { rpc, buildInvocationTree } from '@stellar/stellar-sdk';


const s = new rpc.Server("fill in accordingly");


s.simulateTransaction(tx).then(
 (resp: rpc.Api.SimulateTransactionResponse) => {
   if (rpc.Api.isSimulationSuccess(resp) && resp.result) {
     // bold assumption: there's a valid result with an auth entry
     const auth = resp.result.auth;
     if (auth && auth.length > 0) {
       alert(
         "You are authorizing the following invocation:\n" +
         // args decode via `scValToNative`, so wide ints arrive as `bigint`,
         // which plain JSON.stringify throws on — hence the replacer.
         JSON.stringify(
           buildInvocationTree(auth[0].rootInvocation),
           (_key, value) =>
             typeof value === 'bigint' ? value.toString() : value,
           2
         )
       );
     }
   }
 }
);

Source: src/base/invocation.ts:154

buildWithDelegatesEntry

Builds a SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES authorization entry by wrapping the address credentials of an existing ADDRESS/ADDRESS_V2 entry (e.g. one returned by simulation) together with a caller-provided set of delegate signers.

Simulation never emits the delegates variant on its own — which accounts use delegated authentication is account-specific policy known only to the client (much like a multisig policy). This helper just assembles the wrapper XDR; you supply the delegate tree (addresses and, optionally, signatures). To produce the signatures, build the shared payload with buildAuthorizationEntryPreimage on the returned entry and sign it, or fill each node afterwards with authorizeEntry (passing the signer’s address as forAddress).

Each delegates array (the top-level set and every nestedDelegates) is sorted by address in ascending order, and duplicate addresses within an array are rejected, as the protocol requires (CAP-71-01) — otherwise the host rejects the entry.

buildWithDelegatesEntry(params: BuildWithDelegatesParams): SorobanAuthorizationEntry

Parameters

Throws

  • Error if entry is not an ADDRESS/ADDRESS_V2 entry, or if any delegates array contains a duplicate address.

Source: src/base/auth.ts:606

checkAuthEntryReadiness

Reports whether an authorization entry is ready to submit at a given ledger: fully signed and not yet expired.

Source-account entries are always ready — they carry no signature or expiration of their own and are instead covered by the transaction envelope signature.

The current ledger sequence is taken as a parameter (fetch it from a source you trust, e.g. rpc.Server.getLatestLedger) rather than looked up here, so this stays a pure decode with no network dependency.

For SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES, this conservatively requires every node (top-level and all delegates) to be signed. An account’s policy may accept an unsigned top-level node when its delegates have signed (CAP-71-01); if you support that, check inspectAuthEntry’s signers yourself.

checkAuthEntryReadiness(entry: SorobanAuthorizationEntry, currentLedgerSeq: number): AuthEntryReadiness

Parameters

  • entry — SorobanAuthorizationEntry (required) — the authorization entry to check
  • currentLedgerSeq — number (required) — the network’s current ledger sequence, compared (exclusively) against the entry’s signatureExpirationLedger

Returns

a AuthEntryReadiness: ready, expired, and which addresses are still unsignedBy

Throws

  • Error if currentLedgerSeq cannot represent a uint32 ledger sequence (non-integer, negative, or above 2^32 - 1), which would make the expiration comparison unreliable

Source: src/base/auth.ts:1058

humanizeEvents

Converts raw diagnostic or contract events into something with a flatter, human-readable, and understandable structure.

Each element in the returned list has the following properties:

  • type: one of 'system', 'contract', 'diagnostic'
  • contractId: optionally, a C... encoded strkey
  • topics: a list of scValToNative invocations on the topics
  • data: a scValToNative invocation on the raw event data
humanizeEvents(events: ContractEvent[] | DiagnosticEvent[]): SorobanEvent[]

Parameters

  • events — ContractEvent[] | DiagnosticEvent[] (required) — either contract events or diagnostic events to parse into a friendly format

Source: src/base/events.ts:44

inspectAuthEntry

Decodes a xdr.SorobanAuthorizationEntry into a plain, typed summary: which credential variant it uses, which address authorizes it, its nonce and expiration ledger, and — for every node that can carry a signature (the top-level credentials plus any CAP-71 delegates) — whether it is signed and, when the payload uses the SDK’s standard ed25519 format, by which keys.

This is the read-side complement to authorizeEntry / authorizeInvocation: those fill entries with signatures, this inspects what an entry (e.g. one returned by transaction simulation, or received from a counterparty in a multi-party signing flow) requires and already carries, without reaching into raw XDR accessors.

inspectAuthEntry(entry: SorobanAuthorizationEntry): AuthEntryInfo

Parameters

  • entry — SorobanAuthorizationEntry (required) — the authorization entry to inspect

Returns

a AuthEntryInfo summary of the entry

Example

const info = inspectAuthEntry(entry);
if (!info.signed && info.address !== null) {
  console.log(`${info.address} still needs to sign`, info.signers);
}

See also

  • checkAuthEntryReadiness

Source: src/base/auth.ts:938

nativeToScVal

Attempts to convert native types into smart contract values (xdr.ScVal).

Provides conversions from smart contract XDR values (xdr.ScVal) to native JavaScript types.

The conversions are as follows:

  • xdr.ScVal → passthrough

  • null/undefined → scvVoid

  • string → scvString (a copy is made)

  • Uint8Array → scvBytes (a copy is made)

  • boolean → scvBool

  • number/bigint → the smallest possible XDR integer type that will fit the input value (if you want a specific type, use ScInt)

  • Address or Contract → scvAddress (for contracts and public keys)

  • Array<T> → scvVec after attempting to convert each item of type T to an xdr.ScVal (recursively). note that all values must be the same type!

  • object → scvMap after attempting to convert each key and value to an xdr.ScVal (recursively). note that there is no restriction on types matching anywhere (unlike arrays)

When passing an integer-like native value, you can also optionally specify a type which will force a particular interpretation of that value.

Note that not all type specifications are compatible with all ScVals, e.g. toScVal("a string", {type: "i256"}) will throw.

nativeToScVal(val: unknown, opts: NativeToScValOpts = {}): ScVal

Parameters

  • val — unknown (required) — a native (or convertible) input value to wrap

  • opts — NativeToScValOpts (optional) (default: {}) — an optional set of hints around the type of conversion you’d like to see

    • type: there is different behavior for different input types for val:

      • when val is an integer-like type (i.e. number|bigint), this will be forwarded to ScInt or forced to be u32/i32.

      • when val is an array type, this is forwarded to the recursion

      • when val is an object type (key-value entries), this should be an object in which each key has a pair of types (to represent forced types for the key and the value), where null (or a missing entry) indicates the default interpretation(s) (refer to the examples, below)

      • when val is a Map, this can be a [keyType, valType] pair applied to every entry, or (when all keys are strings) the same per-key spec object used for plain objects

      • when val is a string type, this can be ‘string’ or ‘symbol’ to force a particular interpretation of val.

      • when val is a bytes-like type, this can be ‘string’, ‘symbol’, or ‘bytes’ to force a particular interpretation

    As a simple example, nativeToScVal("hello", {type: 'symbol'}) will return an scvSymbol, whereas without the type it would have been an scvString.

Throws

  • a TypeError if…
  • there are arrays with more than one type in them
  • there are values that do not have a sensible conversion (e.g. random XDR types, custom classes)
  • the type of the input object (or some inner value of said object) cannot be determined (via typeof)
  • the type you specified (via opts.type) is incompatible with the value you passed in (val), e.g. nativeToScVal("a string", { type: 'i128' }), though this does not apply for types that ignore opts (e.g. addresses).

Example

nativeToScVal(1000);                   // gives ScValType === scvU64
nativeToScVal(1000n);                  // gives ScValType === scvU64
nativeToScVal(1n << 100n);             // gives ScValType === scvU128
nativeToScVal(1000, { type: 'u32' });  // gives ScValType === scvU32
nativeToScVal(1000, { type: 'i256' }); // gives ScValType === scvI256
nativeToScVal("a string");                     // gives ScValType === scvString
nativeToScVal("a string", { type: 'symbol' }); // gives scvSymbol
nativeToScVal(new Uint8Array(5));                      // scvBytes
nativeToScVal(new Uint8Array(5), { type: 'symbol' });  // scvSymbol
nativeToScVal(null); // scvVoid
nativeToScVal(true); // scvBool
nativeToScVal([1, 2, 3]);                    // gives scvVec with each element as scvU64
nativeToScVal([1, 2, 3], { type: 'i128' });  // scvVec<scvI128>
nativeToScVal([1, '2'], { type: ['i128', 'symbol'] });  // scvVec with diff types
nativeToScVal([1, '2', 3], { type: ['i128', 'symbol'] });
   // scvVec with diff types, using the default when omitted
nativeToScVal({ 'hello': 1, 'world': [ true, false ] }, {
  type: {
    'hello': [ 'symbol', 'i128' ],
  }
})
// gives scvMap with entries: [
//     [ scvSymbol, scvI128 ],
//     [ scvString, scvArray<scvBool> ]
// ]

Example

import {
  nativeToScVal,
  scValToNative,
  ScInt,
  xdr
} from '@stellar/stellar-sdk';


let gigaMap = {
  bool: true,
  void: null,
  u32: xdr.ScVal.scvU32(1),
  i32: xdr.ScVal.scvI32(1),
  u64: 1n,
  i64: -1n,
  u128: new ScInt(1).toU128(),
  i128: new ScInt(1).toI128(),
  u256: new ScInt(1).toU256(),
  i256: new ScInt(1).toI256(),
  map: {
    arbitrary: 1n,
    nested: 'values',
    etc: false
  },
  vec: ['same', 'type', 'list'],
  vec: ['diff', 1, 'type', 2, 'list'],
};


// then, simply:
let scv = nativeToScVal(gigaMap);    // scv.type === "scvMap"


// then...
someContract.call("method", scv);


// Similarly, the inverse should work:
scValToNative(scv) == gigaMap;       // true

See also

  • scValToNative

Source: src/base/scval.ts:172

scValToNative

Given a smart contract value, attempt to convert it to a native type. Possible conversions include:

  • void → null
  • u32, i32 → number
  • u64, i64, u128, i128, u256, i256, timepoint, duration → bigint
  • vec → Array of any of the above (via recursion)
  • map → key-value object of any of the above (via recursion)
  • bool → boolean
  • bytes → Uint8Array
  • symbol → string
  • string → string IF the underlying buffer can be decoded as ascii/utf8, Uint8Array of the raw contents in any error case

If no viable conversion can be determined, this just “unwraps” the smart value to return its underlying XDR value.

scValToNative(scv: ScVal): any

Parameters

  • scv — ScVal (required) — the input smart contract value

See also

  • nativeToScVal

Source: src/base/scval.ts:431

scvSortedMap

Build a sorted ScVal map from unsorted entries, sorted by key.

scvSortedMap(items: ScMapEntry[]): ScVal

Parameters

  • items — ScMapEntry[] (required) — the unsorted map entries

Source: src/base/scval.ts:530

walkInvocationTree

Executes a callback function on each node in the tree until stopped.

Nodes are walked in a depth-first order. Returning false from the callback stops further depth exploration at that node, but it does not stop the walk in a “global” view.

walkInvocationTree(root: SorobanAuthorizedInvocation, callback: InvocationWalker): void

Parameters

  • root — SorobanAuthorizedInvocation (required) — the tree to explore
  • callback — InvocationWalker (required) — the callback to execute for each node

Source: src/base/invocation.ts:261

Types

AuthEntryCredentialType

The credential arm of a xdr.SorobanAuthorizationEntry.

type AuthEntryCredentialType = "sourceAccount" | "address" | "addressV2" | "addressWithDelegates"

Source: src/base/auth.ts:821

AuthEntryInfo

A structured, read-only view of a xdr.SorobanAuthorizationEntry, returned by inspectAuthEntry.

interface AuthEntryInfo {
  address: string | null;
  credentialType: AuthEntryCredentialType;
  invocation: SorobanAuthorizedInvocation;
  nonce: bigint | null;
  signatureExpirationLedger: number | null;
  signed: boolean;
  signers: AuthEntrySigner[];
}

Source: src/base/auth.ts:868

authEntryInfo.address

the authorizing address, or null for source-account credentials.

address: string | null;

Source: src/base/auth.ts:871

authEntryInfo.credentialType

credentialType: AuthEntryCredentialType;

Source: src/base/auth.ts:869

authEntryInfo.invocation

the invocation tree this entry authorizes.

invocation: SorobanAuthorizedInvocation;

Source: src/base/auth.ts:897

authEntryInfo.nonce

the credential nonce, or null for source-account credentials.

nonce: bigint | null;

Source: src/base/auth.ts:873

authEntryInfo.signatureExpirationLedger

the (exclusive) ledger sequence until which the signature is valid, or null for source-account credentials. Note that unsigned entries commonly carry a placeholder (often 0) until authorizeEntry sets it.

signatureExpirationLedger: number | null;

Source: src/base/auth.ts:879

authEntryInfo.signed

whether every signer node carries a signature payload. Always false for source-account credentials (which have no signature nodes — they are instead covered by the transaction envelope signature; use checkAuthEntryReadiness for a submit check). For the delegates variant note that an account’s policy may accept an unsigned top-level node when its delegates have signed (CAP-71-01) — consult signers if you support that.

signed: boolean;

Source: src/base/auth.ts:895

authEntryInfo.signers

every node that can carry a signature: the top-level credentials first, then (for the delegates variant) each delegate, depth-first. Empty for source-account credentials.

signers: AuthEntrySigner[];

Source: src/base/auth.ts:885

AuthEntryReadiness

The result of checkAuthEntryReadiness.

interface AuthEntryReadiness {
  expired: boolean;
  ready: boolean;
  unsignedBy: string[];
}

Source: src/base/auth.ts:901

authEntryReadiness.expired

true when currentLedgerSeq >= signatureExpirationLedger (expiration is exclusive). Always false for source-account credentials.

expired: boolean;

Source: src/base/auth.ts:908

authEntryReadiness.ready

true when the entry is fully signed and not expired.

ready: boolean;

Source: src/base/auth.ts:903

authEntryReadiness.unsignedBy

addresses of signer nodes that carry no signature payload.

unsignedBy: string[];

Source: src/base/auth.ts:910

AuthEntrySignature

A single ed25519 signature parsed out of a credential node’s signature value, in the map format written by authorizeEntry.

interface AuthEntrySignature {
  publicKey: string;
  signature: Uint8Array;
}

Source: src/base/auth.ts:828

authEntrySignature.publicKey

the signer’s public key, as a G… strkey.

publicKey: string;

Source: src/base/auth.ts:830

authEntrySignature.signature

the raw 64-byte ed25519 signature.

signature: Uint8Array;

Source: src/base/auth.ts:832

AuthEntrySigner

One node of an authorization entry that can carry a signature: the top-level address credentials and, for SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES, each (possibly nested) delegate.

interface AuthEntrySigner {
  address: string;
  rawSignature: ScVal;
  signatures: AuthEntrySignature[] | null;
  signed: boolean;
}

Source: src/base/auth.ts:840

authEntrySigner.address

the node’s address (G… account or C… contract).

address: string;

Source: src/base/auth.ts:842

authEntrySigner.rawSignature

the raw signature value, whatever its shape.

rawSignature: ScVal;

Source: src/base/auth.ts:861

authEntrySigner.signatures

the signature payload parsed as the SDK’s standard ed25519 format (a vec of {public_key, signature} maps, see authorizeEntry), or null when the payload has some other, signer-defined shape (as custom accounts such as WebAuthn/passkey wallets use). Of the two unsigned placeholder forms, an empty scvVec parses as [] while scvVoid (not a vec at all) parses as null — check signed rather than this field to tell whether a node is unsigned.

signatures: AuthEntrySignature[] | null;

Source: src/base/auth.ts:859

authEntrySigner.signed

whether a signature payload is present on this node (i.e. its signature is neither scvVoid nor an empty scvVec). For contract (C…) addresses this only means something is attached — whether it satisfies the contract’s __check_auth cannot be verified client-side.

signed: boolean;

Source: src/base/auth.ts:849

AuthorizeInvocationParams

This builds an entry from scratch, allowing you to express authorization as a function of:

  • a particular identity (i.e. signing Keypair or other signer)
  • approving the execution of an invocation tree (i.e. a simulation-acquired xdr.SorobanAuthorizedInvocation or otherwise built)
  • on a particular network (uniquely identified by its passphrase, see Networks)
  • until a particular ledger sequence is reached.

This is in contrast to authorizeEntry, which signs an existing entry.

interface AuthorizeInvocationParams {
  authV2?: boolean;
  invocation: SorobanAuthorizedInvocation;
  networkPassphrase: string;
  publicKey?: string;
  signer: Keypair | SigningCallback;
  validUntilLedgerSeq: number;
}

See also

  • authorizeEntry

Source: src/base/auth.ts:418

authorizeInvocationParams.authV2

Build SOROBAN_CREDENTIALS_ADDRESS_V2 (CAP-71) credentials instead of the legacy SOROBAN_CREDENTIALS_ADDRESS. V2 credentials bind the address into the signed payload.

authV2?: boolean;

Source: src/base/auth.ts:430

authorizeInvocationParams.invocation

invocation: SorobanAuthorizedInvocation;

Source: src/base/auth.ts:421

authorizeInvocationParams.networkPassphrase

networkPassphrase: string;

Source: src/base/auth.ts:422

authorizeInvocationParams.publicKey

publicKey?: string;

Source: src/base/auth.ts:423

authorizeInvocationParams.signer

signer: Keypair | SigningCallback;

Source: src/base/auth.ts:419

authorizeInvocationParams.validUntilLedgerSeq

validUntilLedgerSeq: number;

Source: src/base/auth.ts:420

BuildWithDelegatesParams

Parameters for buildWithDelegatesEntry.

interface BuildWithDelegatesParams {
  delegates: DelegateSignature[];
  entry: SorobanAuthorizationEntry;
  signature?: ScVal;
  validUntilLedgerSeq: number;
}

Source: src/base/auth.ts:564

buildWithDelegatesParams.delegates

the delegate signers to attach.

delegates: DelegateSignature[];

Source: src/base/auth.ts:574

buildWithDelegatesParams.entry

an existing SOROBAN_CREDENTIALS_ADDRESS or SOROBAN_CREDENTIALS_ADDRESS_V2 entry — typically one returned by simulation — whose address credentials should be wrapped.

entry: SorobanAuthorizationEntry;

Source: src/base/auth.ts:570

buildWithDelegatesParams.signature

the top-level account’s signature. Defaults to scvVoid, which is valid for accounts that authorize purely via delegated signers (CAP-71-01).

signature?: ScVal;

Source: src/base/auth.ts:579

buildWithDelegatesParams.validUntilLedgerSeq

the expiration ledger sequence stored on the top-level credentials.

validUntilLedgerSeq: number;

Source: src/base/auth.ts:572

CreateInvocation

Details about a contract creation invocation.

  • type indicates if this creation was a custom contract ('wasm'), a wrapping of an existing Stellar asset ('sac'), or a reference to an external executable ('external', see CAP-85)
  • asset is set when type=='sac', containing the canonical Asset being wrapped by this Stellar Asset Contract
  • wasm is set when type=='wasm', containing additional creation parameters
  • external is set when type=='external', containing the referenced executable and the creation parameters
interface CreateInvocation {
  asset?: string;
  external?: ExternalRefCreateDetails;
  type: "wasm" | "sac" | "external";
  wasm?: WasmCreateDetails;
}

Source: src/base/invocation.ts:53

createInvocation.asset

asset?: string;

Source: src/base/invocation.ts:55

createInvocation.external

external?: ExternalRefCreateDetails;

Source: src/base/invocation.ts:57

createInvocation.type

type: "wasm" | "sac" | "external";

Source: src/base/invocation.ts:54

createInvocation.wasm

wasm?: WasmCreateDetails;

Source: src/base/invocation.ts:56

DelegateSignature

A delegate signer to attach to a SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES entry via buildWithDelegatesEntry.

interface DelegateSignature {
  address: string;
  nestedDelegates?: DelegateSignature[];
  signature?: ScVal;
}

Source: src/base/auth.ts:550

delegateSignature.address

the delegate’s address (G… account or C… contract).

address: string;

Source: src/base/auth.ts:552

delegateSignature.nestedDelegates

signers this delegate in turn delegates to (recursive).

nestedDelegates?: DelegateSignature[];

Source: src/base/auth.ts:560

delegateSignature.signature

the delegate’s signature value. Defaults to a scvVoid placeholder, which you can fill afterwards with authorizeEntry (passing this address as forAddress) or by editing the entry directly.

signature?: ScVal;

Source: src/base/auth.ts:558

ExecuteInvocation

Details about a contract function execution invocation.

  • source is the strkey of the contract (C...) being invoked
  • function is the name of the function being invoked
  • args are the natively-represented parameters to the function invocation (see scValToNative for rules on how they’re represented as JS types)
interface ExecuteInvocation {
  args: any[];
  function: string;
  source: string;
}

Source: src/base/invocation.ts:68

executeInvocation.args

args: any[];

Source: src/base/invocation.ts:72

executeInvocation.function

function: string;

Source: src/base/invocation.ts:70

executeInvocation.source

source: string;

Source: src/base/invocation.ts:69

ExternalRefCreateDetails

Details about a contract creation from an external executable (CAP-85).

  • owner is the strkey of the account or contract that owns the external executable being referenced
  • tag is the owner-scoped name of that executable. It is an unbounded SCString, so it is not always text: a lenient UTF-8 decode would render two distinct tags identically, and the tag is half of what identifies the code being deployed. Binary tags come back as raw bytes, matching scValToNative
  • address is the strkey of the deployer and salt its hex-encoded salt, which together derive the new contract’s ID
interface ExternalRefCreateDetails {
  address: string;
  constructorArgs?: any[];
  owner: string;
  salt: string;
  tag: string | Uint8Array<ArrayBufferLike>;
}

Source: src/base/invocation.ts:32

externalRefCreateDetails.address

address: string;

Source: src/base/invocation.ts:35

externalRefCreateDetails.constructorArgs

constructorArgs?: any[];

Source: src/base/invocation.ts:38

externalRefCreateDetails.owner

owner: string;

Source: src/base/invocation.ts:33

externalRefCreateDetails.salt

salt: string;

Source: src/base/invocation.ts:36

externalRefCreateDetails.tag

tag: string | Uint8Array<ArrayBufferLike>;

Source: src/base/invocation.ts:34

IntLike

type IntLike = bigint | number | string

Source: src/base/sorobandata_builder.ts:10

InvocationTree

A node in the invocation tree.

  • type is the type of invocation occurring, either contract creation or host function execution
  • args are the parameters to the invocation, depending on the type
  • invocations are any sub-invocations that may occur as a result of this invocation (i.e. a tree of call stacks)
interface InvocationTree {
  args: CreateInvocation | ExecuteInvocation;
  invocations: InvocationTree[];
  type: "create" | "execute";
}

Source: src/base/invocation.ts:84

invocationTree.args

args: CreateInvocation | ExecuteInvocation;

Source: src/base/invocation.ts:86

invocationTree.invocations

invocations: InvocationTree[];

Source: src/base/invocation.ts:87

invocationTree.type

type: "create" | "execute";

Source: src/base/invocation.ts:85

InvocationWalker

A callback used when walking an invocation tree.

Returning exactly false is a hint to stop exploring deeper from this node; other return values are ignored.

type InvocationWalker = (node: SorobanAuthorizedInvocation, depth: number, parent?: SorobanAuthorizedInvocation) => boolean | null | void

Source: src/base/invocation.ts:102

NativeToScValOpts

interface NativeToScValOpts {
  type?: ScValType | ScValMapTypeSpec | ScValType | null[];
}

Source: src/base/scval.ts:25

nativeToScValOpts.type

type?: ScValType | ScValMapTypeSpec | ScValType | null[];

Source: src/base/scval.ts:26

SigningCallback

A callback for signing an XDR structure representing all of the details necessary to authorize an invocation tree.

type SigningCallback = (preimage: HashIdPreimage, payload: Uint8Array) => Promise<Uint8Array | { publicKey: string; signature: Uint8Array } | { address?: string; signatureScVal: ScVal }>

Source: src/base/auth.ts:60

WasmCreateDetails

interface WasmCreateDetails {
  address: string;
  constructorArgs?: any[];
  hash: string;
  salt: string;
}

Source: src/base/invocation.ts:11

wasmCreateDetails.address

address: string;

Source: src/base/invocation.ts:13

wasmCreateDetails.constructorArgs

constructorArgs?: any[];

Source: src/base/invocation.ts:16

wasmCreateDetails.hash

hash: string;

Source: src/base/invocation.ts:12

wasmCreateDetails.salt

salt: string;

Source: src/base/invocation.ts:14