This document describes API for dApps on Neo blockchain.
When using Neo dAPI, a suitable Neo Provider is required. The definition of Neo Provider can be found here.
This library is written in TypeScript, so all the methods and objects are typed. It is therefore usable in TypeScript projects as well as vanilla JavaScript projects.
This library can be used as CommonJS/ES module or directly referenced in web page html.
npm install @neongd/neo-dapior
yarn add @neongd/neo-dapior
pnpm add @neongd/neo-dapiconst BaseDapi = require('@neongd/neo-dapi').BaseDapi;import { BaseDapi } from '@neongd/neo-dapi';The index.js file under the "/dist/umd" folder needs to be referenced from the page:
<script src="./dist/umd/index.js"></script>The use of the code is required under the global namespace of neoDapi.
const Dapi = neoDapi.BaseDapi;Create a Neo dAPI instance, assuming we already have a Neo Provider (e.g., window.neo, window.OneGate):
const dapi = new BaseDapi(window.neo);Examples of usage can be found in test directory.
Gets information about the provider, including the provider, the provider version, and the NEPs that the provider is compatible with.
(none)
Provider - a provider object with the following properties:
name: string- the provider namewebsite: string- the provider websiteversion: string- the provider versiondapiVersion: string- the dapi version used by the providercompatibility: string[]- a list of all the NEPs supported by the providerextra: object- this object can contain any attributes specific to the provider, such as an app theme
/* Example */
const provider = await dapi.getProvider();
/* Example Response */
({
name: 'Awesome Wallet',
website: 'https://awesome-wallet.org',
version: '1.0.0',
dapiVersion: '1.0.0',
compatibility: ['NEP-11', 'NEP-17'],
extra: {
theme: 'Dark Mode',
currency: 'USD',
},
});Gets the networks the provider is available to connect to, along with the default network the provider is currently set to.
(none)
Networks - a networks object with the following properties:
networks: string[]- array of network names to which the provider is available to connect for the dApp developersdefaultNetwork: string- the network the provider connects to by default
/* Example */
const networks = await dapi.getNetworks();
/* Example Response */
({
networks: ['MainNet', 'TestNet'],
defaultNetwork: 'TestNet',
});Gets the account that is currently connected to the dApp.
(none)
Account - an account object with the following properties:
address: string- address of the connected accountpublicKey: string- public key of the connected accountlabel?: string- a label set by user to identify their account
/* Example */
const account = await dapi.getAccount();
/* Example Response */
({
address: 'NXufgyw4AAST8tkLqZ5AtFKErjPzPEwnQp',
publicKey: '0267c8a9872df89d8da5bcb5ae6a30966495bbd6721d2a68d37ba2b842ea09b4c6',
label: 'My Account',
});Gets the block count of the blockchain.
object - an object with the following parameter:
network?: string- network to submit this request to. If omitted, the default network set to the provider is used
number - block count of the target network
/* Example */
const count = await dapi.getBlockCount({});
/* Example Response */
26537;Gets information about a specific block.
object - an object with the following members:
blockIndex: number- index of the block to get information aboutnetwork?: string- network to submit this request to. If omitted, the default network set to the provider is used
Block - a block object (See the type definitions here)
/* Example */
const block = await dapi.getBlock({ blockIndex: 26536 });
/* Example Response */
({
hash: '0xd373a9afdbe57d79ad788196aa4ef37dbfb28c7d8f22ffa1ccbc236d56268bca',
size: 5317,
version: 0,
previousBlockHash: '0x2f384bc40c608333fa9d67179d276381dea3dff33b11cfad8ae6a3b2afa15dce',
merkleRoot: '0xefd4080cb996b8d44dcc313d207a5adb7ed614488a0d636bbfe9d37d157c8e9b',
time: 1615348136186,
index: 26536,
primary: 6,
nextConsensus: 'NiY2NJTPFPyqjrGtdEhQnryJpJbxnQTvpR',
witnesses: [
{
invocation:
'DEA2ZR0uduwN/5tFVCKoHJtAnSJINfqlRDcNXnYl0H0Jcb3YBy1M0G4Z1LB3PQMIb6J4kOtFm7TBL0B6vfPuDpigDEBLHKna+SPlL9vn755blCr3vxvc2HLP5dUch0isPARVDbg24QwVuvx3mbQ6awn0cQ/h+Jym/9xFo0MR0ddKXKzCDEAIcXyoqzFq4+3N9JtyK46LLeyx9ikidPLiXg9HWQk9Ps5wx9+XIe8zziS9dRAOqT4od7tW1SA6cRU3U8ZCexJ1DECxN+nyE15RaIvwpJ0JK3/RJvAM++YKou/ljVef5atDx9pce5nkuibfZzvzrjcoJF53qnP8ZSXBKThjrN2kGCxlDEBSVfUQAFNm4j4KihACjt5Kx1A9hN8RIDQkLw7udpcFm7Nf4PtDtucw7pS7WGEkmu3c+yt2BV3KeCzNBAreypb7',
verification:
'FQwhAwIkKx3O1j4b9+sUh29+8Ca3lWf5xb6D3hlD3Rhewo5oDCECDfiFi2b/TXsKamjRHd7cx9kNKmT/os0IfExdq/QVC0AMIQIXlUMAAYR4HlRHs/D7rOZk6pK34xInyOcbxOfNr8zbjgwhAl6ElJA7k9w2nwiivX4iH1dMddlnVZHwSQfLqdruuD0QDCEDhBXQvo3BK2HT47drmPRk36t/3e50Jxw14t5iS7UQI6YMIQPJscicbi1KvWKaLbi30DrO1RilZ5O8kPSYXvftPxtIGgwhA+irUYbh3qvNEOwOUJ3tT/+t5v3fU0rD4FBiaLrj/USmF0F7zmyl',
},
],
tx: [],
confirmations: 50,
nextBlockHash: '0x568b1d99c5abd460e4a05230d2a70bc7fd432b9f372354076eacd3b9f5cd399e',
});Gets the information about a specific transaction.
object - an object with the following properties:
txid: string- transaction ID of the transaction to get information aboutnetwork?: string- network to submit this request to. If omitted, the default network set to the provider is used
Transaction - a transaction object (See the type definitions here)
/* Example */
const count = await dapi.getTransaction({
txid: '0x7da6ae7ff9d0b7af3d32f3a2feb2aa96c2a27ef8b651f9a132cfaad6ef20724c',
});
/* Example Response */
({
hash: '0x7da6ae7ff9d0b7af3d32f3a2feb2aa96c2a27ef8b651f9a132cfaad6ef20724c',
size: 386,
version: 0,
nonce: 246876555,
sender: 'NikhQp1aAD1YFCiwknhM5LQQebj4464bCJ',
systemFee: '9999540',
networkFee: '2353160',
validUntilBlock: 5899,
signers: [
{
account: '0xebae4ab3f21765e5f604dfdd590fdf142cfb89fa',
scopes: 'None',
},
{
account: '0x86df72a6b4ab5335d506294f9ce993722253b6e2',
scopes: 'CalledByEntry',
},
],
attributes: [],
script:
'CwMA5AtUAgAAAAwU+on7LBTfD1nd3wT25WUX8rNKrusMFOK2UyJyk+mcTykG1TVTq7Smct+GFMAfDAh0cmFuc2ZlcgwUKLOtq3Jp+cIYHbPLdB6/VRkw4nBBYn1bUjk=',
witnesses: [
{
invocation:
'DEC31ZE1kiIFPan7qal/h9FYsD2LTk6Lf0m0Kbbh1GExUqTAfye7BDjyEylfR50/AVNQkr+g+jXXMHGcxF4MUYBQ',
verification: 'DCECztQyOX3cRO26AxwLw7kz8o/dlnd5LXsg5sA23aqs8eILQZVEDXg=',
},
{
invocation:
'DED8PagPv03pnEbsxUY7XgFk/qniHcha36hDCzZsmaJkpFg5vbgxk5+QE46K0GFsNpsqDJHNToGD9jeXsPzSvD5T',
verification: 'EQwhAs7UMjl93ETtugMcC8O5M/KP3ZZ3eS17IObANt2qrPHiEQtBE43vrw==',
},
],
blockHash: '0x3d87f53c51c93fc08e5ccc09dbd9e21fcfad4dbea66af454bed334824a90262c',
confirmations: 26,
blockTime: 1612687482881,
});Gets the application log for a given transaction.
object - an object with the following properties:
txid: string- transaction ID of the transaction to get application log fornetwork?: string- network to submit this request to. If omitted, the default network set to the provider is used
ApplicationLog - an application log object (See the type definitions here)
/* Example */
const applicationLog = await dapi.getApplicationLog({
txid: '0x7da6ae7ff9d0b7af3d32f3a2feb2aa96c2a27ef8b651f9a132cfaad6ef20724c',
});
/* Example Response */
({
txid: '0x7da6ae7ff9d0b7af3d32f3a2feb2aa96c2a27ef8b651f9a132cfaad6ef20724c',
executions: [
{
trigger: 'Application',
vmState: 'HALT',
exception: null,
gasConsumed: '9999540',
stack: [],
notifications: [
{
contract: '0x70e2301955bf1e74cbb31d18c2f96972abadb328',
eventName: 'Transfer',
state: {
type: 'Array',
value: [
{
type: 'ByteString',
value: '4rZTInKT6ZxPKQbVNVOrtKZy34Y=',
},
{
type: 'ByteString',
value: '+on7LBTfD1nd3wT25WUX8rNKrus=',
},
{
type: 'Integer',
value: '10000000000',
},
],
},
},
],
},
],
});Gets all NEP17 asset balances in the given account.
object - an object with the following properties:
address: string- address to check the balancenetwork?: string- network to submit this request to. If omitted, the default network set to the provider is used.
Nep17Balance[] - array of the Nep17 balance object with the following properties:
assetHash: string- NEP17 asset hashamount: string- Integer value of the balance, represented as a String
/* Example */
const balances = await dapi.getNep17Balances({
address: 'NXufgyw4AAST8tkLqZ5AtFKErjPzPEwnQp',
});
/* Example Response */
[
{
assetHash: '0xd2a4cff31913016155e38e474a2c06d08be276cf',
amount: '10000000',
},
];Executes a contract invocation in read-only mode.
object - an object with the following properties:
scriptHash: string- script hash of the smart contract to invokeoperation: string- operation on the smart contract to callargs?: Argument[]- any input arguments for the operationsigners?: Signer[]- sender and the scope of the signature. Read more about signers herenetwork?: string- network to submit this request to. If omitted, the default network set to the provider is used
object - an object with the following properties:
script: string- the script which was runstate: string- status of the invocationexception: null | string- error message of the invocationgasConsumed: string- estimated amount of GAS to be used to execute the invocationstack: Argument[]- an array of response arguments
/* Example */
const result = await dapi.invokeRead({
scriptHash: '0xf61eebf573ea36593fd43aa150c055ad7906ab83',
operation: 'transfer',
args: [
{ type: 'Hash160', value: '0x86df72a6b4ab5335d506294f9ce993722253b6e2' },
{ type: 'Hash160', value: '0xebae4ab3f21765e5f604dfdd590fdf142cfb89fa' },
{ type: 'Integer', value: '10000' },
{ type: 'String', value: '' },
],
signers: [
{
account: '0x86df72a6b4ab5335d506294f9ce993722253b6e2',
scopes: 'CalledByEntry',
allowedContracts: [],
allowedGroups: [],
},
],
});
/* Example Response */
({
script:
'DAABECcMFPqJ+ywU3w9Z3d8E9uVlF/KzSq7rDBTitlMicpPpnE8pBtU1U6u0pnLfhhTAHwwIdHJhbnNmZXIMFIOrBnmtVcBQoTrUP1k26nP16x72QWJ9W1I=',
state: 'HALT',
gasConsumed: '999972',
exception: null,
stack: [
{
type: 'Boolean',
value: true,
},
],
});Same as invokeRead, but it allows to execute multiple read-only invocations in one request.
object - an object with the following properties:
invocations: Invocation[]- array of invocation object with following members:scriptHash: string- script hash of the smart contract to invokeoperation: string- operation on the smart contract to callargs?: Argument[]- any input arguments for the operation
signers?: Signer[]- sender and the scope of the signature. Read more about signers herenetwork?: string- network to submit this request to. If omitted, the default network set to the provider is used
object - an object with the following properties:
script: string- the script which was runstate: string- status of the invocationexception: null | string- error message of the invocationgasConsumed: string- estimated amount of GAS to be used to execute the invocationstack: Argument[]- an array of response arguments
/* Example */
const result = await dapi.invokeReadMulti({
invocations: [
{
scriptHash: '0xf61eebf573ea36593fd43aa150c055ad7906ab83',
operation: 'transfer',
args: [
{
type: 'Hash160',
value: '0x86df72a6b4ab5335d506294f9ce993722253b6e2',
},
{
type: 'Hash160',
value: '0xebae4ab3f21765e5f604dfdd590fdf142cfb89fa',
},
{ type: 'Integer', value: '10000' },
{ type: 'String', value: '' },
],
},
],
signers: [
{
account: '0x86df72a6b4ab5335d506294f9ce993722253b6e2',
scopes: 'CalledByEntry',
allowedContracts: [],
allowedGroups: [],
},
],
});
/* Example Response */
({
script:
'DAABECcMFPqJ+ywU3w9Z3d8E9uVlF/KzSq7rDBTitlMicpPpnE8pBtU1U6u0pnLfhhTAHwwIdHJhbnNmZXIMFIOrBnmtVcBQoTrUP1k26nP16x72QWJ9W1I=',
state: 'HALT',
gasConsumed: '999972',
exception: null,
stack: [
{
type: 'Boolean',
value: true,
},
],
});Executes a contract invocation that requires a user's signature.
object - an object with the following properties:
scriptHash: string- script hash of the smart contract to invokeoperation: string- operation on the smart contract to callargs?: Argument[]- any input arguments for the operationattributes?: Attribute[]- adds attributes for the transactionsigners?: Signer[]- sender and the scope of signature. Read more about signers herenetwork?: string- network to submit this request to. If omitted, the default network set to the provider is usedextraSystemFee?: string- this fee will be added to system fee (Integer Value represented as a String)extraNetworkFee?: string- this fee will be added to network fee (Integer Value represented as a String)broadcastOverride?: boolean- in the case that the dApp would like to be responsible for broadcasting the signed transaction rather than the provider
object - an object with the following properties:
txid: string- transaction ID of the invocationnodeUrl?: string- the node which the transaction was broadcast to. Returned if transaction is broadcasted by the providersignedTx?: string- serialized signed transaction. Returned if the broadcastOverride input argument was set to true
/* Example */
const result = await dapi.invoke({
scriptHash: '0xf61eebf573ea36593fd43aa150c055ad7906ab83',
operation: 'transfer',
args: [
{ type: 'Hash160', value: '0x86df72a6b4ab5335d506294f9ce993722253b6e2' },
{ type: 'Hash160', value: '0xebae4ab3f21765e5f604dfdd590fdf142cfb89fa' },
{ type: 'Integer', value: '10000' },
{ type: 'String', value: '' },
],
signers: [
{
account: '0x86df72a6b4ab5335d506294f9ce993722253b6e2',
scopes: 'CalledByEntry',
allowedContracts: [],
allowedGroups: [],
},
],
});
/* Example Response */
({
txid: '0xd6e4edeb66a75b79bec526d14664017eef9ccee5650c32facb1a4d4fe3640808',
nodeUrl: 'https://n3seed2.ngd.network:10332',
});Same as invoke, but allows to execute multiple invocations in one transaction.
object - an object with the following properties:
invocations: Invocation[]- array of invocation object with the following properties:scriptHash: string- script hash of the smart contract to invokeoperation: string- operation on the smart contract to callargs?: Argument[]- any input arguments for the operation
attributes?: Attribute[]- adds attributes to the transactionsigners?: Signer[]- sender and the scope of signature. Read more about signers herenetwork?: string- network to submit this request to. If omitted, the default network set the provider is usedextraSystemFee?: string- this fee will be added to system fee (Integer Value represented as a String)extraNetworkFee?: string- this fee will be added to network fee (Integer Value represented as a String)broadcastOverride?: boolean- in the case that the dApp would like to be responsible for broadcasting the signed transaction rather than the provider
object - an object with the following properties:
txid: string- transaction ID of the invocationsnodeUrl?: string- the node that the transaction was broadcast to. Returned if the transaction is broadcasted by the providersignedTx?: string- serialized signed transaction. Returned if the broadcastOverride input argument was set to true
/* Example */
const result = await dapi.invokeMulti({
invocations: [
{
scriptHash: '0xf61eebf573ea36593fd43aa150c055ad7906ab83',
operation: 'transfer',
args: [
{
type: 'Hash160',
value: '0x86df72a6b4ab5335d506294f9ce993722253b6e2',
},
{
type: 'Hash160',
value: '0xebae4ab3f21765e5f604dfdd590fdf142cfb89fa',
},
{ type: 'Integer', value: '10000' },
{ type: 'String', value: '' },
],
},
],
signers: [
{
account: '0x86df72a6b4ab5335d506294f9ce993722253b6e2',
scopes: 'CalledByEntry',
allowedContracts: [],
allowedGroups: [],
},
],
});
/* Example Response */
({
txid: '0xd6e4edeb66a75b79bec526d14664017eef9ccee5650c32facb1a4d4fe3640808',
nodeUrl: 'https://n3seed2.ngd.network:10332',
});Signs a provided message with an account selected by user.
object - an object with the following properties:
message: string- the message to sign
object - an object with the following properties:
salt: string- salt added to the input string before signingsignature: string- signed resultpublicKey: string- public key of the account signed the message
/* Example */
const result = await dapi.signMessage({
message: 'Hello world!',
});
/* Example Response */
({
salt: 'b3085013f5edcffe089c029a98794dab',
signature:
'2953200f24dfa8730302906d752cd33f135020f84828ad4f5d39e3563161029716369fdbec7e4cc9aa03dfd2e665f4ce37f149addccc8e336fdf707a5eba4d16',
publicKey: '031fe37e66cd2d6d711bad2b2fd40fabf2acce4def456ced62fc5ba445acb6f27c',
});Signs a provided message with an account selected by user. This method does not add a random salt as prefix.
object - an object with the following properties:
message: string- the message to sign
object - an object with the following properties:
signature: string- signed resultpublicKey: string- public key of the account signed the message
/* Example */
const result = await dapi.signMessageWithoutSalt({
message: 'Hello world!',
});
/* Example Response */
({
signature:
'2953200f24dfa8730302906d752cd33f135020f84828ad4f5d39e3563161029716369fdbec7e4cc9aa03dfd2e665f4ce37f149addccc8e336fdf707a5eba4d16',
publicKey: '031fe37e66cd2d6d711bad2b2fd40fabf2acce4def456ced62fc5ba445acb6f27c',
});Signs a provided transaction with an account selected by user.
object - an object with the following properties:
version: number- transaction version, currently 0nonce: number- random numbersystemFee: string- system fee paid for network resourcenetworkFee: string- network fee paid for the validator packaging transactionsvalidUntilBlock: number- transaction validity periodscript: string- script executed on the NeoVMinvocations?: Invocation[]- the invocations corresponding to script. If omitted, the provider will display a warning to user, because script is not read-friendlyattributes?: Attribute[]- adds attributes to the transactionsigners?: Signer[]- sender and the scope of signature. Read more about signers herenetwork?: string- network to submit this request to. If omitted, the default network set the provider is used
object - an object with the following properties:
signature: string- signed resultpublicKey: string- public key of the account signed the transaction
/* Example */
const result = await dapi.signTransaction({
version: 0,
nonce: 2204045078,
systemFee: '2338018',
networkFee: '323456',
validUntilBlock: 1688607,
script:
'0c148b9391801e7e795f2063c356ecfd462bb0dab8000c0b646564656275672e6e656f12c01f0c0873657441646d696e0c141a89d48d89f8c1a66d3d3d0ef4832cebcea92f1541627d5b52',
signers: [
{
account: '0x69ee19eba1d8f7b43ad64aeaafb64c2939c9baad',
scopes: 'CalledByEntry',
},
{
account: '0x00b8dab02b46fdec56c363205f797e1e8091938b',
scopes: 'CalledByEntry',
},
],
attributes: [],
invocations: [
{
scriptHash: '0x152fa9ceeb2c83f40e3d3d6da6c1f8898dd4891a',
operation: 'setAdmin',
args: [
{
type: 'String',
value: 'dedebug.neo',
},
{
type: 'Hash160',
value: '0x00b8dab02b46fdec56c363205f797e1e8091938b',
},
],
},
],
});
/* Example Response */
({
signature:
'0ca24f47ec6221e283532d0f623f5f8416f638ffd4b9eaba517019933b89893f169d23cf00013443e226d6ce63d28908d5be1addf935349b340a4ff9eae73a27',
publicKey: '031fe37e66cd2d6d711bad2b2fd40fabf2acce4def456ced62fc5ba445acb6f27c',
});Broadcasts a serialized signed transaction to the network.
object - an object with the following properties:
signedTx: string- the signed transaction to broadcastnetwork?: string- network to submit this request to. If omitted, the default network set the provider is used
object - an object with the following properties:
txid: string- transaction ID of the transactionnodeUrl: string- the node that the transaction was broadcast to
/* Example */
const result = await dapi.broadcastTransaction({
signedTx:
'AEG4RerXn0UAAAAAAIPdCwAAAAAA/tMkAAI85lDDWBenYOF3/1box7mlLLdT7AGLUH0kAMoqaP0rMEv2rQ0xrWg+hgEASgwKc0Vid2VWU3ZBcgwUi1B9JADKKmj9KzBL9q0NMa1oPoYSwB8MCG1pbnRVbml2DBS0S9Spjsr+prUeSDg9hC031DhiTkFifVtSAgAAQgxAxFTXpq6kTcPrWvzVcmaWa348mYfNYpjCk6AItQMgH1X0fGDiSbb1JX5NzWji0IHPSsFbsGyqkQOUu7iA+hFLRCgMIQMf435mzS1tcRutKy/UD6vyrM5N70Vs7WL8W6RFrLbyfEFW57Mn',
});
/* Example Response */
({
txid: '0xf1d546c55aade2f25110cfd73b063019d241c69bac289870ec514cb648a4908e',
nodeUrl: 'https://n3seed2.ngd.network:10332',
});Events related functions are provided by Neo Provider.
The errors thrown by the dAPI methods have a code member and descriptive message member. The following list contains all possible error codes and associated messages:
| Code | Message | Description |
|---|---|---|
| -32700 | Parse error | Invalid JSON |
| -32600 | Invalid request | JSON is not a valid request object |
| -32601 | Method not found | Method does not exist |
| -32602 | Invalid params | Invalid method parameters |
| -32603 | Internal error | Error due to faulty logic or coding in the program |
| -32000 | Network error | Underlying network error |
| -32001 | User rejected | The user rejected the request |
| -32002 | Unsupported network | The target network is not supported |
| -32003 | No account | Provider has no account |
| -32004 | Insufficient funds | Insufficient funds |
| -32005 | Remote rpc error | Error when calling remote rpc service |
This project is licensed under the MIT License - see the LICENSE file for details.