This package has been deprecated

Author message:

replaced with @celo/react-celo

@celo-tools/use-contractkit
TypeScript icon, indicating that this package has built-in type declarations

3.1.0 • Public • Published

use-contractkit

MIT License contributions welcome Open Source Love svg1 npm version codecov

The easiest way to access ContractKit in your React applications 🔥. use-contractkit is a React hook for managing access to ContractKit with a built-in headless modal system for connecting to your users wallet of choice.

Now your DApp can be made available to everyone in the Celo ecosystem, from Valora users to self custodied Ledger users.

By default use-contractkit is styled so that you can drop it into your application and go, however it's fully customisable so you can maintain a consistent UX throughout your application.

Table of Contents

Install

yarn add @celo-tools/use-contractkit @celo/contractkit

You can use any @celo/contractkit version at least as recent as 1.5.1 including 2.0.

Supported wallets

Wallet sendTransaction signTransaction signTypedData signPersonal
Plaintext private key
Ledger
WalletConnect
Celo Extension Wallet (Metamask fork)

Basic Usage

Wrap your application with ContractKitProvider

use-contractkit uses unstated-next under the hood to inject state throughout your application. unstated-next is built on top of the React Context API so you need to make sure your application is wrapped with the provider before usage.

import { ContractKitProvider } from '@celo-tools/use-contractkit';
import '@celo-tools/use-contractkit/lib/styles.css';

function WrappedApp() {
  return (
    <ContractKitProvider
      dapp={{
        name: 'My awesome dApp',
        description: 'My awesome description',
        url: 'https://example.com',
      }}
    >
      <App />
    </ContractKitProvider>
  );
}

function App() {
  // your application code
}

Default wallets and customization

use-contractkit provides a list of default wallets (CeloExtensionWallet, Injected, Ledger, MetaMask, PrivateKey (dev only) and WalletConnect). It can be configured as shown below.

<ContractKitProvider
  dapp={{
    name: 'My awesome dApp',
    description: 'My awesome description',
    url: 'https://example.com',
  }}
  connectModal={{
    // This options changes the title of the modal and can be either a string or a react element
    title: <span>Connect your Wallet</span>,
    providersOptions: {
      // This option hides specific wallets from the default list
      hideFromDefaults: [
        SupportedProvider.MetaMask,
        SupportedProvider.Private key,
        SupportedProvider.Celo Extension Wallet,
        SupportedProvider.Valora,
      ],

      // This option hides all default wallets
      hideFromDefaults: true,
    },
  }}
>
  <App />
</ContractKitProvider>

You can also add new custom wallets that don't exist in the registry or aren't in our defaults. For now, we only support custom wallets that implement the walletconnect protocol, but more may come in the future. In the example below, we're hiding all wallets except a new custom wallet.

<ContractKitProvider
  dapp={{
    name: 'My awesome dApp',
    description: 'My awesome description',
    url: 'https://example.com',
  }}
  connectModal={{
    title: <span>Connect your ExampleWallet</span>,
    providersOptions: {
      hideFromDefaults: true,
      additionalWCWallets: [
        // see https://github.com/WalletConnect/walletconnect-registry/#schema for a schema example
        {
          id: 'example-wallet',
          name: 'Example Wallet',
          description: 'Lorem ipsum',
          homepage: 'https://example.com',
          chains: ['eip:4220'],
          // IMPORTANT
          // This is the version of WC. If more than one version is provided
          // use-contractkit will use the highest one
          versions: ['1', '2'],
          logos: {
            sm: 'https://via.placeholder.com/40/000000/FFFFFF',
            md: 'https://via.placeholder.com/80/000000/FFFFFF',
            lg: 'https://via.placeholder.com/160/000000/FFFFFF',
          },
          app: {
            browser: '...',
            ios: '...',
            android: '...',
            mac: '...',
            windows: '..',
            linux: '...',
          },
          mobile: {
            native: '...',
            universal: '...',
          },
          desktop: {
            native: '...',
            universal: '...',
          },
          metadata: {
            shortName: '...',
            colors: {
              primary: '...',
              secondary: '...',
            },
          },
          responsive: {
            mobileFriendly: true,
            browserFriendly: true,
            mobileOnly: false,
            browserOnly: false,
          },
        },
      ],
    },
  }}
>
  <App />
</ContractKitProvider>

Prompt users to connect their wallet

use-contractkit provides a connect function that will open a modal with a list of wallets your user can connect to.

import { useContractKit } from '@celo-tools/use-contractkit';

function App() {
  const { connect, address } = useContractKit();

  return (
    <>
      {address ? (
        <div>Connected to {address}</div>
      ) : (
        <button onClick={connect}>Connect wallet</button>
      )}
    </>
  );
}

After connecting to an account the address property will be set.

Use ContractKit to read chain data

Now that we've connected to an account and have the users address, we can use the kit to query on-chain data:

import { useContractKit } from '@celo-tools/use-contractkit';

function App() {
  const { kit, address } = useContractKit();

  async function getAccountSummary() {
    const accounts = await kit.contracts.getAccounts();
    await accounts.getAccountSummary(address);
  }

  return (
    ...
  )
}

Accessing user accounts

The biggest problem when developing DApps is ensuring a Web2 level experience while managing the flaky and often slow nature of blockchains. To that end we've designed use-contractkit in a way to abstract away most of that pain.

Initially connecting to a user's account is one thing, handled via the connect function we just mentioned. However once a user has connected to your DApp we can make the experience nicer for them on repeat visits.

Last connected account

use-contractkit will remember a user's last connected address when they navigate back to or refresh your DApp. Ensure that when developing your DApp nothing changes in the UI whether or not the user has a kit.defaultAccount property set.

import { useContractKit } from '@celo-tools/use-contractkit';

const { address } = useContractKit();

Get a connected account

When a user refreshes or navigates back to your page, they may not necessarily have a connected account any longer, however we shouldn't need to prompt them to login again just to view the page, that can be done only when doing an action.

For that functionality we have the performActions and getConnectedKit methods. Usage looks a little like this for getConnectedKit:

import { useContractKit } from '@celo-tools/use-contractkit';

function App() {
  const { getConnectedKit } = useContractKit();

  async function transfer() {
    const kit = await getConnectedKit();
    const cUSD = await kit.contracts.getStableToken();
    await cUSD.transfer('0x...', 10000).sendAndWaitForReceipt();
  }

  return <button onClick={transfer}>Transfer</button>;
}

and this for performActions:

import { useContractKit } from '@celo-tools/use-contractkit';

function App() {
  const { performActions } = useContractKit();

  async function transfer() {
    await performActions(async (kit) => {
      const cUSD = await kit.contracts.getStableToken();
      await cUSD.transfer('0x...', 10000).sendAndWaitForReceipt();
    });
  }

  return <button onClick={transfer}>Transfer</button>;
}

The performActions method will also take care of displaying a modal to the user telling them to confirm any actions on their connected wallet.

Network management

use-contractkit provides a network variable and an updateNetwork function you can use to display the currently connected network as well as switch to a different one (ie. Alfajores, Baklava or Mainnet).

If you'd prefer your DApp to only access a specific network (maybe you're deploying your testnet website at https://test-app.dapp.name and your mainnet version at https://app.dapp.name) you can pass the network you want to use as a variable into the provider you wrap your application with:

You can also pass in a network prop to the ContractKitProvider as the default starting network

import { ContractKitProvider, Alfajores, NetworkNames } from '@celo-tools/use-contractkit';

function WrappedApp({ Component, pageProps }) {
  return (
    <ContractKitProvider
      ...
      networks={[Alfajores]}
      network={{
        name: NetworkNames.Alfajores,
        rpcUrl: 'https://alfajores-forno.celo-testnet.org',
        graphQl: 'https://alfajores-blockscout.celo-testnet.org/graphiql',
        explorer: 'https://alfajores-blockscout.celo-testnet.org',
        chainId: 44787,
      }}
    >
      <App />
    </ContractKitProvider>
  );
}

function App () {
  ...
}

Be sure to check the use-contractkit example application for a showcase of how network management works in more depth. Usually you'll want to show a dropdown to your users allowing them to select the network to connect to.

import { useContractKit } from '@celo-tools/use-contractkit';

function App() {
  const { network, updateNetwork } = useContractKit();

  return <div>Currently connected to {network}</div>;
}

Adjust FeeCurrency

use-contractkit provides a feeCurrency variable and an updateFeeCurrency function you can use to display the currently selected feeCurrency (cUSD, CELO, cEUR). The feeCurrency can also be passed to the provider component. Valid values are CeloContract.GoldToken, CeloContract.StableToken, CeloContract.StableTokenEUR. CeloContract can be imported like so:

import { CeloTokenContract } from '@celo/contractkit'

Dark mode

use-contrackit uses Tailwind for styling, to use the modal in dark mode simply add the class tw-dark to the root <html /> tag of the web page.

Development

To run use-contractkit locally, simply clone this repository and run:

  • yarn
  • yarn dev

A hot reloading server should come up on localhost:3000, it's the exact same as what's at use-contractkit-c-labs.vercel.app.

Support

Struggling with anything use-contractkit related? Jump into the GitHub Discussions or celo-org discord channel and ask for help any time.

Versions

Current Tags

  • Version
    Downloads (Last 7 Days)
    • Published

Version History

  • Version
    Downloads (Last 7 Days)
    • Published

Package Sidebar

Install

npm i @celo-tools/use-contractkit

Weekly Downloads

55

Version

3.1.0

License

MIT

Unpacked Size

386 kB

Total Files

159

Last publish

Collaborators

  • aaron-clabs
  • dckesler
  • jmrossy
  • nicolasbrugneaux