Core / Soroban Primitives

Address

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

Source: src/base/address.ts:20

`new Address(address)`

constructor(address: string);

Parameters

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

Source: src/base/address.ts:27

`Address.account(buffer)`

Creates a new account Address object from a buffer of raw bytes.

static account(buffer: Buffer): Address;

Parameters

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

Source: src/base/address.ts:62

`Address.claimableBalance(buffer)`

Creates a new claimable balance Address object from a buffer of raw bytes.

static claimableBalance(buffer: Buffer): Address;

Parameters

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

Source: src/base/address.ts:80

`Address.contract(buffer)`

Creates a new contract Address object from a buffer of raw bytes.

static contract(buffer: Buffer): Address;

Parameters

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

Source: src/base/address.ts:71

`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:116

`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:107

`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:53

`Address.liquidityPool(buffer)`

Creates a new liquidity pool Address object from a buffer of raw bytes.

static liquidityPool(buffer: Buffer): Address;

Parameters

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

Source: src/base/address.ts:89

`Address.muxedAccount(buffer)`

Creates a new muxed account Address object from a buffer of raw bytes.

static muxedAccount(buffer: Buffer): Address;

Parameters

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

Source: src/base/address.ts:98

`address.type`

Return the type of this address.

readonly type: AddressType;

Source: src/base/address.ts:219

`address.toBuffer()`

Return the raw public key bytes for this address.

toBuffer(): Buffer;

Source: src/base/address.ts:212

`address.toScAddress()`

Convert this Address to an xdr.ScAddress type.

toScAddress(): ScAddress;

Source: src/base/address.ts:174

`address.toScVal()`

Convert this Address to an xdr.ScVal type.

toScVal(): ScVal;

Source: src/base/address.ts:167

`address.toString()`

Serialize an address to string.

toString(): string;

Source: src/base/address.ts:147

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 {
  invocation: SorobanAuthorizedInvocation;
  networkPassphrase: string;
  publicKey?: string;
  signer: Keypair | SigningCallback;
  validUntilLedgerSeq: number;
}

See also

authorizeEntry

Source: src/base/auth.ts:231

`authorizeInvocationParams.invocation`

invocation: SorobanAuthorizedInvocation;

Source: src/base/auth.ts:234

`authorizeInvocationParams.networkPassphrase`

networkPassphrase: string;

Source: src/base/auth.ts:235

`authorizeInvocationParams.publicKey`

publicKey?: string;

Source: src/base/auth.ts:236

`authorizeInvocationParams.signer`

signer: Keypair | SigningCallback;

Source: src/base/auth.ts:232

`authorizeInvocationParams.validUntilLedgerSeq`

validUntilLedgerSeq: number;

Source: src/base/auth.ts:233

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[]): Operation2<InvokeHostFunctionResult>;
  contractId(): string;
  getFootprint(): LedgerKey;
  toString(): string;
}

Source: src/base/contract.ts:14

`new Contract(contractId)`

constructor(contractId: string);

Parameters

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

Source: src/base/contract.ts:21

`contract.address()`

Returns the wrapped address of this contract.

address(): Address;

Source: src/base/contract.ts:44

`contract.call(method, params)`

Returns an operation that will invoke this contract call.

call(method: string, ...params: ScVal[]): Operation2<InvokeHostFunctionResult>;

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:60

`contract.contractId()`

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

contractId(): string;

Source: src/base/contract.ts:34

`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:76

`contract.toString()`

Returns the ID as a strkey (C…).

toString(): string;

Source: src/base/contract.ts:39

CreateInvocation

Details about a contract creation invocation.

type indicates if this creation was a custom contract ('wasm') or a wrapping of an existing Stellar asset ('sac')
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

interface CreateInvocation {
  asset?: string;
  type: "sac" | "wasm";
  wasm?: WasmCreateDetails;
}

Source: src/base/invocation.ts:23

`createInvocation.asset`

asset?: string;

Source: src/base/invocation.ts:25

`createInvocation.type`

type: "sac" | "wasm";

Source: src/base/invocation.ts:24

`createInvocation.wasm`

wasm?: WasmCreateDetails;

Source: src/base/invocation.ts:26

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:37

`executeInvocation.args`

args: any[];

Source: src/base/invocation.ts:41

`executeInvocation.function`

function: string;

Source: src/base/invocation.ts:39

`executeInvocation.source`

source: string;

Source: src/base/invocation.ts:38

IntLike

type IntLike = bigint | number | string

Source: src/base/sorobandata_builder.ts:3

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:53

`invocationTree.args`

args: CreateInvocation | ExecuteInvocation;

Source: src/base/invocation.ts:55

`invocationTree.invocations`

invocations: InvocationTree[];

Source: src/base/invocation.ts:56

`invocationTree.type`

type: "create" | "execute";

Source: src/base/invocation.ts:54

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: xdr.SorobanAuthorizedInvocation, depth: number, parent?: xdr.SorobanAuthorizedInvocation) => boolean | null | void

Source: src/base/invocation.ts:71

NativeToScValOpts

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

Source: src/base/scval.ts:18

`nativeToScValOpts.type`

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

Source: src/base/scval.ts:19

SigningCallback

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

type SigningCallback = (preimage: xdr.HashIdPreimage) => Promise<BufferLike | { publicKey: string; signature: BufferLike }>

Source: src/base/auth.ts:35

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

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:72

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> | Buffer<ArrayBufferLike> | SorobanTransactionData);
  static fromXDR(data: string | Uint8Array<ArrayBufferLike> | Buffer<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:29

`new SorobanDataBuilder(sorobanData)`

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

Parameters

sorobanData — string | Uint8Array<ArrayBufferLike> | Buffer<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:38

`SorobanDataBuilder.fromXDR(data)`

Decodes and builds a xdr.SorobanTransactionData instance.

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

Parameters

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

Source: src/base/sorobandata_builder.ts:71

`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:119

`sorobanDataBuilder.build()`

Returns a copy of the final data structure.

build(): SorobanTransactionData;

Source: src/base/sorobandata_builder.ts:186

`sorobanDataBuilder.getFootprint()`

Returns the storage access pattern.

getFootprint(): LedgerFootprint;

Source: src/base/sorobandata_builder.ts:205

`sorobanDataBuilder.getReadOnly()`

Returns the read-only storage access pattern.

getReadOnly(): LedgerKey[];

Source: src/base/sorobandata_builder.ts:195

`sorobanDataBuilder.getReadWrite()`

Returns the read-write storage access pattern.

getReadWrite(): LedgerKey[];

Source: src/base/sorobandata_builder.ts:200

`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:143

`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:162

`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:175

`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:86

`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:101

WasmCreateDetails

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

Source: src/base/invocation.ts:6

`wasmCreateDetails.address`

address: string;

Source: src/base/invocation.ts:8

`wasmCreateDetails.constructorArgs`

constructorArgs?: any[];

Source: src/base/invocation.ts:11

`wasmCreateDetails.hash`

hash: string;

Source: src/base/invocation.ts:7

`wasmCreateDetails.salt`

salt: string;

Source: src/base/invocation.ts:9

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(Buffer): Buffer method) or a callback function (see SigningCallback) to handle signing the envelope hash.

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

Parameters

entry — SorobanAuthorizationEntry (required) — an unsigned authorization entry

signer — Keypair | SigningCallback (required) — either a Keypair instance or a function which takes a xdr.HashIdPreimageSorobanAuthorization input payload and returns EITHER

 (a) an object containing a `signature` of the hash of the raw payload
     bytes as a Buffer-like and a `publicKey` string representing who just
     created this signature, or
 (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`).

The latter 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.

Example

import {
  SorobanRpc,
  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:
function signPayloadCallback(payload) {
   return signer.sign(hash(payload.toXDR()));
}

function multiPartyAuth(
   server: SorobanRpc.Server,
   // assume this involves multi-party auth
   tx: Transaction,
) {
   return server
     .simulateTransaction(tx)
     .then((simResult) => {
         tx.operations[0].auth.map(entry =>
           authorizeEntry(
             entry,
             signPayloadCallback,
             currentLedger + 1000,
             Networks.TESTNET)
         );

         return server.prepareTransaction(tx, simResult);
     })
     .then((preppedTx) => {
       preppedTx.sign(source);
       return server.sendTransaction(preppedTx);
     });
}

See also

authorizeInvocation

Source: src/base/auth.ts:123

authorizeInvocation

authorizeInvocation(params: AuthorizeInvocationParams): Promise<SorobanAuthorizationEntry>

Parameters

params — AuthorizeInvocationParams (required)

Source: src/base/auth.ts:239

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 { Server, buildInvocationTree } from '@stellar/stellar-sdk';

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

s.simulateTransaction(tx).then(
 (resp: SorobanRpc.SimulateTransactionResponse) => {
   if (SorobanRpc.isSuccessfulSim(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" +
         JSON.stringify(
           buildInvocationTree(auth[0].rootInvocation()),
           null,
           2
         )
       );
     }
   }
 }
);

Source: src/base/invocation.ts:120

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:48

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)
UintArray8 → 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 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

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: 'i125' }); // 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-base';

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.switch() == xdr.ScValType.scvMap()

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

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

See also

scValToNative

Source: src/base/scval.ts:161

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:375

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:487

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:229