Wharf 4.0.0

Wharf 4.0.0 is the first release in which every @wharfkit package shares one version number, so installing any one of them brings the matching versions of the rest. It also brings session keys to @wharfkit/session, the API changes developed as @wharfkit/antelope 2.0, and a signing reliability fix for Anchor on iOS.

Package names on npm are unchanged, and every package is developed in github.com/wharfkit/js.

Upgrading

Set every @wharfkit entry in your package.json to ^4.0.0, whatever version it was on before, and reinstall from a clean lockfile:

{
  "dependencies": {
    "@wharfkit/antelope": "^4.0.0",
    "@wharfkit/session": "^4.0.0",
    "@wharfkit/wallet-plugin-anchor": "^4.0.0",
    "@wharfkit/web-renderer": "^4.0.0"
  }
}

Packages in the release depend on each other by exact version, and none declares another as a peer dependency. Remove any @wharfkit entry you added only to satisfy a peer warning, and any resolutions or overrides entry that pins a @wharfkit package, since either can bring back a second copy of a package.

Every package requires Node.js 20.19.0 or later, and both of its bundles are compiled to ES2020. webpack 4 and browsers released before March 2020 cannot parse that level; to support them, transpile @wharfkit packages in your build. Projects that must stay on an older Node.js version can stay on @wharfkit/antelope@1.

After reinstalling, confirm that your project resolves one copy of antelope with npm ls @wharfkit/antelope (or yarn why, pnpm why). The expected result is one entry at 4.0.0. @wharfkit/apiclient-leap, -telos and -wax are outside the release and depend on an older antelope, so a project using one of them resolves a second copy.

Changes to check in your code

  • K1 signatures differ byte for byte from the ones 1.x produced for the same key and message. They are valid and canonical, and older signatures still verify. Re-record any test that asserts a literal signature string.
  • PrivateKey.sharedSecret() returns the full 32 bytes of the shared x-coordinate, where 1.x stripped leading zero bytes. About one key pair in 256 derives a different secret. For those sessions, Anchor desktop, Anchor Android, Web Authenticator and TackleBox cannot open a request from a 4.0.0 application, and the request expires or fails until the user logs in again. Anchor’s option to sign manually or with another device still works in those sessions. Pass {legacy: true} to read data you encrypted with 1.x.
  • Float32.toString() returns the shortest round-tripping string, so 1.5 renders as "1.5" in place of "1.5000000". Infinity, NaN and negative zero render as nodeos spells them.
  • SessionKit.restore() takes a PartialSerializedSession, and the RestoreArgs type is removed. Only an explicit import type {RestoreArgs} needs editing.
  • SessionKit.persistSession() takes options in place of a boolean: persistSession(session, {setAsDefault: false}).
  • Namespaces re-exported from CommonJS dependencies by @wharfkit/cli, @wharfkit/protocol-esr and @wharfkit/session are no longer frozen with a null prototype in the CommonJS bundles. Only code that checks one with instanceof, Object.getPrototypeOf or Object.isFrozen sees a difference.
  • pako moved to 3.x inside antelope. It is ESM with no default export, which matters only to a project that imports pako itself.

What is new

Session keys

Your application can hold a key that signs a chosen set of actions on its own, such as the moves in a game, and send everything else to the user’s wallet. Configure the actions on the SessionKit, then ask the user to approve the key:

const sessionKit = new SessionKit(args, {
  ui,
  sessionKey: {
    whitelist: [{ contract: "eosio.token", actions: ["transfer"] }],
  },
})

await session.setupSessionKey()

setupSessionKey() generates the key, adds it under a permission named after your application, and links the listed actions to it, in one transaction the user approves. Session also has methods to check, update and remove the key. Session keys need a UserInterface that draws four prompts (consent, an existing key on the permission, a whitelist mismatch, and removal); @wharfkit/web-renderer draws all four.

Holding several sessions

equalityFn on the SessionKit decides when two stored sessions are the same, which lets an application keep several sessions for one account apart by something it stores in session.data. Four fixes land with it:

  • logout(session) clears the stored default only when that session was the default.
  • login(), restore() and persistSession() resolve after the session is in storage, so two logins in a row keep both sessions.
  • restoreAll() leaves storage untouched.
  • Each restored session gets its own wallet plugin instance.

Waiting for irreversibility

Set awaitIrreversible on transact(), or once on the SessionKit, and the call resolves only after the transaction is irreversible. broadcastOptions sets returnFailureTrace, retryTrx and retryTrxNumBlocks directly.

Anchor signing on iOS

Signing with Anchor on the same iOS device completes when Safari brings the user back in a fresh tab, a case where @wharfkit/wallet-plugin-anchor could lose the signature before.

Smaller changes

  • @wharfkit/antelope uses @noble/curves and @noble/hashes in place of elliptic, contributed by grctest.
  • Authority.sort() orders keys, accounts and waits the way nodeos does, so the chain accepts the updateauth you build with it. Name, PermissionLevel and PublicKey gained compare().
  • FetchProvider uses the fetch built into Node.js and browsers, so you can drop node-fetch.
  • get_table_rows queries float64 and float128 secondary indexes.
  • @wharfkit/roborovski gains activity(), which pages through an account’s history with next() and prev() and filters by contract, action and date range.
  • @wharfkit/web-renderer accepts colorMode, "light" or "dark".
  • @wharfkit/protocol-scatter and the four wallet plugins built on it import cleanly under Node.js.
  • @wharfkit/account-creation-plugin-metamask no longer brings a second copy of antelope.
  • @wharfkit/bundle ships @wharfkit/web-ui in place of @wharfkit/web-renderer, adds @wharfkit/token and @wharfkit/roborovski, and its ES module build is one file that imports correctly.
  • Every package is licensed under BSD-3-Clause. @wharfkit/signing-request was previously MIT.

New packages

@wharfkit/light-api is a client for the Light API service, contributed by includenull.

@wharfkit/wallet-plugin-tacklebox adds the TackleBox wallet, contributed by on-a-t-break.