@neongd/neo-dapi
v2.0.1
Published
Neo Dapi types and toolings
Downloads
398
Readme
Neo dAPI
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.
Getting Started
This library can be used as CommonJS/ES module or directly referenced in web page html.
Install CommonJS/ES module
npm install @neongd/neo-dapi
or
yarn add @neongd/neo-dapi
or
pnpm add @neongd/neo-dapi
Import CommonJS
const BaseDapi = require('@neongd/neo-dapi').BaseDapi;
Import ES module
import { BaseDapi } from '@neongd/neo-dapi';
Directly reference
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;
Initialization
Create a Neo dAPI instance, assuming we already have a Neo Provider (e.g., window.neo, window.OneGate):
const dapi = new BaseDapi(window.neo);
Example
Examples of usage can be found in test directory.
API Reference
Table of Contents
Methods
getProvider
Description
Gets information about the provider, including the provider, the provider version, and the NEPs that the provider is compatible with.
Parameters
(none)
Returns
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
/* 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',
},
});
getNetworks
Description
Gets the networks the provider is available to connect to, along with the default network the provider is currently set to.
Parameters
(none)
Returns
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
/* Example */
const networks = await dapi.getNetworks();
/* Example Response */
({
networks: ['MainNet', 'TestNet'],
defaultNetwork: 'TestNet',
});
getAccount
Description
Gets the account that is currently connected to the dApp.
Parameters
(none)
Returns
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
/* Example */
const account = await dapi.getAccount();
/* Example Response */
({
address: 'NXufgyw4AAST8tkLqZ5AtFKErjPzPEwnQp',
publicKey: '0267c8a9872df89d8da5bcb5ae6a30966495bbd6721d2a68d37ba2b842ea09b4c6',
label: 'My Account',
});
getBlockCount
Description
Gets the block count of the blockchain.
Parameters
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
Returns
number
- block count of the target network
Example
/* Example */
const count = await dapi.getBlockCount({});
/* Example Response */
26537;
getBlock
Description
Gets information about a specific block.
Parameters
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
Returns
Block
- a block object (See the type definitions here)
Example
/* 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',
});
getTransaction
Description
Gets the information about a specific transaction.
Parameters
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
Returns
Transaction
- a transaction object (See the type definitions here)
Example
/* 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,
});
getApplicationLog
Description
Gets the application log for a given transaction.
Parameters
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
Returns
ApplicationLog
- an application log object (See the type definitions here)
Example
/* 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',
},
],
},
},
],
},
],
});
getNep17Balances
Description
Gets all NEP17 asset balances in the given account.
Parameters
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.
Returns
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
/* Example */
const balances = await dapi.getNep17Balances({
address: 'NXufgyw4AAST8tkLqZ5AtFKErjPzPEwnQp',
});
/* Example Response */
[
{
assetHash: '0xd2a4cff31913016155e38e474a2c06d08be276cf',
amount: '10000000',
},
];
invokeRead
Description
Executes a contract invocation in read-only mode.
Parameters
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
Returns
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
/* 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,
},
],
});
invokeReadMulti
Description
Same as invokeRead
, but it allows to execute multiple read-only invocations in one request.
Parameters
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
Returns
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
/* 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,
},
],
});
invoke
Description
Executes a contract invocation that requires a user's signature.
Parameters
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
Returns
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
/* 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',
});
invokeMulti
Description
Same as invoke
, but allows to execute multiple invocations in one transaction.
Parameters
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
Returns
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
/* 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',
});
signMessage
Description
Signs a provided message with an account selected by user.
Parameters
object
- an object with the following properties:
message: string
- the message to sign
Returns
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
/* Example */
const result = await dapi.signMessage({
message: 'Hello world!',
});
/* Example Response */
({
salt: 'b3085013f5edcffe089c029a98794dab',
signature:
'2953200f24dfa8730302906d752cd33f135020f84828ad4f5d39e3563161029716369fdbec7e4cc9aa03dfd2e665f4ce37f149addccc8e336fdf707a5eba4d16',
publicKey: '031fe37e66cd2d6d711bad2b2fd40fabf2acce4def456ced62fc5ba445acb6f27c',
});
signMessageWithoutSalt
Description
Signs a provided message with an account selected by user. This method does not add a random salt as prefix.
Parameters
object
- an object with the following properties:
message: string
- the message to sign
Returns
object
- an object with the following properties:
signature: string
- signed resultpublicKey: string
- public key of the account signed the message
Example
/* Example */
const result = await dapi.signMessageWithoutSalt({
message: 'Hello world!',
});
/* Example Response */
({
signature:
'2953200f24dfa8730302906d752cd33f135020f84828ad4f5d39e3563161029716369fdbec7e4cc9aa03dfd2e665f4ce37f149addccc8e336fdf707a5eba4d16',
publicKey: '031fe37e66cd2d6d711bad2b2fd40fabf2acce4def456ced62fc5ba445acb6f27c',
});
signTransaction
Description
Signs a provided transaction with an account selected by user.
Parameters
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
Returns
object
- an object with the following properties:
signature: string
- signed resultpublicKey: string
- public key of the account signed the transaction
Example
/* 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',
});
broadcastTransaction
Description
Broadcasts a serialized signed transaction to the network.
Parameters
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
Returns
object
- an object with the following properties:
txid: string
- transaction ID of the transactionnodeUrl: string
- the node that the transaction was broadcast to
Example
/* 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
Events related functions are provided by Neo Provider.
Errors
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 |
License
This project is licensed under the MIT License - see the LICENSE file for details.