Pockie Provider API

The Pockie Provider API injects a global JavaScript API into websites visited by users through the window.pockie provider object. This API enables websites to request the user's EVM account, read data from the blockchain the user is connected to, and suggest the user to sign messages and transactions.

In DApps, you can utilize the properties, methods, and events of this provider. You can start after setting up the development environment.

Properties

window.pockie.isPockie

Used to check whether the user has installed Pockie.

If MetaMask support functionality is activated, setting the window.ethereum.isMetaMask property to true can make the DApp recognize it as MetaMask.

Methods

window.pockie.isConnected()

window.pockie.isConnected(): boolean;

Returns true if the current provider is connected to the current chain. If not connected, reload the page to re-establish the connection. For more information, refer to the connect and disconnect events.

window.pockie.request(args)

interface RequestArguments {
    method: string;
    params?: unknown[] | object;
}

window.pockie.request(args: RequestArguments): Promise<unknown>;

Use this method to submit RPC API requests to the network using Pockie. This method returns a promise that returns the result of the RPC method call.

The parameters and return values vary depending on the RPC method. In most cases where parameters are used, they are of the Array type.

If the request fails, the promise is rejected with an error.

Here is an example of calling eth_sendTransaction using window.pockie.request(args):

params: [
{
    from: '0xb60e8dd61c5d32be8058bb8eb970870f07233155',
    to: '0xd46e8dd67c5d32be8058bb8eb970870f07244567',
    gas: '0x76c0', // 30400
    gasPrice: '0x9184e72a000', // 10000000000000
    value: '0x9184e72a', // 2441406250
    data:
        '0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675',
    },
];

window.pockie
    .request({
        method: 'eth_sendTransaction',
        params,
})
    .then((result) => {
        // The result varies by RPC method.
        // For example, this method returns a transaction hash hexadecimal string upon success.
})
.catch((error) => {
    // If the request fails, the Promise rejects with an error.
});

Events

The Pockie provider uses the Node.js EventEmitter API to emit events. The following is an example of receiving the accountsChanged event. After receiving the event (e.g., when a component is unmounted in React), you should remove the listener.

function handleAccountsChanged(accounts) {
// Handle new accounts, or lack thereof.
}

window.pockie.on('accountsChanged', handleAccountsChanged);

// Later

window.pockie.removeListener('accountsChanged', handleAccountsChanged);

accountsChanged

window.pockie.on('accountsChanged', handler: (accounts: Array<string>) => void);

The provider emits this event when the return value of the eth_accounts RPC method changes. eth_accounts returns an array containing either an empty array or the addresses of the most recently used accounts that the caller can access. The caller is identified by the URL origin, and all sites with the same origin share the same permissions. This means the provider emits the accountsChanged event when the user's exposed account addresses change. Receive the event to handle accounts.

chainChanged

window.pockie.on('chainChanged', handler: (chainId: string) => void);

The provider emits this event when the currently connected chain changes. Receive the event to detect the user's network.

connect

interface ConnectInfo {
    chainId: string;
}

window.pockie.on('connect', handler: (connectInfo: ConnectInfo) => void);

This event occurs when the provider becomes able to submit RPC requests for the chain. It is recommended to receive this event and use the window.pockie.isConnected() provider method to determine whether the provider is connected.

disconnect

window.pockie.on('disconnect', handler: (error: ProviderRpcError) => void);

The provider triggers an event when it can no longer submit an RPC request to the chain. This usually happens due to network connectivity issues or unexpected errors.

When the provider triggers this event, it will not accept new requests until the connection with the chain is reset. This may require users to reload the page. The window.pockie.isConnected() provider method can also be used to determine if the provider is disconnected or not.

Errors

All errors returned by the Pockie provider adhere to the following interface:

interface ProviderRpcError extends Error {
    message: string;
    code: number;
    data?: unknown;
}

The window.pockie.request(args) provider method throws an error immediately. The error code property can be used to understand why the request failed. Common codes and their meanings are:

• 4001: User rejected the request.

• -32602: Invalid parameter.

• -32603: Internal error occurred.

For a full list of errors, refer to EIP-1193 and EIP-1474.