org.iota.jota

Class IotaAPICore

java.lang.Object

org.iota.jota.IotaAPICore

Direct Known Subclasses:

IotaAPI

public class IotaAPICore
extends Object

This class provides access to the Iota core API Handles direct methods with the connected node(s), and does basic verification

Field Summary

Fields

Modifier and Type	Field and Description
protected List<Connection>	nodes

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	IotaAPICore(ApiOptions options)

Method Summary

Modifier and Type	Method and Description
AddNeighborsResponse	addNeighbors(String... uris) Temporarily add a list of neighbors to your node.
boolean	addNode(Connection n)
GetAttachToTangleResponse	attachToTangle(String trunkTransaction, String branchTransaction, Integer minWeightMagnitude, String... trytes) Prepares the specified transactions (trytes) for attachment to the Tangle by doing Proof of Work.
GetAttachToTangleResponse	attachToTangleLocalPow(String trunkTransaction, String branchTransaction, Integer minWeightMagnitude, IotaPoW pow, String... trytes) Prepares the specified transactions (trytes) for attachment to the Tangle by doing Proof of Work.
BroadcastTransactionsResponse	broadcastTransactions(String... trytes) Broadcast a list of transactions to all neighbors.
IotaCustomResponse	callIxi(String module, String... args)
CheckConsistencyResponse	checkConsistency(String... tails) Checks the consistency of the subtangle formed by the provided tails.
FindTransactionResponse	findTransactions(String[] addresses, String[] tags, String[] approvees, String[] bundles) Find the transactions which match the specified input and return.
FindTransactionResponse	findTransactionsByAddresses(String... addresses) Find the transactions by addresses with checksum
FindTransactionResponse	findTransactionsByApprovees(String... approvees) Find the transactions by approvees
FindTransactionResponse	findTransactionsByBundles(String... bundles) Find the transactions by bundles
FindTransactionResponse	findTransactionsByDigests(String... digests) Deprecated.
FindTransactionResponse	findTransactionsByTags(String... tags) Find the transactions by tags
GetBalancesResponse	getBalances(Integer threshold, List<String> addresses) Calculates the confirmed balance, as viewed by the latest solid milestone.
GetBalancesResponse	getBalances(Integer threshold, List<String> addresses, List<String> tips) Calculates the confirmed balance, as viewed by the specified tips.
GetBalancesResponse	getBalances(Integer threshold, String[] addresses, String[] tips) Calculates the confirmed balance, as viewed by the specified tips.
ICurl	getCurl() Gives a clone of the custom curl defined in ApiOptions
String	getHost() Deprecated.
GetInclusionStateResponse	getInclusionStates(String[] transactions, String[] tips) Get the inclusion states of a set of transactions.
IotaPoW	getLocalPoW()
GetNeighborsResponse	getNeighbors() Returns the set of neighbors you are connected with, as well as their activity statistics (or counters).
GetNodeInfoResponse	getNodeInfo() Returns information about this node.
List<Connection>	getNodes()
String	getPort() Deprecated.
String	getProtocol() Deprecated.
Connection	getRandomNode()
GetTipsResponse	getTips() Returns all tips currently known by this node.
GetTransactionsToApproveResponse	getTransactionsToApprove(Integer depth) Tip selection which returns trunkTransaction and branchTransaction.
GetTransactionsToApproveResponse	getTransactionsToApprove(Integer depth, String reference) Tip selection which returns trunkTransaction and branchTransaction.
GetTrytesResponse	getTrytes(String... hashes) Returns the raw transaction data (trytes) of a specific transaction.
boolean	hasNodes()
InterruptAttachingToTangleResponse	interruptAttachingToTangle() Interrupts and completely aborts the attachToTangle process.
RemoveNeighborsResponse	removeNeighbors(String... uris) Temporarily removes a list of neighbors from your node.
boolean	removeNode(Connection n)
void	setCurl(ICurl localPoW)
void	setLocalPoW(IotaPoW localPoW)
StoreTransactionsResponse	storeTransactions(String... trytes) Stores transactions in the local storage.
String	toString()
WereAddressesSpentFromResponse	wereAddressesSpentFrom(String... addresses) Check if a list of addresses was ever spent from, in the current epoch, or in previous epochs.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

nodes

protected final List<Connection> nodes

Constructor Detail

IotaAPICore

protected IotaAPICore(ApiOptions options)

Method Detail

hasNodes

public boolean hasNodes()

getRandomNode

public Connection getRandomNode()

getNodes

public List<Connection> getNodes()

addNode

public boolean addNode(Connection n)

removeNode

public boolean removeNode(Connection n)

getCurl

public ICurl getCurl()

Gives a clone of the custom curl defined in ApiOptions

Returns:

A clone of our curl object

setCurl

public void setCurl(ICurl localPoW)

getLocalPoW

public IotaPoW getLocalPoW()

setLocalPoW

public void setLocalPoW(IotaPoW localPoW)

getNodeInfo

public GetNodeInfoResponse getNodeInfo()
                                throws ArgumentException

Returns information about this node.

Returns:

GetNodeInfoResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

getNeighbors

public GetNeighborsResponse getNeighbors()
                                  throws ArgumentException

Returns the set of neighbors you are connected with, as well as their activity statistics (or counters). The activity counters are reset after restarting IRI.

Returns:

GetNeighborsResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

addNeighbors

public AddNeighborsResponse addNeighbors(String... uris)
                                  throws ArgumentException

Temporarily add a list of neighbors to your node. The added neighbors will not be available after restart. Add the neighbors to your config file or supply them in the -n command line option if you want to add them permanently. The URI (Unique Resource Identification) for adding neighbors is: udp://IPADDRESS:PORT

Parameters:

uris - list of neighbors to add

Returns:

AddNeighborsResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

ArgumentException - When an URI is invalid

removeNeighbors

public RemoveNeighborsResponse removeNeighbors(String... uris)
                                        throws ArgumentException

Temporarily removes a list of neighbors from your node. The added neighbors will be added again after relaunching IRI. Remove the neighbors from your config file or make sure you don't supply them in the -n command line option if you want to keep them removed after restart. The URI (Unique Resource Identification) for removing neighbors is: udp://IPADDRESS:PORT

Parameters:

uris - The URIs of the neighbors we want to remove.

Returns:

RemoveNeighborsResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

ArgumentException - When an URI is invalid

getTips

public GetTipsResponse getTips()
                        throws ArgumentException

Returns all tips currently known by this node.

Returns:

GetTipsResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

findTransactions

public FindTransactionResponse findTransactions(String[] addresses,
                                                String[] tags,
                                                String[] approvees,
                                                String[] bundles)
                                         throws ArgumentException

Find the transactions which match the specified input and return. All input values are lists, for which a list of return values (transaction hashes), in the same order, is returned for all individual elements. The input fields can either be bundles, addresses, tags or approvees.

Using multiple of these input fields returns the intersection of the values. Can error if the node found more transactions than the max transactions send amount

Parameters:

addresses - Array of hashes from addresses, must contain checksums

tags - Array of tags

approvees - Array of transaction hashes

bundles - Array of bundle hashes

Returns:

FindTransactionResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

ArgumentException - If any of the parameters are not empty but have invalid values

callIxi

public IotaCustomResponse callIxi(String module,
                                  String... args)
                           throws ArgumentException

Throws:

ArgumentException

findTransactionsByAddresses

public FindTransactionResponse findTransactionsByAddresses(String... addresses)
                                                    throws ArgumentException

Find the transactions by addresses with checksum

Parameters:

addresses - An array of addresses, must contain checksums

Returns:

FindTransactionResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

ArgumentException - If one of the addresses is invalid

findTransactionsByBundles

public FindTransactionResponse findTransactionsByBundles(String... bundles)
                                                  throws ArgumentException

Find the transactions by bundles

Parameters:

bundles - An array of bundles.

Returns:

FindTransactionResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

ArgumentException - If one of the bundle hashes is invalid

findTransactionsByApprovees

public FindTransactionResponse findTransactionsByApprovees(String... approvees)
                                                    throws ArgumentException

Find the transactions by approvees

Parameters:

approvees - An array of approvees.

Returns:

FindTransactionResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

ArgumentException - If one of the approvee hashes is invalid

findTransactionsByDigests

@Deprecated
public FindTransactionResponse findTransactionsByDigests(String... digests)
                                                              throws ArgumentException

Deprecated.

Find the transactions by digests Deprecated: Use findTransactionsByTags(java.lang.String...) instead

Parameters:

digests - A List of digests. Must be hashed tags (digest)

Returns:

The transaction hashes which are returned depend on the input.

Throws:

ArgumentException - The request was considered wrong in any way by the node

ArgumentException - When one of the digests is invalid

findTransactionsByTags

public FindTransactionResponse findTransactionsByTags(String... tags)
                                               throws ArgumentException

Find the transactions by tags

Parameters:

tags - A List of tags.

Returns:

FindTransactionResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

ArgumentException - When one of the tags is invalid

getInclusionStates

public GetInclusionStateResponse getInclusionStates(String[] transactions,
                                                    String[] tips)
                                             throws ArgumentException

Get the inclusion states of a set of transactions. This is for determining if a transaction was accepted and confirmed by the network or not. You can search for multiple tips (and thus, milestones) to get past inclusion states of transactions.

This API call returns a list of boolean values in the same order as the submitted transactions. Boolean values will be true for confirmed transactions, otherwise false.

Parameters:

transactions - Array of transactions you want to get the inclusion state for.

tips - Array of tips (including milestones) you want to search for the inclusion state.

Returns:

GetInclusionStateResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

ArgumentException - when a transaction hash is invalid

ArgumentException - when a tip is invalid

getTrytes

public GetTrytesResponse getTrytes(String... hashes)
                            throws ArgumentException

Returns the raw transaction data (trytes) of a specific transaction. These trytes can then be easily converted into the actual transaction object. You can use Transaction.Transaction(String) for conversion to an object.

Parameters:

hashes - The transaction hashes you want to get trytes from.

Returns:

GetTrytesResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

ArgumentException - when a transaction hash is invalid

getTransactionsToApprove

public GetTransactionsToApproveResponse getTransactionsToApprove(Integer depth,
                                                                 String reference)
                                                          throws ArgumentException

Tip selection which returns trunkTransaction and branchTransaction. The input value depth determines how many milestones to go back for finding the transactions to approve. The higher your depth value, the more work you have to do as you are confirming more transactions. If the depth is too large (usually above 15, it depends on the node's configuration) an error will be returned. The reference is an optional hash of a transaction you want to approve. If it can't be found at the specified depth then an error will be returned.

Parameters:

depth - Number of bundles to go back to determine the transactions for approval.

reference - Hash of transaction to start random-walk from. This used to make sure the tips returned reference a given transaction in their past. Can be null.

Returns:

GetTransactionsToApproveResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

ArgumentException - The depth is invalid

getTransactionsToApprove

public GetTransactionsToApproveResponse getTransactionsToApprove(Integer depth)
                                                          throws ArgumentException

Tip selection which returns trunkTransaction and branchTransaction. The input value depth determines how many milestones to go back for finding the transactions to approve. The higher your depth value, the more work you have to do as you are confirming more transactions. If the depth is too large (usually above 15, it depends on the node's configuration) an error will be returned. The reference is an optional hash of a transaction you want to approve. If it can't be found at the specified depth then an error will be returned.

Parameters:

depth - Number of bundles to go back to determine the transactions for approval.

Returns:

GetTransactionsToApproveResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

getBalances

public GetBalancesResponse getBalances(Integer threshold,
                                       String[] addresses,
                                       String[] tips)
                                throws ArgumentException

Calculates the confirmed balance, as viewed by the specified tips. If you do not specify the referencing tips, the returned balance is based on the latest confirmed milestone. In addition to the balances, it also returns the referencing tips (or milestone), as well as the index with which the confirmed balance was determined. The balances are returned as a list in the same order as the addresses were provided as input.

Parameters:

threshold - The confirmation threshold between 0 and 100(inclusive). Should be set to 100 for getting balance by counting only confirmed transactions.

addresses - The addresses where we will find the balance for. Must contain the checksum.

tips - The optional tips to find the balance through.

Returns:

GetBalancesResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

ArgumentException - The threshold is invalid

ArgumentException - The tips or addresses are invalid

getBalances

public GetBalancesResponse getBalances(Integer threshold,
                                       List<String> addresses,
                                       List<String> tips)
                                throws ArgumentException

Calculates the confirmed balance, as viewed by the specified tips. If you do not specify the referencing tips, the returned balance is based on the latest confirmed milestone. In addition to the balances, it also returns the referencing tips (or milestone), as well as the index with which the confirmed balance was determined. The balances are returned as a list in the same order as the addresses were provided as input.

Parameters:

threshold - The confirmation threshold between 0 and 100(inclusive). Should be set to 100 for getting balance by counting only confirmed transactions.

addresses - The addresses where we will find the balance for. Must contain the checksum.

tips - The tips to find the balance through. Can be null

Returns:

GetBalancesResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

getBalances

public GetBalancesResponse getBalances(Integer threshold,
                                       List<String> addresses)
                                throws ArgumentException

Calculates the confirmed balance, as viewed by the latest solid milestone. In addition to the balances, it also returns the referencing milestone, and the index with which the confirmed balance was determined. The balances are returned as a list in the same order as the addresses were provided as input.

Parameters:

threshold - The confirmation threshold, should be set to 100.

addresses - The list of addresses you want to get the confirmed balance from. Must contain the checksum.

Returns:

GetBalancesResponse

Throws:

ArgumentException - The request was considered wrong in any way by the node

wereAddressesSpentFrom

public WereAddressesSpentFromResponse wereAddressesSpentFrom(String... addresses)
                                                      throws ArgumentException

Check if a list of addresses was ever spent from, in the current epoch, or in previous epochs.

Parameters:

addresses - List of addresses to check if they were ever spent from. Must contain the checksum.

Returns:

WereAddressesSpentFromResponse

Throws:

ArgumentException - when an address is invalid

checkConsistency

public CheckConsistencyResponse checkConsistency(String... tails)
                                          throws ArgumentException

Checks the consistency of the subtangle formed by the provided tails.

Parameters:

tails - The tails describing the subtangle.

Returns:

CheckConsistencyResponse

Throws:

ArgumentException - when a tail hash is invalid

attachToTangle

public GetAttachToTangleResponse attachToTangle(String trunkTransaction,
                                                String branchTransaction,
                                                Integer minWeightMagnitude,
                                                String... trytes)
                                         throws ArgumentException

Prepares the specified transactions (trytes) for attachment to the Tangle by doing Proof of Work. You need to supply branchTransaction as well as trunkTransaction. These are the tips which you're going to validate and reference with this transaction. These are obtainable by the getTransactionsToApprove API call.

The returned value is a different set of tryte values which you can input into broadcastTransactions and storeTransactions.

The last 243 trytes of the return value consist of the following:

• trunkTransaction
• branchTransaction
• nonce

These are valid trytes which are then accepted by the network.

Parameters:

trunkTransaction - A reference to an external transaction (tip) used as trunk. The transaction with index 0 will have this tip in its trunk. All other transactions reference the previous transaction in the bundle (Their index-1).

branchTransaction - A reference to an external transaction (tip) used as branch. Each Transaction in the bundle will have this tip as their branch, except the last. The last one will have the branch in its trunk.

minWeightMagnitude - The amount of work we should do to confirm this transaction. Each 0-trit on the end of the transaction represents 1 magnitude. A 9-tryte represents 3 magnitudes, since a 9 is represented by 3 0-trits. Transactions with a different minWeightMagnitude are compatible.

trytes - The list of trytes to prepare for network attachment, by doing proof of work.

Returns:

GetAttachToTangleResponse

Throws:

ArgumentException - when a trunk or branch hash is invalid

ArgumentException - when the provided transaction trytes are invalid

attachToTangleLocalPow

public GetAttachToTangleResponse attachToTangleLocalPow(String trunkTransaction,
                                                        String branchTransaction,
                                                        Integer minWeightMagnitude,
                                                        IotaPoW pow,
                                                        String... trytes)

Prepares the specified transactions (trytes) for attachment to the Tangle by doing Proof of Work. You need to supply branchTransaction as well as trunkTransaction. These are the tips which you're going to validate and reference with this transaction. These are obtainable by the getTransactionsToApprove API call.

The returned value is a different set of tryte values which you can input into broadcastTransactions and storeTransactions.

The last 243 trytes of the return value consist of the following:

• trunkTransaction
• branchTransaction
• nonce

These are valid trytes which are then accepted by the network.

Parameters:

trunkTransaction - A reference to an external transaction (tip) used as trunk. The transaction with index 0 will have this tip in its trunk. All other transactions reference the previous transaction in the bundle (Their index-1).

branchTransaction - A reference to an external transaction (tip) used as branch. Each Transaction in the bundle will have this tip as their branch, except the last. The last one will have the branch in its trunk.

minWeightMagnitude - The amount of work we should do to confirm this transaction. Each 0-trit on the end of the transaction represents 1 magnitude. A 9-tryte represents 3 magnitudes, since a 9 is represented by 3 0-trits. Transactions with a different minWeightMagnitude are compatible.

pow - Method of proof of work

trytes - The list of trytes to prepare for network attachment, by doing proof of work.

Returns:

GetAttachToTangleResponse

Throws:

ArgumentException - when a trunk or branch hash is invalid

ArgumentException - when the provided transaction trytes are invalid

interruptAttachingToTangle

public InterruptAttachingToTangleResponse interruptAttachingToTangle()
                                                              throws ArgumentException

Interrupts and completely aborts the attachToTangle process.

Returns:

InterruptAttachingToTangleResponse

Throws:

ArgumentException - If node connection fails

broadcastTransactions

public BroadcastTransactionsResponse broadcastTransactions(String... trytes)
                                                    throws ArgumentException

Broadcast a list of transactions to all neighbors. The trytes to be used for this call should be valid, attached transaction trytes. These trytes are returned by attachToTangle, or by doing proof of work somewhere else.

Parameters:

trytes - The list of transaction trytes to broadcast

Returns:

BroadcastTransactionsResponse

Throws:

ArgumentException - when the provided transaction trytes are invalid

storeTransactions

public StoreTransactionsResponse storeTransactions(String... trytes)
                                            throws ArgumentException

Stores transactions in the local storage. The trytes to be used for this call should be valid, attached transaction trytes. These trytes are returned by attachToTangle, or by doing proof of work somewhere else.

Parameters:

trytes - Transaction data to be stored.

Returns:

StoreTransactionsResponse

Throws:

ArgumentException - when the provided transaction trytes are invalid

getProtocol

@Deprecated
public String getProtocol()

Deprecated.

Gets the protocol. Deprecated - Nodes could not have a protocol. Get specific connection and check url

Returns:

The protocol to use when connecting to the remote node.

getHost

@Deprecated
public String getHost()

Deprecated.

Gets the host. Deprecated - Nodes could not have a host. Get specific connection and check url

Returns:

The host you want to connect to.

getPort

@Deprecated
public String getPort()

Deprecated.

Gets the port. Deprecated - Get specific connection and check port

Returns:

The port of the host you want to connect to.

toString

public String toString()

Overrides:

toString in class Object