A technical preview of the Session Kit in Wharf

SessionKit (Factory)

The core of the Session Kit is named after the component itself and offers itself as a factory class. This allows developers to easily produce Session objects of various types for different uses. The factory is triggered using the login method that utilizes authentication against external wallets. The result of this call returns an appropriate Session object that is ready to use within an application for a specific device.

Session (Product)

Developers working with the Session Kit will primarily be working with individual Session objects in their apps, whether crafted by hand within an application or by the SessionKit factory methods. A Session represents the connection between a device and account on an Antelope-based blockchain. These objects offer a transact method that allows actions to be performed on the blockchain by the account it is associated with.

Plugin (Add-ons)

Both the SessionKit factory and the Session instances are capable of accepting custom logic in the form of one or more Plugin packages.

• The SessionKit can optionally utilize LoginPlugins, which can modify the behavior of the factory during the login call.
• Each Session can optionally utilize TransactPlugins, which can modify the behavior of the object during the transact call.
• Each Session requires one WalletPlugin, which facilitates the creation of signatures and provides an opportunity for communication with external applications (like wallets), when required.

Additional types of plugins may be added in the future as additional needs are identified.

Creating a Session

In order for an application to interact with the blockchain, it will first need to create a Session. To do so, the developer would first need the information to set it up, including:

• The Blockchain: Which blockchain this session is configured to interact with. This includes the Chain ID and an API endpoint.
• The Account: Which account on the configured blockchain this session is using. This includes both the actor and permission.
• The Wallet: A WalletPlugin for this session that is capable of returning a signature for any interaction.

As of version 0.1.1 of the @wharfkit/session library, in practice this would look like:

import { Session } from "@wharfkit/session"

const session = new Session({
  // The Blockchain: Jungle 4's Chain ID and the API to access it.
  chain: {
    id: "73e4385a2708e6d7048834fbc1079f2fabb17b3c125b146af438971e90716c4d",
    url: "https://jungle4.greymass.com",
  },
  // The Account: "wharfkit1131" using the "test" permission.
  permissionLevel: "wharfkit1131@test",
  // The Wallet: A default plugin that will return signatures with the given private key.
  walletPlugin: new WalletPluginPrivateKey({
    privateKey: "5Jtoxgny5tT7NiNFp1MLogviuPJ9NniWjnU4wKzaX4t7pL4kJ8s",
  }),
})

The value returned by running this code is a new Session object which can now be persisted and used throughout an applications codebase. The session can be used to interact with the blockchain using its transact method.

The transact method

The transact method’s goal is to take a smart contract action or full transaction and execute it. This method requires a single argument compatible with the TransactArgs type, which contains information about the action(s) that should be performed. This information can be passed as a single action, an array of actions, a full transaction, or an EOSIO Signing Request payload.

As of version 0.1.1 of the @wharfkit/session library, passing this parameter as a single action would be:

const args = {
  action: {
    authorization: [
      {
        actor: "wharfkit1131",
        permission: "test",
      },
    ],
    account: "eosio.token",
    name: "transfer",
    data: {
      from: "wharfkit1131",
      to: "wharfkittest",
      quantity: "0.0001 EOS",
      memo: "",
    },
  },
}

const response = await session.transact(args)

In the above example, it defines a single action that executes the transfer action on the eosio.token contract. It specifies that the intent is to send 0.0001 EOS to the wharfkittest account from the wharfkit1131 account with an empty memo.

This action is being passed into the transact method call on the Session object on the last line, which facilitates the creation of the signature and sending the transaction to the blockchain.

The response value returned by the call is a TransactResponse which contains all the relevant information related to the transaction, including:

• chain: The chain used during this transaction.
• request: The raw EOSIO Signing Request that was used at the start of the call.
• resolved: The resolved EOSIO Signing Request containing the resulting transaction.
• response: The response that the API endpoint returned after the transaction was broadcast.
• signatures: The signatures generated for the resulting transaction.
• signer: The account and permission that was used to sign the transaction.
• transaction: Quick access to the ResolvedTransaction object from the resolved EOSIO Signing Request.

If any errors occur during the transact call, an exception will be thrown containing information about the failure.

Utilizing a TransactPlugin within a transact call

Any developer experienced in application development on Antelope-based blockchains will be very well versed with the design paradigms of the Session Kit that have been discussed so far. To highlight the additional benefits that the Session Kit brings, we must now shift our focus to the Plugin architecture.

This feature helps differentiate the Session Kit from previous solutions by providing additional flexibility and customization. Plugins offer an opportunity for developers to hook into many of the predefined processes within the Session and extend its capabilities. The Session makes use of the TransactPlugin type. A TransactPlugin can register custom logic at 4 different points in the transact flow, before and after the sign and broadcast phases.

In this example, the script is now going to utilize a Resource Provider plugin, one which analyzes a transaction to determine if the authorizing account requires network resources to perform it. The source code for this plugin can be found here:

https://github.com/wharfkit/resource-provider-plugin

Using the same code example as above, the code just needs a slight modification to include a plugin. As of version 0.1.1 of the @wharfkit/session library, the plugin would be passed in during the creation of the Session as follows:

import { Session } from '@wharfkit/session'
import { ResourceProviderPlugin } from '@wharfkit/resource-provider-plugin'

const session = new Session({
       // The Blockchain: Jungle 4's Chain ID and the API to access it.
   chain: {
       id: '73e4385a2708e6d7048834fbc1079f2fabb17b3c125b146af438971e90716c4d',
       url: 'https://jungle4.greymass.com',
   },
   // The Account: "wharfkit1131" using the "test" permission.
   permissionLevel: 'wharfkit1131@test',
   // The Plugins: Include a resource provider plugin.
   transactPlugins: [new ResourceProviderPlugin({
       url: 'https://jungle4.greymass.com/v1/resource_provider/request_transaction',
   }),
   // The Wallet: A default plugin that will return signatures with the given private key.
   walletPlugin: new WalletPluginPrivateKey({
       privateKey: '5Jtoxgny5tT7NiNFp1MLogviuPJ9NniWjnU4wKzaX4t7pL4kJ8s',
   })
})

Each time the transact method of this session is called, the ResourceProviderPlugin would be able to act upon the requested transaction and perform its custom logic.

Under the hood, the ResourceProviderPlugin is analyzing the transaction itself before it’s signed (using the beforeSign transaction hook) to ensure the account has the appropriate network resources to successfully execute. If the account does not have sufficient resources, it has the potential to modify the transaction to include additional actions to ensure it is accepted by the network.

This is just one example of how plugins can be used to ease the development burden on developers and enhance the user experience. Plugins can either be created exclusively for a specific application or by the community of open source developers for public use. The goal with this plugin architecture is to provide a framework for developers to create and share reusable code and prevent developers from having to reinvent the wheel.