@wharfkit/wallet-plugin-tacklebox

A WalletPlugin for use with @wharfkit/session that lets dapps login and sign transactions with TackleBox, the native wallet and block explorer for Antelope blockchains (EOS/Vaulta, WAX, Telos, and friends).

TackleBox's dapp-link support is currently marked experimental in the wallet itself. The protocol is the anchor-link protocol (ESR identity requests, buoy callbacks, sealed push channels), so this plugin will keep working as the wallet feature matures.

How it works

The flow mirrors Anchor's: requests open the wallet directly, with QR and copy-paste fallbacks.

1. Login — the plugin fires a tacklebox://request/… deep link that opens TackleBox with the ESR identity request (the wallet registers the tacklebox: scheme per user, and claims esr: only when no other wallet owns it — so an Anchor install keeps its links). The prompt keeps a Launch TackleBox link, a QR code and a Copy login request fallback (paste target: Contracts → ESR → CONNECT AS LOGIN). TackleBox answers over a buoy callback and announces its sealed push channel (link_ch / link_key / link_name).
2. Transact — signing requests are sealed to the wallet's session key and pushed straight into TackleBox over that channel; the wallet raises its own window for review. Every request still passes TackleBox's whitelist guard, contract-hash verification and signing review before a signature is produced and returned via callback. Open TackleBox and Sign manually instead fallbacks cover a closed wallet or another device.

The plugin is renderer-agnostic: it speaks only the abstract UserInterface contract (prompts, translations, metadata), so it renders identically under @wharfkit/web-renderer, @wharfkit/web-ui, or any custom session UI, and never touches the host page's styling — TackleBox's presence in the modal comes through its logo and prompt content, with theming left entirely to the integrating dapp.

Installation

npm install @wharfkit/wallet-plugin-tacklebox

Usage

Include the plugin in the walletPlugins list when initializing the SessionKit:

import {SessionKit} from '@wharfkit/session'
import {WebRenderer} from '@wharfkit/web-renderer'
import {WalletPluginTackleBox} from '@wharfkit/wallet-plugin-tacklebox'

const sessionKit = new SessionKit({
    appName: 'myapp',
    chains: [
        {
            id: 'aca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ffbeaef943642f0e906',
            url: 'https://eos.greymass.com',
        },
    ],
    ui: new WebRenderer(),
    walletPlugins: [new WalletPluginTackleBox()],
})

const {session} = await sessionKit.login()
await session.transact({action})

Options

new WalletPluginTackleBox({
    // Buoy callback-forwarder used for this dapp's callbacks.
    // TackleBox's own listening channel is announced by the wallet at login.
    buoyUrl: 'https://cb.anchor.link',
    // WebSocket constructor override (defaults to isomorphic-ws).
    buoyWs: WebSocket,
    // Keep the tacklebox: deep link from firing automatically on login and
    // manual signing; the prompt's launch link and fallbacks remain.
    disableAutoLaunch: false,
})

Trying it live

examples/dapp is a minimal browser dapp (login, self-transfer, restore, logout) for exercising the plugin against a real TackleBox build:

npm install && cd examples/dapp && npm install && npm run dev

Developing

This package is a member of the wharfkit/js monorepo. Install the workspace once from the repository root with bun install, then work in this directory:

make lib    # bundle to lib/ (cjs, esm and types)
make test   # run the mocha test suite
make check  # lint

Tests replay recorded API responses from test/data; delete a file there to re-record it against a live endpoint.

Credits

Based on the Wharfkit wallet plugin template and modeled on the Anchor wallet plugin by Greymass, whose anchor-link protocol TackleBox speaks.

License

BSD-3-Clause