Our team has been busy since the April release of Anchor 1.0.0 helping developers understand the EOSIO Signing Request protocol as well as the Anchor Link protocol. It’s taken a while to help everyone wrap their heads around these new protocols and find ways to integrate Anchor as a signature provider for their users to use.
I wanted to take a bit of time today to outline how this direct integration is done and highlight some of pain points we’ve discovered along the way. Hopefully this guide will help new developers integrate more easily.
Just as a preface and note, if you’re building a new application - I’d recommend avoiding a direct integration with Anchor (using anchor-link) and use either UAL or Transit to abstract wallets away from your code. This will give your users the choice in which wallet they want to use to interact with your application, something which we feel is very important for the EOSIO ecosystem moving forward. This guide will be useful if you’re not using an abstraction layer and are choosing to directly integrate wallets with your own code.
Now - with that said, if you are going to integrate directly in a more advanced way, let’s look at what needs to be done. The first thing you’ll probably need to understand is the tool chain.
To do this I’ll walk through a brief series of code we developed in one of our demo applications. This demo is a fairly well commented reactjs boilerplate that has all of the basics implemented we’re going to outline below. The only requirements the demo needs related to EOSIO are anchor-link and the anchor-link-browser-transport.
Initialize Anchor Link
The first thing you’ll need to do is initialize anchor-link for the appropriate blockchain. This init can happen on page load and requires an array of chains, containing the chain ID and API endpoint, and a transport. The anchor-link-browser-transport is available to use and should work for most use cases, but feel free to build your own.
If your application is going to support multiple blockchains, when you switch blockchains you’ll just need to reinitialize Anchor Link for the new chain and run through this process again.
Signing in a User
With Anchor Link now initialized, you can allow users to sign in. Add a button or control of some sort somewhere, and when clicked, you’ll want to call login on Anchor Link. Pass in the name of your application as the parameter, which should be a name type variable that identifies your app.
This call will create an EOSIO Signing Request, specifically an identity request, and then use the browser transport to prompt the user to complete the request. This is done either by them clicking the button or by scanning the QR code. This identity request automatically has a “callback” embedded in it with information telling the wallet how to relay back the response to your application.
In the background, Anchor Link is also going to spin up a temporary websocket connection to the callback service to await the response from that callback. Once complete it will return an identity to your application that contains information both about the user and how to communicate with them.
Anchor Link Identity & Session
The identity returned from the process of signing in a user contains a lot of useful information about the user, including their account information, signing key, and the parameters used to sign the request itself.
The other important thing it returns is a session, which you can now use to send requests to that user from your application. In our demo application, we are saving that session into our application state so it can be used in the future.
Optional - Verify the Identity
Anchor Link by default provides proof that the user logging in is actually who they say they are. The identity request itself is an actual EOSIO transaction that the user signs, and returns the signature and proof to you via the callback.
If you want to verify this for yourself, you can do so utilizing the helper functions within link or you can use eosjs/eosio-core to perform a signature check yourself.
Performing a transaction
Now with a user signed in to your application, the application can make further requests of that user. In the demo application we have been following, there is a button in the application that when clicked requests the user to sign a proxy vote action.
To do this, we retrieve the session from the applications state, then define the action we want to perform, and finally call the transact method like you would normally with eosjs… except this is done directly on the session.
The session itself has a transact method that performs some magic.
When you use the transact method on the session, what happens is your transaction is converted into an EOSIO Signing Request. This ESR payload is signed for authenticity and then routed through an encrypted session channel to the users wallet, and they are prompted to sign the request.
Again in the background, your application will automatically spin up a websocket connection to the callback service to listen for a response, and await the user to complete and return the signature for the transaction.
If successful, a response will be returned with the signature and completed transaction. Your application will then take the signed transaction and automatically broadcast it to the blockchain (unless you specify broadcast: false, in which case you’ll have to broadcast manually - the wallet will never broadcast it by itself).
Extra: Persisting a User Session
Jumping back to initialization for a moment, you are going to want to attempt to restore any existing sessions the user may have. If you find a session using this method, you can assume the user is already logged in, and if you want to have them perform a transaction you can skip the login step and use the session that was returned.
Extra: Signing Out
While a user is signed in, you can add a “Sign Out” button somewhere for the user. When this button is clicked, all you need to do is clear the session in the application state, any cookies/localstorage data your app may have generated, and call the removeSession method with the current users authorization.
Extra: Swapping Users
To sign in an additional user, just use the login on Anchor Link once more. It will run through the process again and return an additional session.
Upon initialization and whenever a new session is created, you may also want to load all available sessions and save them in your applications state for account switching functionality.
To actually switch between the sessions, you’ll use the restoreSession method again, except this time specify the authorization of the account to switch to.
Extra: Multiple EOSIO Chains
If your application supports multiple EOSIO-based blockchains, to switch between blockchains all you have to do is remove any sessions from your application state, and run through the initialization steps as outlined above. Initialize, restore sessions, and offer sign in.
That’s it.
Your application has now allowed a user to sign in, establishing a connection, and then requested a signature for a transaction and broadcast it to the blockchain. Your user sessions will persist, you can allow multiple sessions at once to switch between, and your users can also choose to logout.
You can abstract this set of logic into whatever libraries, frameworks, or setup your application users. If you need further help or have questions, feel free to ask!