A technical preview of the Session Kit in Wharf
2023-01-09
Wharf is a collection of Software Development Kits (SDKs) for developers working on Antelope applications using JavaScript. This article gives a preview of the upcoming release of the Session Kit, one of the major components in the Wharf product collection. This kit aims to provide the tools required for developers to interact with an Antelope-based blockchain.
Please note that this article contains a “Technical Preview” using an early release of Wharf’s Session Kit. This article was written in early 2023 using
@wharfkit/session
version 0.1.1. Everything within this article is subject to change as the code matures. Please refer to the official documentation (when available) on WharfKit.com for up-to-date usage instructions and information.
Session Kit
With the introduction of the Session Kit, our goal is to create a developer experience that feels similar to what they’d expect from other web technologies. A “session” is a technical concept in development that represents the connection between an authenticated device and a remote application server. When a user authenticates against an application server, a session is established which allows further actions to be performed by a specific device.
During the development of Wharf, we decided to adopt the concept of sessions and apply it to interactions with Antelope-based blockchains. This provides new developers with a sense of familiarity in order to ease the adoption curve.
The Session Kit does this by changing the mechanics under the hood, while still retaining similarities to what is expected in a Web 2.0 world. The authentication step is no longer always required, and instead each session is capable of providing the means to generate transaction signatures, whether that be directly by the Session Kit or by connecting with an external wallet.
Kit Architecture
The kit at the time of writing is made up of 3 major components, each representing a different aspect of Antelope-based application development.
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 utilizeLoginPlugins
, which can modify the behavior of the factory during thelogin
call. - Each
Session
can optionally utilizeTransactPlugins
, which can modify the behavior of the object during thetransact
call. - Each
Session
requires oneWalletPlugin
, 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.
Technical Preview
In an effort to highlight how these components work in these early versions, the rest of this article will show how they can be used as of version 0.1.1. Development of this early release has primarily focused on the Session
instances and the various uses of the TransactPlugin
architecture.
This article will also focus on manually creating a Session
rather than using the SessionKit
factory methods to create one. As of this writing, no external WalletPlugin
packages have been released and no user interfaces have been made available within the SessionKit
for user facing applications.
These usage examples showcase methods developers would typically see included in backend services, such as bots or scripts. It is anticipated that usage within user facing applications will be similar.
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.
The state and future of the Session Kit
The Session Kit is available now as an early release and is available on npmjs.com. If anyone would like to try it out in a backend project today, simply include it in your project using either npm
or yarn
.
npm install @wharfkit/session
# or
yarn add @wharfkit/session
Its capabilities at the time of this writing are very limited and subject to radical changes, we only advise using it for development and experimentation purposes.
Over the coming months, the Session Kit will continue to evolve based on our current plans and feedback collected from the developer community. It is anticipated that the following features will be added next:
- Addition of a User Interface on top of the
SessionKit
which allows web applications to prompt for the information required to createSession
objects. - The creation of multiple
WalletPlugin
packages to allow interactions with the most widely used wallets in the Antelope ecosystem. - A number of additional
LoginPlugin
andTransactPlugin
will be created and released to test the capabilities of the plugin architecture. - Optimizations to the core capabilities of the
Session
to allow caching and better API call patterns.
While the Session Kit is still not ready for production applications, hopefully this article has outlined the benefits that it already provides. As development work continues, it will provide even greater benefits to developers building on Antelope-based blockchains.
Feedback and Collaboration
Feedback and collaboration from the developer community is always welcome. If you’d like to adopt and start using the Session Kit to help guide its development, please give it a try.
To communicate with Greymass and other developers involved about this project, we encourage you to reach out on one of the platforms listed below:
- The WharfKit.com website contains recorded calls and (eventually) documentation.
- Issues for the Session Kit exist on Github.
- Realtime chat about Wharf and the Session Kit in Telegram.
- A TransactPlugin template is available on Github