Aleo Network Client

Overview

Client library that encapsulates REST calls to publicly exposed endpoints of Aleo nodes. The methods provided in this allow users to query public information from the Aleo blockchain and submit transactions to the network.

Kind: global class

AleoNetworkClient

Constructor

AleoNetworkClient

new AleoNetworkClient(host)

Param	Type
host	`string`

Example

// Connection to a local node
let local_connection = new AleoNetworkClient("http://localhost:3030");

// Connection to a public beacon node
let public_connection = new AleoNetworkClient("https://api.explorer.provable.com/v1");

Methods

setHost

Set a new host for the networkClient

networkClient.setHost(host)

Param	Type
host	`string`

Example

// New connection to a public beacon node
let public_connection = AleoNetworkClient.setHost("https://api.explorer.provable.com/v1");

setAccount

Set an account to use in networkClient calls

networkClient.setAccount(account)

Param	Type
account	`Account`

Example

let account = new Account();
networkClient.setAccount(account);

getAccount

Return the Aleo account used in the networkClient

networkClient.getAccount() ⇒ Account

Param	Type
return	`Account`

Example

let account = networkClient.getAccount();

fetchData

Fetches data from the Aleo network and returns it as a JSON object.

networkClient.fetchData(url) ⇒ Promise.<Type>

Param	Type
url	`undefined`
return	`Promise.<Type>`

fetchRaw

Fetches data from the Aleo network and returns it as an unparsed string. This method should be used when it is desired to reconstitute data returned from the network into a WASM object.

networkClient.fetchRaw(url) ⇒ Promise.<string>

Param	Type
url	`undefined`
return	`Promise.<string>`

findRecords

Attempt to find records in the Aleo blockchain.

networkClient.findRecords(startHeight, endHeight, unspent, programs, amounts, maxMicrocredits, nonces, privateKey) ⇒ Promise.<Array.<RecordPlaintext>>

Param	Type	Description
startHeight	`number`	The height at which to start searching for unspent records
endHeight	`number`	The height at which to stop searching for unspent records
unspent	`boolean`	Whether to search for unspent records only
programs	`Array.<string>`	The program(s) to search for unspent records in
amounts	`Array.<number>`	The amounts (in microcredits) to search for (eg. [100, 200, 3000])
maxMicrocredits	`number`	The maximum number of microcredits to search for
nonces	`Array.<string>`	The nonces of already found records to exclude from the search
privateKey	`string`	An optional private key to use to find unspent records.
return	`Promise.<Array.<RecordPlaintext>>`

Example

// Find specific amounts
const startHeight = 500000;
const amounts = [600000, 1000000];
const records = await networkClient.findRecords(startHeight, undefined, true, ["credits.aleo"], amounts);

// Find specific amounts with a maximum number of cumulative microcredits
const maxMicrocredits = 100000;
const records = await networkClient.findRecords(startHeight, undefined, true, ["credits.aleo"], undefined, maxMicrocredits);

findUnspentRecords

Attempts to find unspent records in the Aleo blockchain.

networkClient.findUnspentRecords(startHeight, endHeight, programs, amounts, maxMicrocredits, nonces, privateKey) ⇒ Promise.<Array.<RecordPlaintext>>

Param	Type	Description
startHeight	`number`	The height at which to start searching for unspent records
endHeight	`number`	The height at which to stop searching for unspent records
programs	`Array.<string>`	The program(s) to search for unspent records in
amounts	`Array.<number>`	The amounts (in microcredits) to search for (eg. [100, 200, 3000])
maxMicrocredits	`number`	The maximum number of microcredits to search for
nonces	`Array.<string>`	The nonces of already found records to exclude from the search
privateKey	`string`	An optional private key to use to find unspent records.
return	`Promise.<Array.<RecordPlaintext>>`

Example

// Find specific amounts
const startHeight = 500000;
const endHeight = 550000;
const amounts = [600000, 1000000];
const records = await networkClient.findUnspentRecords(startHeight, endHeight, ["credits.aleo"], amounts);

// Find specific amounts with a maximum number of cumulative microcredits
const maxMicrocredits = 100000;
const records = await networkClient.findUnspentRecords(startHeight, undefined, ["credits.aleo"], undefined, maxMicrocredits);

getBlock

Returns the contents of the block at the specified block height.

networkClient.getBlock(height) ⇒ Promise.<BlockJSON>

Param	Type
height	`number`
return	`Promise.<BlockJSON>`

Example

let block = await networkClient.getBlock(1234);

getBlockRange

Returns a range of blocks between the specified block heights.

networkClient.getBlockRange(start, end) ⇒ Promise.<Array.<BlockJSON>>

Param	Type
start	`number`
end	`number`
return	`Promise.<Array.<BlockJSON>>`

Example

let blockRange = await networkClient.getBlockRange(2050, 2100);

getProgram

Returns the source code of a program given a program ID.

networkClient.getProgram(programId) ⇒ Promise.<string>

Param	Type	Description
programId	`string`	The program ID of a program deployed to the Aleo Network
return	`Promise.<string>`

Example

let program = await networkClient.getProgram("hello_hello.aleo");
const expectedSource = "program hello_hello.aleo;\n\nfunction hello:\n    input r0 as u32.public;\n    input r1 as u32.private;\n    add r0 r1 into r2;\n    output r2 as u32.private;\n"
assert.equal(program, expectedSource);

getProgramObject

Returns a program object from a program ID or program source code.

networkClient.getProgramObject(inputProgram) ⇒ Promise.<Program>

Param	Type	Description
inputProgram	`string`	The program ID or program source code of a program deployed to the Aleo Network
return	`Promise.<Program>`

Example

let program = await networkClient.getProgramObject("hello_hello.aleo");
const programSource = "program hello_hello.aleo;\n\nfunction hello:\n    input r0 as u32.public;\n    input r1 as u32.private;\n    add r0 r1 into r2;\n    output r2 as u32.private;\n"

// Get program object from program ID or program source code
const programObjectFromID = await networkClient.getProgramObject(programID);
const programObjectFromSource = await networkClient.getProgramObject(programSource);

// Both program objects should be equal
assert.equal(programObjectFromID.to_string(), programObjectFromSource.to_string());

getProgramImports

Returns an object containing the source code of a program and the source code of all programs it imports

networkClient.getProgramImports(inputProgram) ⇒ Promise.<ProgramImports>

Param	Type	Description
inputProgram	`Program`	The program ID or program source code of a program deployed to the Aleo Network
return	`Promise.<ProgramImports>`

Example

let program = await networkClient.getProgramImports("double_test.aleo");
const double_test_source = "import multiply_test.aleo;\n\nprogram double_test.aleo;\n\nfunction double_it:\n    input r0 as u32.private;\n    call multiply_test.aleo/multiply 2u32 r0 into r1;\n    output r1 as u32.private;\n"
const double_test = Program.fromString(double_test_source);
const expectedImports = {
    "multiply_test.aleo": "program multiply_test.aleo;\n\nfunction multiply:\n    input r0 as u32.public;\n    input r1 as u32.private;\n    mul r0 r1 into r2;\n    output r2 as u32.private;\n"
}

// Imports can be fetched using the program ID, source code, or program object
let programImports = await networkClient.getProgramImports("double_test.aleo");
assert.deepStrictEqual(programImports, expectedImports);

// Using the program source code
programImports = await networkClient.getProgramImports(double_test_source);
assert.deepStrictEqual(programImports, expectedImports);

// Using the program object
programImports = await networkClient.getProgramImports(double_test);
assert.deepStrictEqual(programImports, expectedImports);

getProgramImportNames

Get a list of the program names that a program imports.

networkClient.getProgramImportNames(inputProgram) ⇒ Array.<string>

Param	Type	Description
inputProgram	`Program`	The program id or program source code to get the imports of
return	`Array.<string>`

Example

let mappings = networkClient.getProgramImportNames("double_test.aleo");
const expectedImportsNames = ["multiply_test.aleo"];
assert.deepStrictEqual(programImportsNames, expectedImportsNames);

getDeploymentTransactionIDForProgram

Returns the deployment transaction id associated with the specified program.

networkClient.getDeploymentTransactionIDForProgram(program) ⇒ TransactionJSON

Param	Type
program	`Program`
return	`TransactionJSON`

Example

let program = networkClient.getDeploymentTransactionIDForProgram("foo.aleo");

getDeploymentTransactionForProgram

Returns the deployment transaction associated with a specified program.

networkClient.getDeploymentTransactionForProgram(program) ⇒ TransactionJSON

Param	Type
program	`Program`
return	`TransactionJSON`

Example

let program = networkClient.getDeploymentTransactionForProgram("foo.aleo");

getDeploymentTransactionObjectForProgram

Returns the deployment transaction associated with a specified program as a wasm object.

networkClient.getDeploymentTransactionObjectForProgram(program) ⇒ TransactionJSON

Param	Type
program	`Program`
return	`TransactionJSON`

getProgramMappingNames

Returns the names of the mappings of a program.

networkClient.getProgramMappingNames(programId) ⇒ Promise.<Array.<string>>

Param	Type	Description
programId	`string`	The program ID to get the mappings of (e.g. "credits.aleo")
return	`Promise.<Array.<string>>`

Example

let mappings = await networkClient.getProgramMappingNames("credits.aleo");
const expectedMappings = [
  "committee",
  "delegated",
  "metadata",
  "bonded",
  "unbonding",
  "account",
  "withdraw"
];
assert.deepStrictEqual(mappings, expectedMappings);

getProgramMappingValue

Returns the value of a program's mapping for a specific key.

networkClient.getProgramMappingValue(programId, mappingName, key) ⇒ Promise.<string>

Param	Type	Description
programId	`string`	The program ID to get the mapping value of (e.g. "credits.aleo")
mappingName	`string`	The name of the mapping to get the value of (e.g. "account")
key	`string`	The key of the mapping to get the value of (e.g. "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px")
return	`Promise.<string>`

Example

// Get public balance of an account
let mappingValue = await networkClient.getProgramMappingValue("credits.aleo", "account", "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px");
const expectedValue = "0u64";
assert.equal(mappingValue, expectedValue);

getProgramMappingPlaintext

Returns the value of a mapping as a wasm Plaintext object. Returning an object in this format allows it to be converted to a Js type and for its internal members to be inspected if it's a struct or array.

networkClient.getProgramMappingPlaintext(programId, mappingName, key) ⇒ Promise.<string>

Param	Type	Description
programId	`string`	The program ID to get the mapping value of (e.g. "credits.aleo")
mappingName	`string`	The name of the mapping to get the value of (e.g. "account")
key	`string`	The key of the mapping to get the value of (e.g. "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px")
return	`Promise.<string>`

Example

// Get the bond state as an account.
const unbondedState = await networkClient.getProgramMappingPlaintext("credits.aleo", "bonded", "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px");

// Get the two members of the object individually.
const validator = unbondedState.getMember("validator");
const microcredits = unbondedState.getMember("microcredits");

// Ensure the expected values are correct.
assert.equal(validator, "aleo1u6940v5m0fzud859xx2c9tj2gjg6m5qrd28n636e6fdd2akvfcgqs34mfd");
assert.equal(microcredits, BigInt("9007199254740991"));

// Get a JS object representation of the unbonded state.
const unbondedStateObject = unbondedState.toObject();

const expectedState = {
    validator: "aleo1u6940v5m0fzud859xx2c9tj2gjg6m5qrd28n636e6fdd2akvfcgqs34mfd",
    microcredits: BigInt("9007199254740991")
};
assert.equal(unbondedState, expectedState);

getLatestBlock

Returns the contents of the latest block.

networkClient.getLatestBlock() ⇒ Promise.<BlockJSON>

Param	Type
return	`Promise.<BlockJSON>`

Example

let latestHeight = await networkClient.getLatestBlock();

getLatestHeight

Returns the latest block height.

networkClient.getLatestHeight() ⇒ Promise.<number>

Param	Type
return	`Promise.<number>`

Example

let latestHeight = await networkClient.getLatestHeight();

getLatestCommittee

Returns the latest committee.

networkClient.getLatestCommittee() ⇒ Promise.<object>

Param	Type
return	`Promise.<object>`

Example

let latestCommittee = await networkClient.getLatestCommittee();

getStateRoot

Returns the latest state/merkle root of the Aleo blockchain.

networkClient.getStateRoot() ⇒ Promise.<string>

Param	Type
return	`Promise.<string>`

Example

let stateRoot = await networkClient.getStateRoot();

getTransaction

Returns a transaction by its unique identifier.

networkClient.getTransaction(id) ⇒ Promise.<TransactionJSON>

Param	Type
id	`string`
return	`Promise.<TransactionJSON>`

Example

let transaction = await networkClient.getTransaction("at1handz9xjrqeynjrr0xay4pcsgtnczdksz3e584vfsgaz0dh0lyxq43a4wj");

getTransactionObject

Returns a transaction as a wasm object. Getting a transaction of this type will allow the ability for the inputs, outputs, and records to be searched for and displayed.

networkClient.getTransactionObject(transactionId) ⇒ Promise.<Transaction>

Param	Type
transactionId	`string`
return	`Promise.<Transaction>`

Example

const transactionObject = await networkClient.getTransactionObject("at1handz9xjrqeynjrr0xay4pcsgtnczdksz3e584vfsgaz0dh0lyxq43a4wj");
// Get the transaction inputs as a JS array.
const transactionOutputs = transactionObject.inputs(true);

// Get the transaction outputs as a JS object.
const transactionInputs = transactionObject.outputs(true);

// Get any records generated in transitions in the transaction as a JS object.
const records = transactionObject.records();

// Get the transaction type.
const transactionType = transactionObject.transactionType();
assert.equal(transactionType, "Execute");

// Get a JS representation of all inputs, outputs, and transaction metadata.
const transactionSummary = transactionObject.summary();

getTransactions

Returns the transactions present at the specified block height.

networkClient.getTransactions(height) ⇒ Promise.<Array.<ConfirmedTransactionJSON>>

Param	Type
height	`number`
return	`Promise.<Array.<ConfirmedTransactionJSON>>`

Example

let transactions = await networkClient.getTransactions(654);

getTransactionsInMempool

Returns the transactions in the memory pool. This method requires access to a validator's REST API.

networkClient.getTransactionsInMempool() ⇒ Promise.<Array.<TransactionJSON>>

Param	Type
return	`Promise.<Array.<TransactionJSON>>`

Example

let transactions = await networkClient.getTransactionsInMempool();

getTransitionId

Returns the transition ID of the transition corresponding to the ID of the input or output.

networkClient.getTransitionId(inputOrOutputID) ⇒ Promise.<string>

Param	Type	Description
inputOrOutputID	`string`	ID of the input or output.
return	`Promise.<string>`

Example

let transition = await networkClient.getTransitionId("2429232855236830926144356377868449890830704336664550203176918782554219952323field");

submitTransaction

Submit an execute or deployment transaction to the Aleo network.

networkClient.submitTransaction(transaction) ⇒ string

Param	Type	Description
transaction	`Transaction`	The transaction to submit to the network
return	`string`

submitSolution

Submit a solution to the Aleo network.

networkClient.submitSolution(solution) ⇒ Promise.<string>

Param	Type	Description
solution	`string`	The string representation of the solution desired to be submitted to the network.
return	`Promise.<string>`

Overview​

Constructor​

AleoNetworkClient​

Methods​

setHost​

setAccount​

getAccount​

fetchData​

fetchRaw​

findRecords​

findUnspentRecords​

getBlock​

getBlockRange​

getProgram​

getProgramObject​

getProgramImports​

getProgramImportNames​

getDeploymentTransactionIDForProgram​

getDeploymentTransactionForProgram​

getDeploymentTransactionObjectForProgram​

getProgramMappingNames​

getProgramMappingValue​

getProgramMappingPlaintext​

getLatestBlock​

getLatestHeight​

getLatestCommittee​

getStateRoot​

getTransaction​

getTransactionObject​

getTransactions​

getTransactionsInMempool​

getTransitionId​

submitTransaction​

submitSolution​

Overview

Constructor

AleoNetworkClient

Methods

setHost

setAccount

getAccount

fetchData

fetchRaw

findRecords

findUnspentRecords

getBlock

getBlockRange

getProgram

getProgramObject

getProgramImports

getProgramImportNames

getDeploymentTransactionIDForProgram

getDeploymentTransactionForProgram

getDeploymentTransactionObjectForProgram

getProgramMappingNames

getProgramMappingValue

getProgramMappingPlaintext

getLatestBlock

getLatestHeight

getLatestCommittee

getStateRoot

getTransaction

getTransactionObject

getTransactions

getTransactionsInMempool

getTransitionId

submitTransaction

submitSolution