{"id":13470997,"url":"https://github.com/scio-labs/use-inkathon","last_synced_at":"2025-10-15T16:42:11.426Z","repository":{"id":65206535,"uuid":"587341753","full_name":"scio-labs/use-inkathon","owner":"scio-labs","description":"Typesafe React hooks and utility functions that simplify the process of working with Substrate-based networks and ink! smart contracts.","archived":false,"fork":false,"pushed_at":"2024-12-04T17:54:49.000Z","size":4131,"stargazers_count":51,"open_issues_count":12,"forks_count":18,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-29T10:05:43.282Z","etag":null,"topics":["blockchain","hooks","ink","javascript","polkadot","polkadot-blockchain","polkadot-js","polkadot-js-api","polkadot-network","react","react-hook","react-hooks","reactjs","rust","smart-contract","smart-contracts","substrate","typescript","web3"],"latest_commit_sha":null,"homepage":"https://inkathon.xyz","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scio-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-10T14:29:28.000Z","updated_at":"2025-02-21T08:44:59.000Z","dependencies_parsed_at":"2024-04-15T00:41:17.632Z","dependency_job_id":"a5ae3908-6b0b-49e3-b995-ae6859ab7d0a","html_url":"https://github.com/scio-labs/use-inkathon","commit_stats":null,"previous_names":[],"tags_count":82,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scio-labs%2Fuse-inkathon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scio-labs%2Fuse-inkathon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scio-labs%2Fuse-inkathon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scio-labs%2Fuse-inkathon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scio-labs","download_url":"https://codeload.github.com/scio-labs/use-inkathon/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247325693,"owners_count":20920714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","hooks","ink","javascript","polkadot","polkadot-blockchain","polkadot-js","polkadot-js-api","polkadot-network","react","react-hook","react-hooks","reactjs","rust","smart-contract","smart-contracts","substrate","typescript","web3"],"created_at":"2024-07-31T16:00:38.332Z","updated_at":"2025-10-15T16:42:06.369Z","avatar_url":"https://github.com/scio-labs.png","language":"TypeScript","funding_links":[],"categories":["Client Libraries","🛠️ Libraries \u0026 Standards"],"sub_categories":["Testnets"],"readme":"![inkathon Devtooling Banner](inkathon-devtooling-banner.png)\n\n# `useInkathon` – React Hooks \u0026 Utility Library\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Built with ink!](https://raw.githubusercontent.com/paritytech/ink/master/.images/badge.svg)](https://use.ink)\n![TypeScript](https://img.shields.io/badge/TypeScript-000000?logo=typescript\u0026logoColor=white)\n![React](https://img.shields.io/badge/React-000000?logo=react\u0026logoColor=white)\n\nThis library provides typesafe React hooks and utility functions that simplify the process of working with Substrate-based networks and ink! smart contracts. It abstracts away the complexities of polkadot{.js} but still lets you access the full power of the underlying API.\n\nThe project is part of a [Scio Labs](https://scio.xyz) initiative to improve the developer experience in the ink! ecosystem and a proud member of the [Aleph Zero EFP](https://alephzero.org/ecosystem-funding-program). 💜\n\nOther projects include:\n\n- `create-ink-app` CLI (_Coming soon_)\n- [`ink!athon`](https://github.com/scio-labs/inkathon) Boilerplate\n- [`useInkathon`](https://github.com/scio-labs/use-inkathon) Hooks \u0026 Utility Library\n- [`zink!`](https://github.com/scio-labs/zink) Smart Contract Macros\n\n**Join the discussion in our [Telegram Group](https://t.me/inkathon)** 💬\n\n**Checkout our [TypeDoc Documentation](https://scio-labs.github.io/use-inkathon/)** 📃\n\n---\n\n1. [Getting started 🚀](#getting-started-)\n2. [Features ✨](#features-)\n3. [Contract Registry 🗳️](#contract-registry-️%EF%B8%8F)\n   1. [How it works](#how-it-works)\n   2. [Typed Contracts](#typed-contracts)\n4. [Examples 📚](#examples-)\n5. [Package Development 🛠](#package-development-)\n\n---\n\n## Getting started 🚀\n\n\u003e [!IMPORTANT]  \n\u003e **If you are looking for a boilerplate to start your dApp project from scratch, checkout [ink!athon](https://inkathon.xyz).**\n\n1. Go to your existing project and install the package from the npm registry:\n\n```bash\npnpm add @scio-labs/use-inkathon\n# or\nnpm install @scio-labs/use-inkathon\n# or\nyarn add @scio-labs/use-inkathon\n```\n\n2. Wrap it around your app or parent component:\n\n```ts\nimport { development, UseInkathonProvider } from '@scio-labs/use-inkathon'\n```\n\n```tsx\n\u003cUseInkathonProvider appName=\"My dApp\" defaultChain={development}\u003e\n  \u003cComponent {...pageProps} /\u003e\n\u003c/UseInkathonProvider\u003e\n```\n\n1. Use the primary `useInkathon` hook for connecting the wallet or accessing the API:\n\n```ts\nimport { useInkathon } from '@scio-labs/use-inkathon'\n```\n\n```ts\nconst { api, connect, activeChain, activeAccount, … } = useInkathon()\n```\n\n## Features ✨\n\nAt its core, this library serves as a **wrapper for polkadot{.js}, potentially saving you over 100 lines of code.** This includes:\n\n- Utility functions for API initialization, connection, account management, balance checks, transfers, contract interactions, etc.\n- React hooks \u0026 provider for easy access to all of the above, including:\n  - [`useInkathon`](https://scio-labs.github.io/use-inkathon/functions/useInkathon.html) – Main Hook responsible for connection, account management, etc.\n  - [`useBalance`](https://scio-labs.github.io/use-inkathon/functions/useBalance.html)\n  - [`usePSP22Balances`](https://scio-labs.github.io/use-inkathon/functions/usePSP22Balances.html)\n  - [`useContract`](https://scio-labs.github.io/use-inkathon/functions/useContract.html)\n  - [`useRegisteredContract`](https://scio-labs.github.io/use-inkathon/functions/useRegisteredContract.html) _(read more below)_\n- Contract interaction helper functions with automatic upfront gas estimation, including:\n  - [`contractTx`](https://scio-labs.github.io/use-inkathon/functions/contractTx.html)\n  - [`contractQuery`](https://scio-labs.github.io/use-inkathon/functions/contractQuery.html)\n  - [`decodeOutput`](https://scio-labs.github.io/use-inkathon/functions/decodeOutput.html)\n- Constants definitions for Substrate-based chains, wallets, and assets\n- Works multichain with live \u0026 dynamic chain-switching out of the box\n- Full contract-level type-safety with [`typechain-polkadot`](https://github.com/Brushfam/typechain-polkadot) via [`useRegisteredTypedContract`](https://scio-labs.github.io/use-inkathon/functions/useRegisteredTypedContract.html)\n\n\u003e [!NOTE]  \n\u003e Checkout our [TypeDoc Documentation](https://scio-labs.github.io/use-inkathon/) for more details.\n\n## Contract Registry 🗳️\n\nOften when working with smart contracts in the frontend, you have to import the contract metadata multiple times across a project, then determine the matching deployment address for the active chain, and create a `ContractPromise` instance manually each time.\n\nThe idea of a _Contract Registry_ is to **define contract metadata \u0026 addresses only once and use them everywhere with a simple hook:**\n\n```ts\nconst { contract } = useRegisteredContract('greeter')\n```\n\n### How it works\n\nStart by defining an async `getDeployments` function that returns [`SubstrateDeployment[]`](https://scio-labs.github.io/use-inkathon/interfaces/SubstrateDeployment.html) metadata objects for each contract deployment on each chain.\n\n\u003e [!NOTE]  \n\u003e Checkout an advanced example within the ink!athon boilerplate [here](https://github.com/scio-labs/inkathon/blob/main/frontend/src/deployments/deployments.ts) where metadata is imported dynamically based on defined chains and contract identifiers.\n\n```ts\nimport { alephzeroTestnet, SubstrateDeployment } from '@scio-labs/use-inkathon'\n\nexport const getDeployments = async (): Promise\u003cSubstrateDeployment[]\u003e =\u003e {\n  return [\n    {\n      contractId: 'greeter',\n      networkId: alephzeroTestnet.network,\n      abi: await import(`../deployments/metadata.json`),\n      address: '5HPwzKmJ6wgs18BEcLdH5P3mULnfnowvRzBtFcgQcwTLVwFc',\n    },\n  ]\n}\n```\n\nThe function's result passed to the `UseInkathonProvider` provider:\n\n```tsx\n\u003cUseInkathonProvider\n  appName=\"My dApp\"\n  defaultChain={alephzeroTestnet}\n  deployments={getDeployments()}\n\u003e\n  \u003cComponent {...pageProps} /\u003e\n\u003c/UseInkathonProvider\u003e\n```\n\nThen access the contract as above:\n\n```ts\nconst { contract } = useRegisteredContract('greeter')\n```\n\n### Typed Contracts\n\n\u003e [!NOTE]  \n\u003e Make sure to also install `@727-ventures/typechain-types`, `bn.js`, and `@types/bn.js` as dependencies in your project. Find a complete setup \u0026 usage example in the [`ink!athon boilerplate`](https://github.com/scio-labs/inkathon).\n\nIf you are using [`typechain-polkadot`](https://github.com/Brushfam/typechain-polkadot) to generate type-safe contracts, you can use the `useRegisteredTypedContract` hook instead:\n\n```ts\nimport GreeterContract from '[…]/typed-contracts/contracts/greeter'\n\n// …\n\nconst { typedContract } = useRegisteredTypedContract('greeter', GreeterContract)\nconst result = await typedContract.query.greet()\n```\n\n\u003e [!IMPORTANT]  \n\u003e Currently, only queries are supported until [typechain-polkadot#138](https://github.com/Brushfam/typechain-polkadot/pull/138) is merged. Alternatively, we're considering switching to the [`prosopo/typechain-polkadot`](https://github.com/prosopo/typechain-polkadot) fork completely.\n\n## Examples 📚\n\nWithin this repository:\n\n- [Vanilla React Example](./examples/react-ts) (`examples/react-ts`)\n- [Vanilla CLI Scripts Example](./examples/scripts-ts) (`examples/scripts-ts`)\n\nLive examples:\n\n- [ink!athon Boilerplate](https://inkathon.xyz)\n- [AZERO.ID](https://azero.id)\n\n## Package Development 🛠\n\n**If you want to contribute, please read our [Contributor Guidelines](https://github.com/scio-labs/use-inkathon/blob/main/CONTRIBUTING.md)** 🙏\n\n\u003e **Pre-requisites:**\n\u003e\n\u003e - Setup Node.js v18 (recommended via [nvm](https://github.com/nvm-sh/nvm))\n\u003e - Install [pnpm](https://pnpm.io/installation) (recommended via [Node.js Corepack](https://nodejs.org/api/corepack.html))\n\u003e - Clone this repository\n\n```bash\n# Install dependencies\npnpm i\n\n# Enable pre-commit hooks\npnpm simple-git-hooks\n\n# Run tsup in development mode (watching)\npnpm dev\n\n# Run package compilation in parallel with vanilla React example\npnpm run dev:react-example\n\n# Build the package\npnpm build\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow to import a development version of this package locally?\u003c/strong\u003e\u003c/summary\u003e\n\nUnfortunately, importing this package locally into other local projects requires some manual steps. You need to build \u0026 pack this package into a `.tgz`-build and then update this dependency in your other project. These steps must be repeated each time you make changes to this package.\n\n```bash\n# 1. [THIS PACKAGE] Generate a .tgz package of the build\npnpm tsup \u0026\u0026 pnpm pack\n\n# 2. [OTHER PROJECT] Add it as a dependency in your other project like:\n#    `\"@scio-labs/use-inkathon\": \"file:../scio-labs-use-inkathon-0.0.X.tgz\"`\npnpm add ../use-inkathon/scio-labs-use-inkathon-0.0.X.tgz\n\n# 3. [OTHER PROJECT] Subsequent updates can be done via\npnpm update @scio-labs/use-inkathon --force\n```\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscio-labs%2Fuse-inkathon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscio-labs%2Fuse-inkathon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscio-labs%2Fuse-inkathon/lists"}