API Reference

Properties

isXPLL

This property is true if the user has the extension installed.

window.xpll.isXPLL; // => true

Request

The request method is intended as a transport- and protocol-agnostic wrapper function for Remote Procedure Calls (RPCs).

If resolved, the Promise will resolve with a result per the RPC method’s specification. If the returned Promise rejects, it will reject with an XPLLProviderRpcError as specified in the Errors section below.

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

request(data: RequestArguments): Promise<Result>;
// or reject with `XPLLProviderRpcError`

Parameters

• method: Indicates which RPC method to call
• params: An optional array or object of arguments to pass with the RPC

Helper Functions

To improve the developer experience, the Provider also implements a list of helper functions, which helps simplify the RPC method call.

Request Permission

Request permission to access the user's accounts.

Warning

The request causes a pop-up to appear. You should only request permission in response to a direct user action, such as a button click.

Failure

If the user rejects the request, the User Rejected Request 4001 error will be thrown.

interface Permission {
  id: string;
  invoker: string;
  parent_capability: string;
  caveats: {
    type: string;
    value?: unknown;
  }[];
  created_at: number;
}
interface RequestPermissionRequest {
  method: "request_permissions";
}
type RequestedPermissionResult = Permission;

RPCHelper Function

window.xpll.request({
  method: "request_permissions"
});

window.xpll.requestPermissions();

Is Wallet Locked

Return true if the wallet is locked; return false otherwise.

interface IsWalletLockedRequest {
  method: "is_wallet_locked";
}
type IsWalletLockedResult = boolean;

RPCHelper Function

window.xpll.request({
  method: "is_wallet_locked"
});

window.xpll.isWalletLocked();

Get Permissions

Return all permissions that have been granted to the wallet.

interface Permission {
  id: string;
  invoker: string;
  parent_capability: string;
  caveats: {
    type: string;
    value?: unknown;
  }[];
  created_at: number;
}
interface GetPermissionsRequest {
  method: "get_permissions";
}
type GetPermissionsResult = Permission[];

RPCHelper Function

window.xpll.request({
  method: "get_permissions"
});

window.xpll.getPermissions();

Get Accounts

Return the list of account addresses owned by the user.

Warning

The get_accounts should have permission granted; otherwise, the User Rejected Request 4001 error will be thrown. Please check Permissions for more details.

interface GetAccountsRequest {
  method: "get_accounts";
}

type GetAccountsResult = string[];

RPCHelper Function

window.xpll.request({
  method: "get_accounts"
});

window.xpll.getAccounts();

Get Active Account

Get the address of the currently active account;
return undefined if the user still needs to register.

Warning

The get_active_account should have permission granted; otherwise, the User Rejected Request 4001 error will be thrown. Please check Permission for more details.

interface GetActiveAccountRequest {
  method: "get_active_account";
}
type GetActiveAccountResult = string | undefined;

RPCHelper Function

window.xpll.request({
  method: "get_active_account"
});

window.xpll.getActiveAccount();

Get Active Account Balance

Return the balance of the active account in XPLL.

Warning

The get_active_account_balance should have the permission granted; otherwise, the User Rejected Request 4001 error will be thrown. Please check Permission for more details.

interface GetActiveAccountBalanceRequest {
  method: "get_active_account_balance";
}
type GetActiveAccountBalanceResult = string;

RPCHelper Function

window.xpll.request({
  method: "get_active_account_balance"
});

window.xpll.getActiveAccountBalance();

Get Active Account Latest Transactions

Return the latest transactions of the active account.

Params

• limit: The number of transactions to return. The default value is 1.
• order: The order of transactions to return. The default value is desc.

Warning

The get_active_account_latest_transactions should have the permission granted; otherwise, the User Rejected Request 4001 error will be thrown. Please check Permission for more details.

interface GetActiveAccountLatestTransactionsRequest {
  method: "get_active_account_latest_transactions";
  params?: {
    limit?: number;
    order?: "asc" | "desc";
  };
}

interface TransactionSummary {
  amount: string;
  block_hash: string;
  commands: string[];
  command: string;
  exit_status?: string;
  gas_consumed: string;
  gas_limit: string;
  hash: string;
  nonce: string;
  number: string;
  signer: string;
  status: number;
  timestamp: number;
  tx_gas_consumption: string;
}
type GetActiveAccountLatestTransactionsResult = TransactionSummary[];

RPCHelper Function

window.xpll.request({
  method: "get_active_account_latest_transactions",
  params: {
    limit: 1,
    order: "desc",
  }
});

window.xpll.getActiveAccountLatestTransactions({
  limit: 1,
  order: "desc",
});

Get Current Network

Return the current network.

interface GetCurrentNetworkRequest {
  method: "get_current_network";
}
type GetCurrentNetworkResult = string | undefined;

RPCHelper Function

window.xpll.request({
  method: "get_current_network"
});

window.xpll.getCurrentNetwork();

Send Token

Transfer tokens to another account; return the transaction hash if the request is successful.

Params

• amount: The amount of tokens to transfer in XPLL.
• recipient: The address of the recipient account.
• nonce: The nonce of the transaction. If not provided, the nonce will be calculated automatically.
• gas_limit: The gas limit of the transaction. If not provided, the gas limit will be calculated automatically.
• max_base_fee_per_gas: The maximum base fee per gas of the transaction. The default value is 8.
• priority_fee_per_gas: The priority fee per gas of the transaction. The default value is 0.

Warning

The request causes a pop-up to appear. You should only request permissions in response to a direct user action, such as a button click.

Failure

If the user rejects the request, the User Rejected Request 4001 error will be thrown.

Tip

Send Token is only for XPLL transfers. If you want to transfer the PRFC1 token, we should use Call Contract instead.

interface SendTokenRequest {
  method: "send_token";
  params: {
    amount: string | number | bigint;
    recipient: string;
    nonce?: string | number | bigint;
    gas_limit?: string | number | bigint;
    max_base_fee_per_gas?: string | number | bigint;
    priority_fee_per_gas?: string | number | bigint;
  };
}
export type SendTokenResult = string; // transaction hash

RPCHelper Function

window.xpll.request({
  method: "send_token",
  params: {
    recipient: "FOg6_UOmsPRs4KOECp3G2UoSS1sUQQH8NSgNa_IkQ_8",
    amount: "1",
    gas_limit: "166350",
    nonce: "17",
    max_base_fee_per_gas: "8",
    priority_fee_per_gas: "0",
  },
});

window.xpll.sendToken({
  recipient: "FOg6_UOmsPRs4KOECp3G2UoSS1sUQQH8NSgNa_IkQ_8",
  amount: "1",
});

Call Contract

Call the method except the view method of the contract; return the transaction hash if the request is successful.

Params

• method: The method of the contract.
• address: The address of the contract.
• args: The arguments of the contract's method.
• nonce: The nonce of the transaction. If not provided, the nonce will be calculated automatically.
• gas_limit: The gas limit of the transaction. If not provided, the gas limit will be calculated automatically.
• max_base_fee_per_gas: The maximum base fee per gas of the transaction. The default value is 8.
• priority_fee_per_gas: The priority fee per gas of the transaction. The default value is 0.

Warning

The request causes a pop-up to appear. You should only request permissions in response to a direct user action, such as a button click.

Arguments Serialization

The arguments of the contract method should be serialized as Uint8Array before passing to the call_contract method.

The primitive types are serialized based on Borsh binary serialization format. You can use the library borsh-js to help serialize the arguments.

The address is a base64 encoded string. For more details about the base64 serialization, please check MDN.

The option type is also based on Borsh binary serialization format. For instance, Option<PublicAddress> is serialized as:

const address = 'ggYKJ-RGIfs2YVzAW2W5KV39NpPSUIzabo7m0dSC_Hs'; 
const addressBytes = new TextEncoder().encode(address); // PublicAddress
const optionBytes = new Uint8Array([1, ...addressBytes]); // Option<PublicAddress>

The following example shows how to serialize the arguments:

Assume that you want to call the transfer_from() method of the xXAbY4DmeOHHuRCmE9dXczV38BoO-CTKYeWra8YOlLw PRFC1 contract.

import * as borsh from 'borsh';

// PublicAddress
const fromAddress = 'YChzIE0ZGwKuuJSSVugZ-SlY3RvBzzjjz3__VkftgCY';
// Option<PublicAddress>
const toAddress = 'ggYKJ-RGIfs2YVzAW2W5KV39NpPSUIzabo7m0dSC_Hs'; 
// u64
const value = '0.001'; 

// helper functions for serialization
const base64ToBytes = (text) => new TextEncoder().encode(text);
const option = (bytes) => new Uint8Array([1, ...bytes]);

window.xpll.request({
    method: 'call_contract',
    params: {
        address: 'xXAbY4DmeOHHuRCmE9dXczV38BoO-CTKYeWra8YOlLw',
        method: 'transfer_from',
        args: [
            base64ToBytes(fromAddress),
            option(base64ToBytes(toAddress)),
            borsh.serialize('u64', value),
        ],
    }
});

Sometimes, it's hard to serialize the arguments by yourself. Hence, the Provider provides a handy way to help you with the argument serialization: by passing in the arguments as an array of objects, as seen below.

interface UintArgument {
    type: 'u8' | 'u16' | 'u32' | 'u64' | 'u128';
    value: string | number | bigint;
}

interface IntArgument {
    type: 'i8' | 'i16' | 'i32' | 'i64' | 'i128';
    value: string | number | bigint;
}

interface FloatArgument {
    type: 'f32' | 'f64';
    value: string | number | bigint;
}

interface BoolArgument {
    type: 'bool';
    value: boolean;
}

interface StringArgument {
    type: 'string';
    value: string;
}
interface Base64Argument {
    type: 'base64';
    value: string;
}

type Argument = UintArgument | IntArgument | FloatArgument | BoolArgument | StringArgument | Base64Argument;

The following example shows how to serialize the arguments:

window.xpll.request({
    method: 'call_contract',
    params: {
        address: 'xXAbY4DmeOHHuRCmE9dXczV38BoO-CTKYeWra8YOlLw',
        method: 'transfer_from',
        args: [
            { type: 'base64', value: 'YChzIE0ZGwKuuJSSVugZ-SlY3RvBzzjjz3__VkftgCY' },
            { type: 'base64', value: 'ggYKJ-RGIfs2YVzAW2W5KV39NpPSUIzabo7m0dSC_Hs' },
            { type: 'u64', value: '0.001' }
        ],
    }
});

interface CallContractRequest {
  method: "call_contract";
  params: {
    method: string;
    address: string;
    args: Argument[];
    gas_limit?: string | number | bigint;
    nonce?: string | number | bigint;
    max_base_fee_per_gas?: string | number | bigint;
    priority_fee_per_gas?: string | number | bigint;
  };
}
export type CallContractResult = string; // transaction hash

RPCHelper Function

window.xpll.request({
    method: 'call_contract',
    params: {
        address: 'xXAbY4DmeOHHuRCmE9dXczV38BoO-CTKYeWra8YOlLw',
        method: 'transfer_from',
        args: [
            { type: 'base64', value: 'YChzIE0ZGwKuuJSSVugZ-SlY3RvBzzjjz3__VkftgCY' },
            { type: 'base64', value: 'ggYKJ-RGIfs2YVzAW2W5KV39NpPSUIzabo7m0dSC_Hs' },
            { type: 'u64', value: '0.001' }
        ],
    }
});

window.xpll.callContract({
    address: 'xXAbY4DmeOHHuRCmE9dXczV38BoO-CTKYeWra8YOlLw',
    method: "transfer_from",
    args: [
        { type: 'base64', value: 'YChzIE0ZGwKuuJSSVugZ-SlY3RvBzzjjz3__VkftgCY' },
        { type: 'base64', value: 'ggYKJ-RGIfs2YVzAW2W5KV39NpPSUIzabo7m0dSC_Hs' },
        { type: 'u64', value: '0.001' }
    ],
});

Watch Asset

Allows developers to request a specified asset be tracked in the wallet.

Params

• type: The type string is the commonly accepted name of the interface implemented by the asset’s contract, e.g. PRFC1.
• address: The address of the contract.

Warning

The watch_asset should have permission granted; otherwise, the User Rejected Request 4001 error will be thrown. Please check Permissions for more details.

Warning

The request causes a pop-up to appear. You should only request permissions in response to a direct user action, such as a button click.

Failure

If the user rejects the request, the User Rejected Request 4001 error will be thrown.

interface WatchAssetRequest {
    method: "watch_asset";
    params: {
        type: "PRFC1";
        address: string;
    };
}
type WatchAssetResult = boolean;

RPCHelper Function

window.xpll.request({
    method: 'watch_asset',
    params: {
        type: 'PRFC1',
        address: 'xXAbY4DmeOHHuRCmE9dXczV38BoO-CTKYeWra8YOlLw'
    }
});

window.xpll.watchAsset({
    type: 'PRFC1',
    address: 'xXAbY4DmeOHHuRCmE9dXczV38BoO-CTKYeWra8YOlLw'
});