useInkathon – React Hooks for Substrate & ink!

Typesafe React Hooks abstracting functionality by polkadot.js for working with Substrate-based networks and ink! Smart Contracts.

By Dennis Zoma & Scio Labs 🪄

Join our Telegram Group 💬

Live in Action 🚢

See this library live & in action within our ink!athon dApp boilerplate!

Disclaimer 🚨

This package is under development and not ready for production use yet. See the open issues.

Documentation 📃

https://scio-labs.github.io/use-inkathon/

Features ✨

• Wrapper for polkadot.js (wallet connection, account switching, etc.) that saves you 100+ lines of code
• Easy-to-use React Hooks:
  • useInkathon – Main Hook responsible for connection, account management, etc.
  • useBalance – Fetches the native token balance of a given wallet
  • useContract – Instantiates a polkadot.js ContractPromise for given abi & address
  • useRegisteredContract – Instantiates a contract with only one single identifier (read more about the contract registry concept below)
• Contract Interaction Helper Functions: Call mutating (contractTx) and non-mutating (contractQuery) contract functions with automatic upfront gas estimation.
• Constants/Definitions for Substrate-based chains & wallets
• Makes polkadot.js compatible with server-side environments (i.e. Next.js)
• Works multichain with live & dynamic chain-switching out-of-the-box

Getting Started

Install the package from the npm registry:

npm install @scio-labs/use-inkathon

Use it:

1. Wrap it around your app or parent component:

// import { development, UseInkathonProvider } from '@scio-labs/use-inkathon'

<UseInkathonProvider appName="ink!athon" defaultChain={development}>
  <Component {...pageProps} />
</UseInkathonProvider>

2. Use the useInkathon hook everywhere underneath to access all the exposed properties below.

import { useInkathon } from '@scio-labs/use-inkathon'

const { api, connect, activeChain, activeAccount, … } = useInkathon()

The Contract Registry Concept 🌟

Define metadata once and create ContractPromises everywhere with just a single identifier:

const { contract } = useRegisteredContract('greeter')

This works by defining typesafe contract metadata objects (example) which are passed to the UseInkathonProvider provider (example).

import { alephzeroTestnet, SubstrateDeployment } from '@scio-labs/use-inkathon'

export const getDeployments = async (): Promise<SubstrateDeployment[]> => {
  return [
    {
      contractId: 'greeter',
      networkId: alephzeroTestnet.network,
      abi: await import(
        `@inkathon/contracts/greeter/deployments/metadata.json`
      ),
      address: '5HPwzKmJ6wgs18BEcLdH5P3mULnfnowvRzBtFcgQcwTLVwFc',
    },
  ]
}

<UseInkathonProvider
  appName="ink!athon"
  defaultChain={alephzeroTestnet}
  deployments={getDeployments()}
>
  <Component {...pageProps} />
</UseInkathonProvider>

---

Package Development

# Install pnpm (https://pnpm.io/)
npm i -g pnpm

# Install dependencies
pnpm i

# Start tsup in development mode (watching)
pnpm dev

# Build the package and generated docs
pnpm build

Heads up, when locally importing a development version of this package into other projects: Unfortunately, this does not yet work w/o generating a local packages .tgz-build every time. Otherwise, polkadot.js thinks it's installed twice with two different versions.

# 1. [THIS PACKAGE] Generate a .tgz package of the build
pnpm tsup && pnpm pack

# 2. [OTHER PROJECT] Add it as a dependency in your other project
#    NOTE: This results in a package.json entry like: `"@scio-labs/use-inkathon": "file:../scio-labs-use-inkathon-0.0.1-alpha.X.tgz"`
pnpm add ../use-inkathon/scio-labs-use-inkathon-0.0.1-alpha.X.tgz
# 3. [OTHER PROJECT] Subsequent updates can be done via
#    TIP: Add `--offline` flag for faster package updates
pnpm update @scio-labs/use-inkathon

Package Release

GITHUB_TOKEN=… pnpm release-it