AlcorDocs
Alcor Signer

WharfKit plugin

Connect a dApp to Alcor Signer with WharfKit Session Kit: install, sign-in, transactions, what is refused, errors, pop-ups and local development.

Alcor Signer connects through WharfKit Session Kit as a wallet plugin, @alcorexchange/wallet-plugin-alcor-signer. If your dApp already uses Session Kit with Anchor or another wallet, it is one more entry in walletPlugins.

Your site must be on the Signer's list first. Write to the Alcor team in Telegram, t.me/alcorexchange, with your exact origins. See Get your site listed.

Install

npm install @wharfkit/session @wharfkit/web-renderer @alcorexchange/wallet-plugin-alcor-signer

Version 0.2.0 or later has proveAccount.

Set up Session Kit

import { SessionKit } from '@wharfkit/session'
import { WebRenderer } from '@wharfkit/web-renderer'
import { WalletPluginAlcorSigner } from '@alcorexchange/wallet-plugin-alcor-signer'

const sessionKit = new SessionKit({
  appName: 'yourapp',
  chains: [
    { id: '1064487b3cd1a897ce03ae5b6a865651747e2e152090f99c1d19d44e01aea5a4', url: 'https://wax.greymass.com' },
  ],
  ui: new WebRenderer(),
  walletPlugins: [new WalletPluginAlcorSigner()],
})

The networks the Signer signs on:

NetworkChain id
Telos4667b205c6838ef70ff7988f6e8257e8be0e1284a2f59699054a018f743b1d11
WAX1064487b3cd1a897ce03ae5b6a865651747e2e152090f99c1d19d44e01aea5a4
XPR Network384da888112027f0321850a169f737c33e53b388aad48b5adace4bab97f437e0
Vaultaaca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ffbeaef943642f0e906

The url is for Session Kit's own reads and the push. The Signer never uses it: it builds and checks with its own nodes, and only the network's name travels to it.

Sign in

const { session } = await sessionKit.login()
session.actor       // 'alice'
session.permission  // 'active'

The Signer window opens; the person unlocks with their passkey and picks one of their accounts on that network (one passkey can hold several). The plugin then looks up which permission of that account holds the passkey and prefers active. A person with no account on the network is told so in the window, and login fails.

Session Kit restores the session after a reload as usual; the plugin keeps only the passkey's public key.

Send a transaction

await session.transact({
  actions: [
    {
      account: 'eosio.token',
      name: 'transfer',
      authorization: [session.permissionLevel],
      data: { from: session.actor, to: 'bob', quantity: '1.00000000 WAX', memo: 'thanks' },
    },
  ],
})

What happens:

  1. The plugin sends only the actions to the Signer window.
  2. The Signer builds the transaction itself: reference block and expiration from its own nodes, the chain id from its registry. It decodes the actions with ABIs it checked and shows them in plain words, with warnings.
  3. The person clicks Confirm (and touches the passkey, unless they turned on Fast sign for this account).
  4. The plugin gets back the Signer's transaction and its signatures, checks that the actions are byte for byte the ones you sent, and hands it to Session Kit, which pushes it.

Because the Signer sets the transaction header, Session Kit's allowModify must stay on. It is on by default.

Refused before the window opens

WhatError
Context-free actionsAlcor Signer does not sign context-free actions
Transaction extensionsAlcor Signer does not sign transaction extensions
delay_secAlcor Signer does not sign delayed transactions
A network the Signer does not sign onAlcor Signer does not sign on chain <id>

Refused in the window

Permission changes are never signed for an app: eosio::updateauth, deleteauth, linkauth, unlinkauth, canceldelay, setcode, setabi, every eosio.msig action, and an action whose contract or name is not a canonical Antelope name. The window says so and the request fails. Nothing your dApp can send changes this.

Signing modes

Each account has a mode in the person's browser, and your dApp can neither read nor change it:

  • Passkey: every signature needs the passkey.
  • Fast: a browser key on the account signs with a button in the window, no Face ID.
  • Auto works only on Alcor's own trading app. On your site every transaction opens the window.

Errors

ErrorMeansDo
SignerRejected (class), e.g. Rejected by the user, The Alcor Signer window was closedThe person said no or closed the windowNothing to report. Let them try again
Alcor Signer did not open in time, or does not accept requests from <origin>The window never answered: your origin is not listed, or the page did not loadCheck the listing, then the network
The browser blocked the Alcor Signer window. Allow pop-ups for this site.No pop-up and no WharfKit UI to ask for a clickCall login / transact from a click handler
Alcor Signer did not answer. Try again.The window loaded but gave no answer in 3 minutesRetry
Alcor Signer returned other actions than the app asked to signThe signed transaction is not yoursDo not push; report it
Sign in with Alcor Signer againThe session lost the passkey's keylogin again
<account> is not authorized by this passkeyThe account no longer holds this passkeylogin again

SignerRejected is exported: import { SignerRejected } from '@alcorexchange/wallet-plugin-alcor-signer'.

Pop-ups

Safari opens a window only right after a click, and Session Kit may reach nodes before it calls the plugin. When the browser holds the window back, the plugin shows a button in the WharfKit dialog that opens it. Start login, transact and proveAccount from a click, and pass Session Kit's ui where you can.

Local development

Run the Signer locally and point the plugin at it:

import { SIGNER_ORIGINS, WalletPluginAlcorSigner } from '@alcorexchange/wallet-plugin-alcor-signer'

new WalletPluginAlcorSigner({ signerOrigin: SIGNER_ORIGINS.development }) // https://sign.localhost:8443

The local Signer answers one partner origin, https://localhost:4000: serve your dApp there over https. It signs on the real networks, with real accounts.

Checklist

  • Your production and staging origins are listed (Telegram, t.me/alcorexchange).
  • allowModify is on.
  • No context-free actions, extensions or delay_sec.
  • login, transact and proveAccount start from a click.
  • SignerRejected is handled as a cancel, not as a failure.
  • Your dApp pays its own CPU and NET.

On this page