Guide
Getting Started
To develop for O3-desktop, install O3-desktop on your development machine
What is the dAPI?
The dAPI is a package interface for communicating with the ETH blockchain. The methods are handled by an existing wallet provider, such as the O3 wallet, and help to reduce the development overhead associated with creating dApps on ETH.
By offloading the responsibility of ETH blockchain interactions to a wallet provider, dApp developers do no have to worry about managing users private keys or how to format transactions to be signed and broadcast. The developer no long has to worry about user onboarding flows related to creating and managing a users secure credentials, and can just focus on the development of their core dApp.
On the user side, since all transactions that a dApp needs to broadcast to the blockchain will be handled by the users wallet proivder, they can feel safe knowing that they never need to copy and paste their private key into a dApp again. Any transaction that a user signs will be done so in the wallet, and their private key will never be provided to the dApp.
Installation
dAPI client integrations are currently facilited via a versioned JS package, and can be imported to your application either via CDN or NPM.
Install via CDN
<script src="https://cdn.jsdelivr.net/npm/o3-dapi-core@0.3.13/lib/o3-dapi-core.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/o3-dapi-eth@1.1.0/lib/o3-dapi-eth.min.js"></script>
window.initPlugins([o3DapiETH['ETH']]);
or
window.initPlugins([o3DapiETH['BSC']]);
or
window.initPlugins([o3DapiETH['HECO']]);
Install via NPM
npm i --save o3-dapi-eth
or
yarn add o3-dapi-eth
import o3dapi from 'o3-dapi-core';
import o3DapiETH from 'o3-dapi-eth';
or
var o3dapi = require('o3-dapi-core');
var o3DapiETH = require('o3-dapi-eth');
o3dapi.initPlugins([o3DapiETH]);
Example Response
import o3dapi from 'o3-dapi-core';
import o3DapiETH from 'o3-dapi-eth';
or
var o3dapi = require('o3-dapi-core');
var o3DapiETH = require('o3-dapi-eth');
o3dapi.initPlugins([o3DapiETH]);
o3dapi.ETH.request({method: 'eth_chainId', params: []}).then((res) => {}).catch((err) => {});
dAPI Testbed
After you deploy your smart contract, and would like to start building the interface to call your smart contract from your dApp, you can start by using the dAPI Testbed @ ethdapitestbed.o3.app. This is a free open source testbed which allows you to quickly explore all the different methods on the dAPI. It can make all the same calls related to getting a user address, getting asset balances, and even transferring assets. However, one of the most important features of this testbed is that it allows you to test out your smart contract code by invoking it via the dAPI.
API Methods
Read Methods
Read methods do not alter the state of the blockchain. It can help you query information about your user, and provide you with relevant information:
eth_chainId
o3dapi.ETH.request({ method: "eth_chainId", params: [] })
.then((res) => {})
.catch((err) => {});
Example Response
{
"id": 1,
"jsonrpc": "2.0",
"result": "0x1"
}
net_version
Returns the current network id.
o3dapi.ETH.request({ method: "net_version", params: [] })
.then((res) => {})
.catch((err) => {});
Example Response
{
"id": 1,
"jsonrpc": "2.0",
"result": "1"
}
Parameters
none
Returns
String
- The current network id.
"1"
: Ethereum Mainnet
eth_accounts
Returns of addresses owned by client.
o3dapi.ETH.request({ method: "eth_accounts", params: [] })
.then((res) => {})
.catch((err) => {});
Example Response
{
"id": 1,
"jsonrpc": "2.0",
"result": [
"0x54715A7ab13692b268Eb12334E98e0DA891a86d0"
]
}
Parameters
none
Returns
Array of DATA
,20 Bytes - addresses owned by the client.
eth_requestAccounts
Returns of addresses owned by client.
o3dapi.ETH.request({ method: "eth_requestAccounts", params: [] })
.then((res) => {})
.catch((err) => {});
Example Response
{
"id": 1,
"jsonrpc": "2.0",
"result": [
"0x54715A7ab13692b268Eb12334E98e0DA891a86d0"
]
}
Parameters
none
Returns
Array of DATA
,20 Bytes - addresses owned by the client.
eth_blockNumber
Returns the number of most recent block.
o3dapi.ETH.request({ method: "eth_blockNumber", params: [] })
.then((res) => {})
.catch((err) => {});
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0xb3f5db"
}
Parameters
none
Returns
QUANTITY
- integer of the current block number the client is on.
eth_call
Executes a new message call immediately without creating a transaction on the block chain.
let params = [
{
to: "0xdaaf96c344f63131acadd0ea35170e7892d3dfba", // account address
data:
"0xbc1c58d11d9964670435ad8ded3a5abba251ed340cb01fce690794b9dc35627fdac55fb0",
},
"latest",
];
o3dapi.ETH.request({ method: "eth_sendTransaction", params: params })
.then((txid) => {
console.log(txid);
})
.catch((err) => {});
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000026e3010170122094c398198b191d52219591e891c88fff49b6c613b20d89164e66045dcca5d0ad0000000000000000000000000000000000000000000000000000"
}
Parameters
1.Object
- The transaction call object
Parameter | Type | Description |
---|---|---|
from | String | TDATA, 20 Bytes - The address the transaction is send from. |
to | String | DATA, 20 Bytes - (optional when creating new contract) The address the transaction is directed to. |
gas | String | QUANTITY - (optional, default: 90000) Integer of the gas provided for the transaction execution. It will return unused gas. |
gasPrice | String | QUANTITY - (optional, default: To-Be-Determined) Integer of the gasPrice used for each paid gas |
value | String | QUANTITY - (optional) Integer of the value sent with this transaction |
data | String | DATA - The compiled code of a contract OR the hash of the invoked method signature and encoded parameters. |
nonce | String | QUANTITY-(optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce. |
2.QUANTITY|TAG
- integer block number, or the string "latest"
, "earliest"
or "pending"
.
eth_estimateGas
Generates and returns an estimate of how much gas is necessary to allow the transaction to complete. The transaction will not be added to the blockchain. Note that the estimate may be significantly more than the amount of gas actually used by the transaction, for a variety of reasons including EVM mechanics and node performance.
const params = [
{
from: "0x54715A7ab13692b268Eb12334E98e0DA891a86d0",
to: "0xdF704A67Fc56F0D7CFA147548Ee4C115921D2ba3",
value: "0x3211",
},
"latest",
];
o3dapi.ETH.request({ method: "eth_estimateGas", params: params })
.then((res) => {})
.catch((err) => {});
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x5208"
}
Parameters
1.Object
- The transaction call object.
Parameter | Type | Description |
---|---|---|
from | String | DATA, 20 Bytes - The address the transaction is send from. |
to | String | DATA, 20 Bytes - (optional when creating new contract) The address the transaction is directed to. |
gas | String | QUANTITY - (optional, default: 90000) Integer of the gas provided for the transaction execution. It will return unused gas. |
gasPrice | String | QUANTITY - (optional, default: To-Be-Determined) Integer of the gasPrice used for each paid gas |
value | String | QUANTITY - (optional) Integer of the value sent with this transaction |
data | String | DATA - The compiled code of a contract OR the hash of the invoked method signature and encoded parameters. |
nonce | String | QUANTITY-(optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce. |
2.QUANTITY|TAG
- integer block number, or the string "latest"
, "earliest"
or "pending"
.
Returns
DATA
- the return value of executed contract.
eth_getBalance
Parameter | Type | Description |
---|---|---|
DATA | String | DATA, 20 Bytes - address to check for balance. |
QUANTITY | TAG | String |
o3dapi.ETH.request({ method: "eth_getBalance", params: [
"0x54715A7ab13692b268Eb12334E98e0DA891a86d0",
"latest"]
})
.then((res) => {})
.catch((err) => {});
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x5c7277d40a532"
}
Returns the current price per gas in wei.
eth_gasPrice
o3dapi.ETH.request({ method: "eth_gasPrice", params: [] })
.then((res) => {})
.catch((err) => {});
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x5208"
}
Returns integer of the current balance in wei.
Parameters
none
Returns
QUANTITY
- integer of the current gas price in wei.
eth_getTransactionReceipt
Returns the receipt of a transaction by transaction hash. Note That the receipt is not available for pending transactions.
Parameters
1.DATA
, 32 Bytes - hash of a transaction
Returns
const params = [
"0x4383f1bc48657782998bd8d44e24bdbe8f2431346cd69dde73aec2188288ae06",
];
o3dapi.ETH.request({ method: "eth_getTransactionReceipt", params: params })
.then((res) => {})
.catch((err) => {});
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"blockHash": "0xe0eb08b52feaecd7c33c36a033f3111a28b3ab1114ceaeadffb034a9745f5d96",
"blockNumber": "0xb247e6",
"contractAddress": null,
"cumulativeGasUsed": "0xa1a968",
"from": "0xd34e3b073a484823058ab76fc2304d5394beafe4",
"gasUsed": "0x5208",
"logs": [],
"logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"status": "0x1",
"to": "0x54715a7ab13692b268eb12334e98e0da891a86d0",
"transactionHash": "0x4383f1bc48657782998bd8d44e24bdbe8f2431346cd69dde73aec2188288ae06",
"transactionIndex": "0x8a"
}
}
Object
- A transaction receipt object, or null
when no receipt was found:
Parameter | Type | Description |
---|---|---|
transactionHash | DATA |
2 Bytes - hash of the transaction. |
transactionIndex | QUANTITY |
integer of the transactions index position in the block. |
blockHash | DATA |
32 Bytes - hash of the block where this transaction was in. |
blockNumber | QUANTITY |
block number where this transaction was in. |
from | DATA |
20 Bytes - address of the sender. |
to | DATA |
20 Bytes - address of the receiver. null when its a contract creation transaction. |
cumulativeGasUsed | QUANTITY |
The total amount of gas used when this transaction was executed in the block. |
gasUsed | QUANTITY |
The amount of gas used by this specific transaction alone. |
contractAddress | DATA |
20 Bytes - The contract address created, if the transaction was a contract creation, otherwise null . |
logs | Array |
Array of log objects, which this transaction generated. |
logsBloom | DATA |
256 Bytes - Bloom filter for light clients to quickly retrieve related logs. |
cumulativeGasUsed | QUANTITY |
The total amount of gas used when this transaction was executed in the block. |
It also returns either :
Parameter | Type | Description |
---|---|---|
root | DATA |
32 bytes of post-transaction stateroot (pre Byzantium) |
status | QUANTITY |
either 1 (success) or 0 (failure) |
Write Methods
eth_sendTransaction
Creates new message call transaction or a contract creation, if the data field contains code.
let params = {
"from": "0xd34E3B073a484823058Ab76fc2304D5394beafE4",
"to": "0xdF704A67Fc56F0D7CFA147548Ee4C115921D2ba3",
"gas": "0x15f90", // 90000
"gasPrice": "0x32", // 50
// "value": "0x9184e72a", // 2441406250
"data": "0xa9059cbb00000000000000000000000054715A7ab13692b268Eb12334E98e0DA891a86d000000000000000000000000000000000000000000000000000000000000186a0"
"nonce": "0x1"
}
o3dapi.ETH.request({method: 'eth_sendTransaction', params: params}).then(res => {}).catch((err) => {});
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x0676cae6b9d2838ad19574d4106262a21e0231ab0c3087d27255cdcdbf785056"
}
Input Arguments
Parameter | Type | Description |
---|---|---|
from | String | TDATA, 20 Bytes - The address the transaction is send from. |
to | String | DATA, 20 Bytes - (optional when creating new contract) The address the transaction is directed to. |
gas | String | QUANTITY - (optional, default: 90000) Integer of the gas provided for the transaction execution. It will return unused gas. |
gasPrice | String | QUANTITY - (optional, default: To-Be-Determined) Integer of the gasPrice used for each paid gas |
value | String | QUANTITY - (optional) Integer of the value sent with this transaction |
data | String | DATA - The compiled code of a contract OR the hash of the invoked method signature and encoded parameters. |
nonce | String | QUANTITY-(optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce. |
eth_sendRawTransaction
Creates new message call transaction or a contract creation, if the data field contains code.
let params = {
from: "0xd34E3B073a484823058Ab76fc2304D5394beafE4",
to: "0xdF704A67Fc56F0D7CFA147548Ee4C115921D2ba3",
gas: "0x15f90", // 90000
gasPrice: "0x32", // 50
value: "0x9184e72a", // 2441406250
// "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"
};
o3dapi.ETH.request({ method: "eth_sendTransaction", params: params })
.then((txid) => {})
.catch((err) => {});
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x0676cae6b9d2838ad19574d4106262a21e0231ab0c3087d27255cdcdbf785056"
}
Input Arguments
Parameter | Type | Description |
---|---|---|
from | String | TDATA, 20 Bytes - The address the transaction is send from. |
to | String | DATA, 20 Bytes - (optional when creating new contract) The address the transaction is directed to. |
gas | String | QUANTITY - (optional, default: 90000) Integer of the gas provided for the transaction execution. It will return unused gas. |
gasPrice | String | QUANTITY - (optional, default: To-Be-Determined) Integer of the gasPrice used for each paid gas |
value | String | QUANTITY - (optional) Integer of the value sent with this transaction |
data | String | DATA - The compiled code of a contract OR the hash of the invoked method signature and encoded parameters. |
nonce | String | QUANTITY-(optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce. |
Event Methods
addEventListener
o3dapi.ETH.addEventListener(
o3dapi.ETH.Constants.EventName.CONNECTED,
(data) => {
console.log(`Connected Account: ${data}`);
}
);
Method is used to add a callback method to be triggered on a specified event.
removeEventListener
o3dapi.ETH.removeEventListener(o3dapi.ETH.Constants.EventName.CONNECTED);
Method is to remove existing callback event listeners.
Events
Events are a way for the wallet to asynchronously with the DAPP when certain changes occur to the state of the wallet that might be relevant for the
READY
On a READY event, the callback will fire with a single argument with information about the wallet provider. At any time a READY event listener is added, it will immidiately be called if the provider is already in a ready state. This provides a single flow for dapp developers since this listener should start any and all interactions with the dapi protocol.
Parameter | Type | Description |
---|---|---|
name | String | The name of the wallet provider |
website | String | The website of the wallet provider |
version | String | The version of the dAPI that the the wallet supports |
compatibility | String[] | A list of all applicable NEPs which the wallet provider supports |
extra | Object | Provider specific attributes |
CONNECTED
On a CONNECTED event, the user has approved the connection of the dapp with one of their accounts.
Example Response
{
"id": 1,
"jsonrpc": "2.0",
"result": [
"0x54715A7ab13692b268Eb12334E98e0DA891a86d0"
]
}
DISCONNECTED
On a DISCONNECTED event, the account connected to the dapp via the dapi provider has been disconnected (logged out).
NETWORK_CHANGED
On a NETWORK_CHANGED event, the user has changed the network their provider wallet is connected to. The event will return the updated network details.
Parameter | Type | Description |
---|---|---|
networks | String[] | A list of all networks which this wallet provider allows access to |
defaultNetwork | String | Network the wallet is currently set to |
ETH_BLOCK_HEIGHT_CHANGED
On a ETH_BLOCK_HEIGHT_CHANGED event, the block has advanced to the next.
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0xb3f5db"
}
Errors
All errors thrown or returned by the MetaMask provider follow this interface:
interface ProviderRpcError extends Error {
message: string;
code: number;
data?: unknown;
}
Error Type | Meaning |
---|---|
4001 | The request was rejected by the user |
-32602 | The parameters were invalid |
-32603 | Internal error |