v0.10.1

Please refer to the v0.10.0 release notes for a detailed changelog in this minor version, as this this patch release only adds small bug fixes and performance improvements.

Fixed

• Upgraded stellar-base dependency to fix a TypeScript definition bug (#665).
• Decreased bundle size by refactoring assembleTransaction to use new abstractions from stellar-base (#120).

v0.10.0

Breaking Changes

• We have dropped all support for the deprecated hex-encoded contract ID format (#117, #658).

You should use the well-supported C... strkey format, instead. To migrate, you can do something like

let contractId = StrKey.encodeContract(Buffer.from(hexContractId, 'hex'));

Added

• Updated stellar-base dependency to v10.0.0-soroban.5 which introduces many helpful Soroban abstractions (see full release notes for more details and TypeScript interfaces):
  • Use an existing, immutable Transaction as a template for a new one via TransactionBuilder.cloneFrom(tx, opts = {}) and use opts to override fields (#656).
  • Use the new SorobanDataBuilder class to easily prepare Soroban transaction footprints #660.
  • Use humanizeEvents to create human-readable versions of xdr.ContractEvents and xdr.DiagnosticEvents that come out of transaction meta (#659).
  • Use several helpers to reliably build Soroban authorization entries for complex, multi-party signing scenarios (#663). These are each at various levels of granularity/complexity:
    • authorizeInvocation
    • authorizeInvocationCallback
    • buildAuthEnvelope
    • buildAuthEntry

Fixed

• assembleTransaction() (and Server.prepareTransaction() by proxy) will now override the authorization portion of simulation if you provide a transaction with existing authorization entries. This is because, in complex auth scenarios, you may have signed entries that would be overwritten by simulation, so this just uses your existing entries (#114).
• Added a missing type field to the EventResponse interface (#118).

New Contributors

• @tyvdh made their first contribution in #118

Full Changelog: v0.9.2...v0.10.0

v0.9.2

Updated

• Updated stellar-base dependency to fix the way scValToNative converts string and symbol values: they will always decode strings when possible (#112 for #645).

v0.9.1

What's Changed

• Update stellar-base to v10.0.0-soroban.3, to fix a bug with Contract.call method. (#109)

Full Changelog: v0.9.0...v0.9.1

v0.9.0

Preview 10 Release Notes

This Preview outlines a foundation for State Expiration on the Soroban platform.

XDR Changes

Significant changes have happened in the way that authorization trees are defined for contract invocations. This should be covered by transaction simulation, but you can view stellar/js-stellar-base#633 and stellar/js-stellar-base#634 for details and diffs around the changes.

Breaking Changes

• The Server.getContractData method now takes an optional parameter of a new type, Durability, representing the "keyspace" of the contract data. It should be set to either Durability.Persistent (the default) or Durability.Temporary, depending on the type of storage that backs this particular piece of data (#103).
• The Operation.invokeHostFunction method now takes a func parameter that should be an xdr.HostFunction instead of an args parameter.
• The Operation.invokeHostFunctions method has been removed because multiple host function invocations in a single operation are no longer supported.

New Operations

• To facilitate bumping rent and expiration for contract ledger entries, there are two new operations:
  • Operation.bumpFootprintExpiration({ ledgersToExpire: number }) bumps the expiration all of the read and written ledger keys in the transaction's sorobanData by the specified number of ledgers
  • Operation.restoreFootprint() uses the transaction's sorobanData field to restore the entire footprint
• Server.prepareTransaction now incorporates simulation results containing the new operations as part of assembleTransaction (#108).

New Features

We've made an effort to improve the abstractions around dealing with smart contract values (xdr.ScVal). There are a handful of new helpful interfaces to make dealing with them easier:

Large Integers

"Large" integers (e.g. 64, 128, and 256-bit values) and their ScVal equivalents (for passing to raw Operation.invokeHostOperation structures, to Contract.call(...) invocations, or as part of the authorization framework) can now easily be crafted from strings or bigints.

You should never need to deal with bitwise operations or endianness again!

This is accomplished via the following APIs:

class ScInt {
  constructor(
    value: number | string | bigint | ScInt,
    opts?: { type: ScIntType }
  );

  toU64(): xdr.ScVal;
  /* ... and the others ... */

  toString(): string;
  toBigInt(): bigint;
  toNumber(): number;
}

function scValToBigInt(scv: xdr.ScVal): bigint;

The interfaces should be pretty self-explanatory, but you can refer to the documentation for details and example usage. To keep it simple, you can do:

let input = "1000000000000";
let scv = new ScInt(input).toU128();

Here, scv is an xdr.ScVal with the U128 type. Similarly, you can get the integer back out:

let bigi = scValToBigInt(scv);
bigi === 1000000000000n

Native Conversions

There are also new abstractions to easily convert between native JavaScript types and xdr.ScVals. Since they are new and very high-level, they try to make reasonable assumptions about what you hope to accomplish.

You should never need to deal with converting basic (and nested basic) types to and from XDR smart contract values (ScVals)!

The APIs are:

function nativeToScVal(n: any, opts?: { type: any }): xdr.ScVal;
function scValToNative(n: xdr.ScVal): any;

The documentation has details on each conversion and what types of conversions you can force via options, but here's some simple examples:

const native = {
  name: "soroban",
  age: 123,
  interests: [
    "smart", 
    "contract", 
    "abstractions"
  ]
}

const scv = nativeToScVal(native, { 
  type: {
    // force the age to be interpreted as a symbol key and i128 value
    age: ['symbol', 'i128']
    // all other entries will have default conversions
  }
});
// naturally, scValToNative(scv) == scv

// you can do the same type-interpretation as above for large integers
const scvAge = nativeToScVal(native.age, 'u32');

It handles most of the ScVal types you will see in high-level contexts and even handles nested types.

---

Full Changelog: v0.8.1...v0.9.0

v0.8.1

Fix

• The stellar-base library is now pinned to a specific version so that a fresh installation (via e.g. npm i soroban-client) does not implicitly pull the latest major version (i.e. one without Soroban support) of the dependency (#100).

v0.8.0

Added

• Server.getContractId() now accepts a contract strkey (#97).

Updated

• The XDR library (stellar-base) has been upgraded to handle contract strkeys (C... addresses) better (see #612 and #614 of stellar-base) (#98).

• Misc. dependencies have been upgraded and the buffer polyfill is now a primary dependency (#98).

New Contributors

• @willemneal made their first contribution in #97

Full Changelog: https://github.com/stellar/js-soroban-client/blob/main/CHANGELOG.md#v080

v0.7.2

Fixed

• Downstream dependencies are transpiled to target the same older JS environments as the main library (#96).

Full Changelog: v0.7.1...v0.7.2

v0.7.1

Fixed

• The module was not being exported correctly in browser environments; the following should now work in your project (#95):

import * as SorobanClient from 'soroban-client';

• The browser bundles compatibility has increased, supporting older JS environments and undoing #90 from v0.7.0 (#95).

---

Full Changelog: v0.7.0...v0.7.1

v0.7.0

Breaking

• Replaced the deprecated getLedgerEntry with getLedgerEntries (#66).

Fixed

• Transaction simulation parses correctly when there is no auth (#89).
• TypeScript types are packaged correctly (#86).
• Documentation is packaged correctly (#87, #88).

Updated

• Published bundles support modern JS features (ES6ish) (#90).

---

Contributors

@stellarsaur
@sreuland
@Shaptic

Full Changelog: v0.6.0...v0.7.0