Skip to content

Migration to 15.0.0

This guide describes all breaking changes introduced with v15.0.0.

Transaction builder

buildTxAsync doesn't write prepared values into the given params

buildTxAsync used to write the values it prepared (nonce, ttl, fee, gasPrice) back into the object it was given. It builds from a copy instead, so the object stays as the caller made it.

Read a prepared value off the built transaction instead

  const params = { tag: Tag.SpendTx, senderId, recipientId, amount, onNode };
  const transaction = await buildTxAsync(params);
- const nonce = params.nonce;
+ const { nonce } = unpackTx(transaction, Tag.SpendTx);

Only direct callers of buildTxAsync are affected — spend and the other high-level methods copy the options object before building.

Passing the same object to two builds is now correct: the second one prepares the values again instead of reusing the ones priced for the first. Before this change it produced two transactions with the same nonce, and priced the second one against the parameters of the SDK release rather than the ones of the node it is built for.

Use rebuildUnpackedTx to serialize an unpacked transaction back

buildTx prices and bounds the values it is given, so serializing the result of an unpackTx back with it re-prices a transaction that already exists. That fails for a transaction built for a node running other consensus parameters — a hyperchain or a devnet with a lower minimum gas price, an AENS transaction accepted under other name limits.

- const transaction = buildTx(unpackTx(rawTransaction));
+ const transaction = rebuildUnpackedTx(unpackTx(rawTransaction));

buildTx itself is unchanged, and stays the way to build a transaction that doesn't exist yet.

Behaviour changes

These don't need a change in your code, but they change what the sdk does.

Transactions are priced by the parameters of the connected node

buildTxAsync requests /v3/protocol-parameters and /v3/node-settings, and prices the transaction by what the node reports instead of by the constants of the sdk release. A node that doesn't provide these endpoints, can't be reached, or answers something this release can't read falls back to the previous constants. See protocolParameters in transaction options.

Two consequences worth knowing about:

  • The fee/gasPrice default is raised to the minimum gas price the miner of the connected node accepts, so a transaction is priced to be mined by the node it is submitted to. On a node whose miner minimum is above the consensus minimum this costs more than before.
  • buildTxAsync rejects with a NodeError when the node reports parameters that would price a transaction far above the sdk release. Provide protocolParameters in options to build against such parameters anyway.

MIN_GAS_PRICE and MAX_AUTH_FUN_GAS are deprecated

They are the values as they were at the moment of the sdk release, and are wrong on a node running other parameters. They are still exported.

- const gasPrice = MIN_GAS_PRICE;
+ const { minGasPrice: gasPrice } = await getCachedProtocolParameters(node);