npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@newm.io/cardano-dapp-wallet-connector

v1.3.3

Published

Cardano dApp wallet connector package

Downloads

496

Readme

Cardano dApp Wallet Connector

The Cardano wallet dApp connector library provides components, hooks, and util functions to simplify utilizing the Cardano wallet object as defined in CIP 30.

Example

The most straightforward implementation is to use the ConnectWallet component to connect a wallet and the useConnectWallet hook to access it. This example will provide a button and modal to connect a Cardano wallet. Once the wallet is connected, the wallet object and helper functions from the hook can be utilized.

import { FunctionComponent, useEffect } from "react";
import { ConnectWallet, useConnectWallet } from "@newm.io/cardano-dapp-wallet-connector";

const Example: FunctionComponent = () => {
  const { wallet, getAddress } = useConnectWallet();
  const [address, setAddress] = useState<string>()

  useEffect(() => {
    if (wallet) {
      // do whatever you need with the wallet and/or helper functions once the wallet is connected
      // e.g. get an address from the wallet and update the component state with it
      getAddress(setAddress)
    }
  }, [wallet, getAddress])

  return (
    <ConnectWallet />
  );
};

Components

ConnectWallet

Provides a button, which brings up a modal to select and connect a wallet when clicked.

Props

  • modalStyle?: CSSProperties Inline styles for the connect wallet modal.
  • modalHeaderStyle?: CSSProperties Inline styles for the modal header.
  • mainButtonStyle?: CSSProperties Inline styles for the button used to open the connect wallet modal.
  • disconnectButtonStyle?: CSSProperties Inline styles for the modal disconnect button.
  • fontFamily?: string Font family to be used throughout the component
  • isInverted?: boolean true if text, icon, and hover styles should be adjusted for a dark background.
  • onClickButton?: (event: MouseEvent) => void Called when intial button is clicked. Defaults opening the wallet modal.
  • onCloseModal?: (event: MouseEvent) => void Called when modal close icon or background is clicked. Defaults to closing the wallet modal.
  • onConnect?: (wallet: Wallet) => void Called when a wallet is connected.
  • onDisconnect?: () => void Called when a wallet is disconnected.
  • onError?: (message: string) => void Called when an error is received from the wallet.

WalletButton

Stand-alone connect wallet button from the ConnectWallet component. It can be used if you would like to create your own modal, or have it trigger functionality other than opening the connect wallet modal.

Props

  • onClick?: (event: MouseEvent) => void Called when the button is clicked.
  • style?: CSSProperties Inline styles for the button.
  • fontFamily?: string Font family for the button text.
  • isInverted?: boolean true if text styles should be adjusted for a dark background.

WalletModal

Stand-alone select wallet modal from the ConnectWallet component. It can be used if you would like to trigger the modal with your own button or other user interaction.

Example

import { FunctionComponent, useState } from "react";
import { WalletModal, useConnectWallet } from "@newm.io/cardano-dapp-wallet-connector";

const Example: FunctionComponent = () => {
  const { wallet } = useConnectWallet();
  const [isModalOpen, setIsModalOpen] = useState(false);

  return (
    <>
      <MyCustomButton onClick={ () => setIsModalOpen(true) } />

      <WalletModal isOpen={isModalOpen} onClose={ () => setIsModalOpen(false) />
    </>
  );
};

Props

  • isOpen: boolean true if the modal is open.
  • onClose: (event: MouseEvent) => void Called when the modal background or close button is clicked.
  • style?: CSSProperties Inline styles for the modal.
  • headerStyle?: CSSProperties Inline styles for the modal header.
  • disconnectButtonStyle?: CSSProperties Inline styles for the disconnect button.
  • fontFamily?: string Font family for the button text.
  • isInverted?: boolean true if text, icon, and hover styles should be adjusted for a dark background.
  • onConnect?: (wallet: Wallet) => void Called when a wallet is connected.
  • onDisconnect?: () => void Called when a wallet is disconnected.
  • onError?: (message: string) => void Called when an error is received from the wallet.

Hooks

useConnectWallet

The useConnectWallet hook returns an object with the CIP 30 wallet object and a number of helper functions.

Example

import { FunctionComponent, useEffect, useState } from "react";
import { useConnectWallet } from "@newm.io/cardano-dapp-wallet-connector";

const Example: FunctionComponent = () => {
  const { wallet, connect, getBalance, error } = useConnectWallet();
  const [walletBalance, setWalletBalance] = useState();

  useEffect(() => {
    connect("cip_30_wallet_identifier")
  }, []);

  useEffect(() => {
    if (wallet) {
      getBalance(setWalletBalance)
    }
  }, [wallet])

  if (!wallet) {
    return <div>No wallet connected.</div>;
  }

  return (
    <div>
      { wallet.name } wallet is currently connected.
      { !!walletBalance && <div>Current wallet balance is {walletBalance} ADA.</div> }
      { !!error && <div>An error occured: {error}</div> }
    </div>
  );
};

Returns

wallet: Wallet | undefined

The "Wallet" is an object as defined in CIP 30. If the wallet has not been connected yet, it will be undefined.

connect: (id: string) => undefined

Sets the wallet value for the provided wallet id.

disconnect: () => undefined

Disconnects the currently connected wallet and sets the wallet value to undefined.

isConnected: boolean

true if a wallet is connected.

getBalance: (callback: (balance: number) => undefined) => undefined

Function that accepts a callback with the current ADA balance as the argument.

getTokenBalance: (policyId: string, callback: (balance: number) => undefined, tokenName?: string) => undefined

Function that accepts a callback with the current balance for a specific policy ID and optional hex encoded token name.

getAddress: (callback: (address: string) => undefined) => undefined

Function that accepts a callback with a usable recieving address as the argument.

getChangeAddress: (callback: (address: string) => undefined) => undefined

Function that accepts a callback with a change address as the argument.

signTransaction: (tx: string, callback: (signedTx: string) => undefined, partialSign?: boolean = false) => undefined

Function that accepts an unsigned transaction, a callback with the signed transaction as the argument, and an optional partialSign argument.

isLoading: boolean

true if the wallet is currently loading (connecting, fetching balance, etc...).

error: string | undefined

An error message returned from the Cardano wallet, if one exists.

getSupportedWallets: () => Array<WalletInfo>

Returns an array of "WalletInfo" objects for Cardano wallet browser extensions.

The "WalletInfo" is an object with the following fields:

  • id: string String identifier for the wallet
  • name: string Display name for the wallet
  • icon: string Path to the icon file
  • extensionUrl: string Url for the wallet's browser extension
  • websiteUrl: string Url for the wallet's website
  • isInstalled: boolean true if the wallet browser extension has been installed

Utils

In order to allow the library functionality to be used outside of a component, the following functions can also be imported as utils:

disconnectWallet: () => void

Disconnects the currently connected wallet.

enableWallet: (walletId: string) => Promise<Wallet>

Connects the wallet corresponding to the provided wallet ID. Returns a wallet object as defined in CIP 30.

getWalletAddress: (wallet: Wallet) => Promise<string>

Returns a plain text wallet address from the provided wallet object.

getWalletChangeAddress: (wallet: Wallet) => Promise<string>

Returns a plain text wallet change address from the provided wallet object.

getWalletBalance: (wallet: Wallet) => Promise<number>

Returns the balance for the provided wallet in ADA.

getWalletTokenBalance: (wallet: Wallet, policyId: string, tokenName?: string) => Promise<number>

Returns the wallet balance for a specific policy ID and optional hex encoded token name.

signWalletTransaction: (wallet: Wallet, tx: string, partialSign?: boolean = false) => Promise<string>

Returns the full signed transaction as a CBOR encoded hex string.

getSupportedWallets: () => Array<WalletInfo>

Returns an array of "WalletInfo" objects for Cardano wallet browser extensions.

Troubleshooting

Issues with the jsdom testing library

If you're using the react-create-app package for your app (which jsdom is a dependency of), you may encounter the following error when running jest: ReferenceError: TextDecoder is not defined. This is because the cbor-web dependency references the TextDecoder global browser variable, which is not present in the jsdom test environment. This can be resolved by adding the global variable in your setupTests.js file:

import { TextDecoder } from "util";
global.TextDecoder = TextDecoder;

Another option is to mock the @newm.io/cardano-dapp-wallet-connector package for your tests:

jest.mock("@newm.io/cardano-dapp-wallet-connector", () => ({
  ...jest.requireActual,
  getWalletBalance: jest.fn(),
  useConnectWallet: jest.fn(() => ({
    wallet: {},
    connect: jest.fn(),
    disconnect: jest.fn(),
    isLoading: false,
    getAddress: jest.fn(),
    getBalance: jest.fn(),
    getSupportedWallets: jest.fn(),
  })),
}));

Roadmap

  • Improved customization
  • Additional components
  • Additional helper functions

Please let us know if you are a developer and would like to contribute to the package or if you have an idea for additional functionality. Thanks!