@amax/amaxwallet-adapters

@amax/amaxwallet-adapters provides multiple wallet adapters to help developers connect to Amax wallet.

Supported wallets

As @amax/amaxwallet-adapters exports adapter of each wallet , you can use this package, or use the individual wallet adapter you want.

| NPM package | Description | Source Code | | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | @amax/amaxwallet-adapters | Includes all the wallet adapters | View | | @amax/amaxwallet-adapter-armodillo | adapter for Armadillo | View | | @amax/amaxwallet-adapter-aplink | adapter for adapter for APLink | View | | @amax/amaxwallet-adapter-metamask | adapter for Metamask | View | | "@amax/amaxwallet-adapter-unisat | adapter for UniSat | View |

Usage

If you are working in a typescript project, you must set skipLibCheck: true in tsconfig.json.

React

You can use @amax/amaxwallet-adapters in your component. Use useMemo to memorize the adapter to improve your web performance.

import { ArmodilloAdapter } from '@amax/amaxwallet-adapters';

function App() {
    const [readyState, setReadyState] = useState(WalletReadyState.NotFound);
    const [account, setAccount] = useState('');
    const [signedMessage, setSignedMessage] = useState('');

    const adapter = useMemo(() => new ArmodilloAdapter({permission: 'owner' }), []);

    useEffect(() => {
        setReadyState(adapter.readyState);
        setAccount(adapter.account!);

        adapter.on('connect', () => {
            setAccount(adapter.account!);
        });

        adapter.on('readyStateChanged', (state) => {
            setReadyState(state);
        });

        adapter.on('accountsChanged', (data) => {
            setAccount(data);
        });

        adapter.on('disconnect', () => {
            // when disconnect from wallet
        });
        return () => {
            // remove all listeners when components is destroyed
            adapter.removeAllListeners();
        };
    }, []);

    async function sign() {
        const res = await adapter!.signMessage('helloworld');
        setSignedMessage(res);
    }

    return (
        <div className="App">
            <div>readyState: {readyState}</div>
            <div>current account: {JSON.stringify(account)}</div>
            <button disabled={adapter.connected} onClick={() => adapter.connect()}>
                Connect to Amax
            </button>
            <button onClick={sign}>sign message</button>
            <br />
            SignedMessage: {signedMessage}
        </div>
    );
}

A demo with cdn file can be found here.

Vue

In Vue, as the created/mounted hook just can be executed once, you can init the adapter in mounted or created hook.

// vue2.x
export default {
    created() {
        this.adapter = new ArmodilloAdapter();
        this.adapter.on('connect', () => {
            // here you can do something
        });
    },
    beforeDestroy() {
        this.adapter.removeAllListeners();
    }
}

// vue3
export default {
    setup() {
        onMounted(function() {
            const adapter = new ArmodilloAdapter();
            adapter.on('connect', () => {
                // here you can do something
            });
        });
        onBeforeUnmount(function() {
            // remove all listeners when components is destroyed
            adapter.removeAllListeners();
        });
        return {};
    }
}

API Reference

Adapter

The Adapter class defines the common interface for all adapters of specified wallets.

Constructor

• constructor(config): adapter constructor method, an optional config is valid. For detailed config type, refer to the following adapter section.

Properties

• name: The name of the adapter.
• url: The website of the adapter's wallet.
• icon: The icon of the adapter's wallet.
• readyState: The wallet's state, which includes three value:
  • Loading: When adapter is checking if the wallet is available or not.
  • NotFound: The wallet is not detected in current browser.
  • Found: The wallet is detected in current browser.
• account: The account of current account when the adapter is connected.
• connecting: Whether the adapter is trying to connect to the wallet.
• connected: Whether the adapter is connected to the wallet.

Methods

• connect(): Promise<void>: connect to the wallet.
• disconnect(): Promise<void>: disconnect to the wallet.
• signMessage(message): Promise<string>: sign a string, return the signature result.
• transact(actions): Promise<TransactResult>: push a transaction.

Events

Adapter extends the EventEmitter class in eventemitter3 package. So you can listen to the events by adapter.on('connect', function() {}).

Events are as follows:

• connect(address): Emit when adapter is connected to the wallet. The parameter is the address of current account.
• disconnect(): Emit when adapter is disconnected to the wallet.
• readyStateChanged(state: WalletReadyState): Emit when wallet's readyState is changed. The parameter is the state of wallet:

  enum WalletReadyState {
      /**
       * Adapter will start to check if wallet exists after adapter instance is created.
       */
      Loading = 'Loading',
      /**
       * When checking ends and wallet is not found, readyState will be NotFound.
       */
      NotFound = 'NotFound',
      /**
       * When checking ends and wallet is found, readyState will be Found.
       */
      Found = 'Found',
  }

• accountsChanged(address: string, preAddress: string): Emit when users change the current selected account in wallet. The parameter is the address of new account.
• chainChanged(chainInfo: ChainInfo): Emit when users change the current selected chain in wallet. The parameter is the new network config：

  interface ChainInfo {
      chainId: string;
  }

• error(WalletError): Emit when there are some errors when call the adapter's method. The [WalletError Types] is defined as follows.

WalletError

WalletError is a superclass which defines the error when using adapter. All error types are extended from this class. Developers can check the error type according to the error instance.

try {
    // do something here
} catch (error: WalletError) {
    if (error instanceof WalletNotFoundError) {
        console.log('Wallet is not found');
    }
}

All errors are as follows:

• WalletNotFoundError: Occurs when wallet is not installed.
• WalletNotSelectedError: Occurs when connect but there is no selected wallet.
• WalletDisconnectedError: Occurs when wallet is disconnected. Used by some wallets which won't connect automatically when call signMessage() or signTransaction().
• WalletConnectionError: Occurs when try to connect a wallet.
• WalletDisconnectionError: Occurs when try to disconnect a wallet.
• WalletSignMessageError: Occurs when call signMessage().
• WalletSignTransactionError: Occurs when call signTransaction().

Following exmaple shows how to get original error info with WalletError:

const adapter = new ArmodilloAdapter();
try {
    await adapter.connect();
} catch (e: any) {
    const originalError = e.error;
}

• Constructor(config: ArmodilloAdapterConfig)

  interface ArmodilloAdapterConfig {
      permission?: string;
      walletProviderLocalStorageKey?: string;
  }

• TronLink Doesn't support disconnect by DApp. As ArmodilloAdapter doesn't support disconnect by DApp website, call adapter.disconnect() won't disconnect from amax extension really.

• Auto open TronLink app in mobile browser. If developers call connect() method in mobile browser, it will open DApp in TronLink app to get amax wallet.