Astrone Docs

# Ethereum Provider API

Recommended Reading

We recommend that all web3 site developers read the Basic Usage section.

Astrone injects a global API into websites visited by its users at window.astrone. This API allows websites to request users' Ethereum accounts, read data from blockchains the user is connected to, and suggest that the user sign messages and transactions. The presence of the provider object indicates an Ethereum user.

# Table of Contents

# Basic Usage

For any non-trivial Ethereum web application — a.k.a. dapp, web3 site etc. — to work, you will have to:

  • Detect the Ethereum provider (window.astrone)
  • Detect which Ethereum network the user is connected to
  • Get the user's Ethereum account(s)

The snippet at the top of this page is sufficient for detecting the provider. You can learn how to accomplish the other two by reviewing the snippet in the Using the Provider section.

The provider API is all you need to create a full-featured web3 application.

# Chain IDs

These are the IDs of the Ethereum chains that Astrone supports by default. Consult chainid.network (opens new window) for more.

Hex Decimal Network
0x141 321 KCC Mainnet
0x38 56 BSC Mainnet
0x142 322 KCC Testnet
0x61 97 BSC Testnet

# Properties

# astrone.isAstrone

Note

This property is non-standard. Non-Astrone providers may also set this property to true.

true if the user has Astrone installed.

# Methods

# astrone.request(args)

interface RequestArguments {
  method: string;
  data?: object;
}
astrone.request(args: RequestArguments): Promise<unknown>;

Use request to submit RPC requests to Ethereum via Astrone. It returns a Promise that resolves to the result of the RPC method call.

The params and return value will vary by RPC method. In practice, if a method has any params, they are almost always of type Object<any>.

If the request fails for any reason, the Promise will reject with an Ethereum RPC Error.

Astrone supports most standardized Ethereum RPC methods, in addition to a number of methods that may not be supported by other wallets. See the Astrone RPC API documentation for details.

# Example

data: {
  params: {
    from: '0xb60e8dd61c5d32be8058bb8eb970870f07233155',
    to: '0xd46e8dd67c5d32be8058bb8eb970870f07244567',
    gas: '0x76c0', // 30400
    gasPrice: '0x9184e72a000', // 10000000000000
    value: '0x9184e72a', // 2441406250
    data: '0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675',
  },
  type: "approve", // only necessary when approving
}
astrone
  .request({
    method: 'eth_sendTransaction',
    data,
  })
  .then((result) => {
    // The result varies by RPC method.
    // For example, this method will return a transaction hash hexadecimal string on success.
  })
  .catch((error) => {
    // If the request fails, the Promise will reject with an error.
  });

# Events

The Astrone provider implements the Node.js EventEmitter (opens new window) API. This sections details the events emitted via that API. There are innumerable EventEmitter guides elsewhere, but you can listen for events like this:

astrone.on('accountsChanged', (response) => {
  console.log(response.account);
  // Handle the new accounts, or lack thereof.
  // "accounts" will always be an array, but it can be empty.
});
astrone.on('chainChanged', (response) => {
  console.log(response.chainId);
  // Handle the new chain.
  // Correctly handling chain changes can be complicated.
  // We recommend reloading the page unless you have good reason not to.
  window.location.reload();
});

Also, don't forget to remove listeners once you are done listening to them (for example on component unmount in React):

function handleAccountsChanged(accountObj) {
  // ...
}
astrone.on('accountsChanged', handleAccountsChanged);

The first argument of the ethereum.removeListener is the event name and the second argument is the reference to the same function which has passed to ethereum.on for the event name mentioned in the first argument.

# accountsChanged

ethereum.on('accountsChanged', handler: (accountObj: object) => void);

The Astrone provider emits this event whenever the return value of the eth_accounts RPC method changes. eth_accounts returns an array that is either empty or contains a single account address. The returned address, if any, is the address of the most recently used account that the caller is permitted to access. Callers are identified by their URL origin, which means that all sites with the same origin share the same permissions.

This means that accountsChanged will be emitted whenever the user's exposed account address changes.

Tip

We plan to allow the eth_accounts array to be able to contain multiple addresses in the near future.

# chainChanged

Tip

See the Chain IDs section for Astrone's default chains and their chain IDs.

astrone.on('chainChanged', handler: (chainIdObj: object) => void);

The Astrone provider emits this event when the currently connected chain changes.

All RPC requests are submitted to the currently connected chain. Therefore, it's critical to keep track of the current chain ID by listening for this event.

We strongly recommend reloading the page on chain changes, unless you have good reason not to.

astrone.on('chainChanged', (data) => window.location.reload());

# Errors

All errors thrown or returned by the Astrone provider follow this interface:

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

# Legacy API

WARNING

You should never rely on any of these methods, properties, or events in practice.

This section documents our legacy provider API. Astrone only supported this API before the provider API was standardized via EIP-1193 (opens new window) in 2020. Because of this, you may find web3 sites that use this API, or other providers that implement it.

# Legacy Events

# chainIdChanged

WARNING

Use chainChanged instead.

Misspelled alias of chainChanged.

astrone.on('chainChanged', handler: (chainIdObj: object) => void);

← RPC API →