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