This is the official Javascript library for the Aidos Core. It implements both the API, as well as newly proposed functionality (such as signing, bundles, utilities and conversion).
It should be noted that the Javascript Library as it stands right now is an beta release. As such, there might be some unexpected results.
After you've successfully installed the library, it is fairly easy to get started by simply launching a new instance of the aidos object. When instantiating the object you have the option to decide the API provider that is used to send the requests to. You can either supply this directly via the provider
option, or individually with host
and port
, as can be seen in the example below:
// Create an aidos instance with host and port as provider
var aidos = new aidos({
'host': 'http://localhost',
'port': 14266
});
// Create an aidos instance directly with provider
var aidos = new aidos({
'provider': 'http://api.aidoskuneen.com:14266' // this is just an example
});
// now you can start using all of the functions
aidos.api.getNodeInfo();
Overall, there are currently four subclasses that are accessible from the aidos object:
api
: Core API functionality for interacting with the Aidos core. (The available API commands can be seen in the Aidos Kuneen Reference Implementation)utils
: Utility related functions for conversions, validation and so onmultisig
: Functions for creating and signing multi-signature addresses and transactions. (This functionality has not been completely tested yet and will be re-worked)validate
: Validator functions that can help with determining whether the inputs or results that you get are valid.
It should be noted that most API calls are done asynchronously. What this means is that you have to utilize callbacks in order to catch the response successfully. We will add support for sync API calls, as well as event listeners in future versions.
Here is a simple example of how to access the getNodeInfo
function:
aidos.api.getNodeInfo(function(error, success) {
if (error) {
console.error(error);
} else {
console.log(success);
}
})
This Javascript library has implemented all of the core API calls that are made available by the current Aidos Reference Implementation.
You can simply use any of the available options from the api
object then. For example, if you want to use the getTips
function, you would simply do it as such:
aidos.api.getTips(function(error, success) {
// do stuff here
})
Wrapper function for getTrytes
and the Utility function transactionObjects
. This function basically returns the entire transaction objects for a list of transaction hashes.
aidos.api.getTransactionsObjects(hashes, callback)
hashes
:Array
List of transaction hashescallback
:Function
callback.
Array
- list of all the transaction objects from the corresponding hashes.
Wrapper function for getTrytes
and the Utility function transactionObjects
. This function basically returns the entire transaction objects for a list of transaction hashes.
aidos.api.findTransactionObjects(hashes, callback)
hashes
:Array
List of transaction hashescallback
:Function
callback.
Array
- list of all the transaction objects from the corresponding hashes.
Wrapper function for getNodeInfo
and getInclusionStates
. It simply takes the most recent solid milestone as returned by getNodeInfo, and uses it to get the inclusion states of a list of transaction hashes.
aidos.api.getLatestInclusion(hashes, callback)
hashes
:Array
List of transaction hashescallback
:Function
callback.
Array
- list of all the inclusion states of the transaction hashes
Wrapper function for broadcastTransactions
and storeTransactions
.
aidos.api.broadcastAndStore(trytes, callback)
trytes
:Array
List of transaction trytes to be broadcast and stored. Has to be trytes that were returned fromattachToMesh
callback
:Function
callback.
Object
- empty object.
Generates a new address from a seed and returns the address. This is either done deterministically, or by providing the index of the new address to be generated.
aidos.api.getNewAddress(seed [, options], callback)
seed
:String
tryte-encoded seed. It should be noted that this seed is not transferredoptions
:Object
which is optional:
index
:Int
If the index is provided, the generation of the address is not deterministic.checksum
:Bool
Adds 9-tryte address checksumtotal
:Int
Total number of addresses to generate.returnAll
:Bool
If true, it returns all addresses which were deterministically generated (until findTransactions returns null)
callback
:Function
Optional callback.
String | Array
- returns either a string, or an array of strings.
Gets all possible inputs of a seed and returns them with the total balance. This is either done deterministically (by genearating all addresses until findTransactions
returns null for a corresponding address), or by providing a key range to use for searching through.
You can also define the minimum threshold
that is required. This means that if you provide the threshold
value, you can specify that the inputs should only be returned if their collective balance is above the threshold value.
aidos.api.getInputs(seed, [, options], callback)
seed
:String
tryte-encoded seed. It should be noted that this seed is not transferredoptions
:Object
which is optional:
start
:int
Starting key indexend
:int
Ending key indexthreshold
:int
Minimum threshold of accumulated balances from the inputs that is requested
callback
:Function
Optional callback.
Object
- an object with the following keys:inputs
Array
- list of inputs objects consisting ofaddress
,balance
andkeyIndex
totalBalance
int
- aggregated balance of all inputs
Main purpose of this function is to get an array of transfer objects as input, and then prepare the transfer by generating the correct bundle, as well as choosing and signing the inputs if necessary (if it's a value transfer). The output of this function is an array of the raw transaction data (trytes).
You can provide multiple transfer objects, which means that your prepared bundle will have multiple outputs to the same, or different recipients. As single transfer object takes the values of: address
, value
, message
, tag
. The message and tag values are required to be tryte-encoded.
For the options, you can provide a list of inputs
, that will be used for signing the transfer's inputs. It should be noted that these inputs (an array of objects) should have the provided keyIndex
and address
values:
var inputs = [{
'keyIndex': //VALUE,
'address': //VALUE
}]
The library validates these inputs then and ensures that you have sufficient balance. The address
parameter can be used to define the address to which a remainder balance (if that is the case), will be sent to. So if all your inputs have a combined balance of 2000, and your spending 1800 of them, 200 of your coins will be sent to that remainder address. If you do not supply the address
, the library will simply generate a new one from your seed.
aidos.api.prepareTransfers(seed, transfersArray [, options], callback)
seed
:String
tryte-encoded seed. It should be noted that this seed is not transferredtransfersArray
:Array
of transfer objects:
address
:String
81-tryte encoded address of recipientvalue
:Int
value to be transferred.message
:String
tryte-encoded message to be included in the bundle.tag
:String
Tryte-encoded tag. Maximum value is 27 trytes.
options
:Object
which is optional:
inputs
:Array
List of inputs used for funding the transferaddress
:String
if defined, this address will be used for sending the remainder value (of the inputs) to.
callback
:Function
Optional callback.
Array
- an array that contains the trytes of the new bundle.
Wrapper function that does attachToMesh
and finally, it broadcasts and stores the transactions.
aidos.api.sendTrytes(trytes, depth, minWeightMagnitude, callback)
trytes
Array
trytesdepth
Int
depth value that determines how far to go for tip selectionminWeightMagnitude
Int
minWeightMagnitudecallback
:Function
Optional callback.
Array
- returns an array of the transfer (transaction objects).
Wrapper function that basically does prepareTransfers
, as well as attachToMesh
and finally, it broadcasts and stores the transactions locally.
aidos.api.sendTransfer(seed, depth, minWeightMagnitude, transfers [, options], callback)
seed
String
tryte-encoded seed. If provided, will be used for signing and picking inputs.depth
Int
depthminWeightMagnitude
Int
minWeightMagnitudetransfers
:Array
of transfer objects:
address
:String
81-tryte encoded address of recipientvalue
:Int
value to be transferred.message
:String
tryte-encoded message to be included in the bundle.tag
:String
27-tryte encoded tag.
options
:Object
which is optional:
inputs
:Array
List of inputs used for funding the transferaddress
:String
if defined, this address will be used for sending the remainder value (of the inputs) to.
callback
:Function
Optional callback.
Array
- returns an array of the transfer (transaction objects).
Takes a tail transaction hash as input, gets the bundle associated with the transaction and then replays the bundle by attaching it to the Mesh.
aidos.api.replayBundle(transaction [, callback])
transaction
:String
Transaction hash, has to be tail.depth
Int
depthminWeightMagnitude
Int
minWeightMagnitudecallback
:Function
Optional callback
Takes a tail transaction hash as input, gets the bundle associated with the transaction and then rebroadcasts the entire bundle.
aidos.api.broadcastBundle(transaction [, callback])
transaction
:String
Transaction hash, has to be tail.callback
:Function
Optional callback
This function returns the bundle which is associated with a transaction. Input has to be a tail transaction (i.e. currentIndex = 0). If there are conflicting bundles (because of a replay for example) it will return multiple bundles. It also does important validation checking (signatures, sum, order) to ensure that the correct bundle is returned.
aidos.api.getBundle(transaction, callback)
transaction
:String
Transaction hash of a tail transaction.callback
:Function
Optional callback
Array
- returns an array of the corresponding bundle of a tail transaction. The bundle itself consists of individual transaction objects.
Returns the transfers which are associated with a seed. The transfers are determined by either calculating deterministically which addresses were already used, or by providing a list of indexes to get the addresses and the associated transfers from. The transfers are sorted by their timestamp. It should be noted that, because timestamps are not enforced in aidos, that this may lead to incorrectly sorted bundles (meaning that their chronological ordering in the Mesh is different).
If you want to have your transfers split into received / sent, you can use the utility function categorizeTransfers
getTransfers(seed [, options], callback)
seed
:String
tryte-encoded seed. It should be noted that this seed is not transferredoptions
:Object
which is optional:
start
:Int
Starting key index for searchend
:Int
Ending key index for searchinclusionStates
:Bool
If True, it gets the inclusion states of the transfers.
callback
:Function
Optional callback.
Array
- returns an array of transfers. Each array is a bundle for the entire transfer.
Similar to getTransfers
, just a bit more comprehensive in the sense that it also returns the balance
and addresses
that are associated with your account (seed). This function is useful in getting all the relevant information of your account. If you want to have your transfers split into received / sent, you can use the utility function categorizeTransfers
getAccountData(seed [, options], callback)
seed
:String
tryte-encoded seed. It should be noted that this seed is not transferredoptions
:Object
which is optional:
start
:Int
Starting key index for searchend
:Int
Ending key index for search
callback
:Function
Optional callback.
Object
- returns an object of your account data in the following format:
{
'addresses': [],
'transfers': [],
'balance': 0
}
All utils function are done synchronously.
aidos utilizes the Standard system of Units. See below for all available units:
'u ADK' : 0.000001,
'm ADK' : 0.001,
'ADK' : 1,
'M ADK' : 1000000
aidos.utils.convertUnits(value, fromUnit, toUnit)
value
:Integer || String
Value to be converted. Can be string, an integer or float.fromUnit
:String
Current unit of the value. See above for the available units to utilize for conversion.toUnit
:String
Unit to convert the from value into.
Integer
- returns the converted unit (fromUnit => toUnit).
Takes an 81-trytes address or a list of addresses as input and calculates the 9-trytes checksum of the address(es).
aidos.utils.addChecksum(address)
address
:String | List
Either an individual address, or a list of addresses.
String | List
- returns the 90-trytes addresses (81-trytes address + 9-trytes checksum) either as a string or list, depending on the input.
Takes an 90-trytes address as input and simply removes the checksum.
aidos.utils.noChecksum(address)
address
:String |Â List
90-trytes address. Either string or a list
String | List
- returns the 81-tryte address(es)
Takes an 90-trytes checksummed address and returns a true / false if it is valid.
aidos.utils.isValidChecksum(addressWithChecksum)
addressWithChecksum
:String
90-trytes address
Bool
- True / False whether the checksum is valid or not
Converts the trytes of a transaction into its transaction object.
aidos.utils.transactionObject(trytes)
trytes
:String
2673-trytes of a transaction
Object
- Transaction object
Converts a valid transaction object into trytes. Please refer to [TODO] for more information what a valid transaction object looks like.
aidos.utils.transactionTrytes(transactionObject)
transactionObject
:Object
valid transaction object
trytes
- converted trytes of
Categorizes a list of transfers into sent
and received
. It is important to note that zero value transfers (which for example, is being used for storing addresses in the Mesh), are seen as received
in this function.
aidos.utils.categorizeTransfers(transfers, addresses)
transfers
:List
A list of bundles. Basically is an array, of arrays (bundles), as is returned from getTransfers or getAccountDataaddresses
: 'List' List of addresses that belong to you. With these addresses as input, it's determined whether it's a sent or a receive transaction. Therefore make sure that these addresses actually belong to you.
object
- the transfers categorized into sent
and received
Multi signature related functions.
VERY IMPORTANT NOTICE
This functionality has not been completely tested yet and will be re-worked, as always use is at your own risk. It is not recommended to use multisig until a full guide is released / until it is fully implemented into the wallet.
Generates the corresponding private key of a seed.
aidos.multisig.getKey(seed, index)
seed
:String
Tryte encoded seedindex
: 'Int' Index of the private key.
String
- private key represented in trytes.
Generates the digest value of a key.
aidos.multisig.getDigest(seed, index)
seed
:String
Tryte encoded seedindex
: 'Int' Index of the private key.
String
- digest represented in trytes.
This function is used to initiate the creation of a new multisig address. The way that it works is that the first participant of the multi-signature initiates this function with an empty curl state, and then shares the newly generated state with the other participants of the multisig address, who then basically add their key digest. Then finally, once the last co-signer added their digest, finalizeAddress
can be used to get the actual 81-tryte address value. validateAddress
can be used to actually validate the multi-signature.
aidos.multisig.addAddressDigest(digestTrytes, curlStateTrytes)
digestTrytes
:String
digest trytes as returned bygetDigest
curlStateTrytes
: 'String' curl state trytes to continue modifying (which are returned by this function)
String
- curl state trytes
Finalizes the multisig address generation process and returns the correct 81-tryte address.
aidos.multisig.finalizeAddress(curlStateTrytes)
curlStateTrytes
: 'String' curl state trytes to continue modifying (which are returned by this function)
String
- curl state trytes
Validates a generated multi-sig address by getting the corresponding key digests of each of the co-signers. The order of the digests is of essence in getting correct results.
aidos.multisig.validateAddress(multisigAddress, digests)
multisigAddress
:String
digest trytes as returned bygetDigest
digests
: 'Array' array of the key digest for each of the cosigners. The digests need to be provided in the correct signing order.
Bool
- true / false
Initiates the creation of a new transfer by generating an empty bundle with the correct number of bundle entries to be later used for the signing process. It should be noted that currently, only a single input (via inputAddress
) is possible. The remainderAddress
also has to be provided and should be generated by the co-signers of the multi-signature before initiating the transfer.
aidos.multisig.initiateTransfer(inputAddress, remainderAddress, numCosigners, transfers, callback)
inputAddress
:String
input address which has sufficient balance and is controlled by the co-signersremainderAddress
: 'String' in case there is a remainder balance, send the funds to this address.numCosigners
:Int
the number of co-signers for the multi-sigtransfers
:Array
Transfers objectcallback
:Function
Array
- bundle
This function is called by each of the co-signers individually to add their signature to the bundle. Here too, order is important. This function returns the bundle, which should be shared with each of the participants of the multi-signature.
aidos.multisig.addSignature(bundleToSign, cosignerIndex, inputAddress, key, callback)
bundleToSign
:Array
bundle to signcosignerIndex
:Int
total order index of the current signer in the multi-signature. Index starts at 0. e.g. If there are 4 co-signers, and you are the 3rd in order to add your signature, then your index is2
.inputAddress
: 'String' input address as provided toinitiateTransfer
.key
:String
private key trytes as returned bygetKey
callback
:Function
Array
- bundle
This function makes it possible for each of the co-signers in the multi-signature to independently verify that a generated transaction with the corresponding signatures of the co-signers is valid. This function is safe to use and does not require any sharing of digests or key values.
aidos.multisig.validateSignatures(signedBundle, inputAddress, numCosigners)
signedBundle
:Array
signed bundle by all of the co-signersinputAddress
: 'String' input address as provided toinitiateTransfer
.numCosigners
:Int
total number of co-signers
bool
- true / false
Validator functions. Return either true / false.
Checks if the provided input is a valid 81-tryte (non-checksum), or 90-tryte (with checksum) address.
aidos.validate.isAddress(address)
address
:String
A single address
Determines if the provided input is valid trytes. Valid trytes are: ABCDEFGHIJKLMNOPQRSTUVWXYZ9
. If you specify the length parameter, you can also validate the input length.
aidos.validate.isTrytes(trytes [, length])
trytes
:String
length
:int || string
optional
Validates the value input, checks if it's integer.
aidos.validate.isValue(value)
value
:Integer
Checks if it's a decimal value
aidos.validate.isDecimal(value)
value
:Integer || String
Checks if correct hash consisting of 81-trytes.
aidos.validate.isHash(hash)
hash
:String
Checks if it's a correct array of transfer objects. A transfer object consists of the following values:
{
'address': // STRING (trytes encoded, 81 or 90 trytes)
'value': // INT
'message': // STRING (trytes encoded)
'tag': // STRING (trytes encoded, maximum 27 trytes)
}
aidos.validate.isTransfersArray(transfersArray)
transfersArray
:array
Array of valid 81 or 90-trytes hashes.
aidos.validate.isArrayOfHashes(hashesArray)
hashesArray
:Array
Checks if it's an array of correct 2673-trytes. These are trytes either returned by prepareTransfers, attachToMesh or similar call. A single transaction object is encoded 2673 trytes.
aidos.validate.isArrayOfTrytes(trytesArray)
trytesArray
:Array
Similar to isArrayOfTrytes
, just that in addition this function also validates that the last 243 trytes are non-zero (meaning that they don't equal 9). The last 243 trytes consist of: trunkTransaction
+ branchTransaction
+ nonce
. As such, this function determines whether the provided trytes have been attached to the Mesh successfully. For example this validator can be used for trytes returned by attachToMesh
.
aidos.validate.isArrayOfAttachedTrytes(trytesArray)
trytesArray
:Array
Work in progress.
aidos.validate.isUri(uris)
uris
:Array
Validates if it's an array of correct input objects. These inputs are provided to either prepareTransfers
or sendTransfer
. An input objects consists of the following:
{
'keyIndex': // INT
'address': // STRING
}
aidos.validate.isInputs(inputsArray)
inputsArray
:Array
Self explanatory.
aidos.validate.isString(string)
Self explanatory.
aidos.validate.isInt(int)
Self explanatory.
aidos.validate.isArray(array)
Self explanatory.
aidos.validate.isObject(array)
Validates a given string to check if it's a valid IPv6, IPv4 or hostname format. The string must have a tcp://
prefix, and it may or may not have a port. Here are some example inputs:
tcp://[2001:db8:a0b:12f0::1]:14265
tcp://[2001:db8:a0b:12f0::1]
tcp://8.8.8.8:14265
tcp://domain.com
tcp://domain2.com:14265
aidos.utils.isUri(node)
node
:String
IPv6, IPv4 or Hostname with or without a port.
bool
- true/false if valid node format.