API Reference

This specification is intended to be implementation agnostic. The API may turn out to be RESTful, in which case specific calls will be defined by URL endpoints not method names.

The method names are not intended to be part of the final product.For any method call that involves transaction signing, that method call will return a payload (a raw transaction) to be signed, which, once signed, is sent to the OAN via the sendSignedPayload method.

Note: none of these calls involve using meta-transactions for simplicity. But the final draft will provide a means of producing meta-transactions for any of the method calls that send transactions to the network.

---

API calls that involve direct blockchain interaction (transactions)

Some calls are omitted (calls that pertain to methods exposed by the ATS). What’s listed here are calls directly relating to use-cases that have come up in the EGs we’ve studied.

sendSignedTransactionDescription:

Sends the signed transaction to the blockchain only if the transaction was signed by the expected sender account.
Parameters: action–the name of the method call that was used to produce the transactionexpected sender–the account that must have signed the transactiontransaction–the signed transaction.
Returns:The address of a newly created contract if one was created or else nothing.

createUnboundedDataTokenDescription:

Returns a raw transaction that will create a new UDT with the sender of the transaction listed as the owner of the token. The token will begin with an initial supply of zero tokens.
Parameters:
nonce – the nonce of the sender accountenergy.
price–the price per unit energy.
Returns: A raw transaction to be signed and sent to the OAN via sendSignedTransaction.

createUnboundedPlainTokenDescription:

Returns a raw transaction that will create a new UPT with the sender of the transaction listed as the owner of the token. The token will begin with an initial supply of zero tokens.
Parameters:
nonce–the nonce of the sender accountenergy.
price–the price per unit energy.
Returns: A raw transaction to be signed and sent to the OAN via sendSignedTransaction

mintUnboundedDataTokensToDescription:

Returns a raw transaction that will mint quantitynew tokens, all of which will have the same specified associated data, to the recipient.
Parameters:
nonce–the nonce of the sender accountenergy.
price–the price per unit.
energycontract–the address of the UDT.
contractrecipient–the address that will receive the newly minted.
tokensdata–the data associated with the newly minted.
tokensquantity–the number of such tokens to mint.
Returns: A raw transaction to be signed and sent to the OAN via sendSignedTransaction

mintUnboundedPlainTokensToDescription:

Returns a raw transaction that will mint quantitynew tokens to the recipient.
Parameters:
nonce–the nonce of the sender accountenergy.
price–the price per unit.
energycontract–the address of the UPT.
contractrecipient–the address that will receive the newly minted.
tokensquantity–the number of such tokens to mint.
Returns: A raw transaction to be signed and sent to the OAN via sendSignedTransaction

removeUnboundedDataTokensDescription:

Returns a raw transaction that will remove the specified quantityof UDTs from circulation by removing them from the specified address. Only tokens that have the associated datawill be removed. This is not the same as burning tokens! Burning tokens is used to destroy tokens. Removing tokens from circulation, while having the same effect, is used to communicate the idea of ‘this token has been used or fulfilled an off-chain purpose’.
Parameters:
nonce–the nonce of the sender accountenergy.
price–the price per unit.
energycontract–the address of the UDT.
contractaddress–the address that holds the tokens to be.
removeddata–the data associated with the tokens that are to be.
removedquantity–the number of such tokens to remove.
Returns: A raw transaction to be signed and sent to the OAN via sendSignedTransaction

removeUnboundedPlainTokensDescription:

Returns a raw transaction that will remove the specified quantityof UPTs from circulation by removing them from the specified address. This is not the same as burning tokens! Burning tokens is used to destroy tokens. Removing tokens from circulation, while having the same effect, is used to communicate the idea of ‘this token has been used or fulfilled an off-chain purpose’. Parameters:
nonce–the nonce of the sender accountenergy.
price–the price per unit.
energycontract–the address of the UPT.
contractaddress–the address that holds the tokens to be removed.
quantity–the number of such tokens to remove.
Returns: A raw transaction to be signed and sent to the OAN via sendSignedTransaction

API calls that do not hit the blockchain but query our projected state.

For each of these calls we may also want versions where they can make these queries over a specified range of blocks. This does involve ‘leaking’ more blockchain details, which is probably fine, but the question is: can apps talk about block numbers in a meaningful way? Likely the only thing they can talk aboutmeaningfully is time. In this case, we could make timestamp to block number conversions under the hood.

getBalanceOfAllUnboundedDataTokensDescription:

Returns the total number of all UDTs owned by the specified address.
Parameters:
address–theaccount whose token balance is to be queried.
contract–the contract address of the UDT.
ignore–the number of most recent blocks to ignore.
Returns: The total number of all UDTs owned by the specified address.

getBalanceOfUnboundedDataTokensDescription:

Returns the number of UDTs with the specified associated data that are owned by the given address.
Parameters:
address–the account whose token balance is to be queried.
contract–the contract address of the UDT.
data–the data associated with the particular UDT to be queried.
ignore–the number of most recent blocks to ignore.
Returns:The number of UDTs with the specified associated data that are owned by the given address.

getBalanceOfUnboundedPlainTokensDescription:

Returns the total number of all UPTs owned by the specified address. Parameters:
address–the account whose token balance is to be queried.
contract–the contract address of the UPT.
ignore–the number of most recent blocks to ignore.
Returns:The total number of all UPTs owned by the specified address.

getSupplyOfAllUnboundedDataTokensDescription:

Returns the total supply of all UDTs currently in circulation.
Parameters:
contract–the contract address of the UDT.
ignore–the number of most recent blocks to ignore.
Returns: The total supply of all UDTs currently in circulation.

getSupplyOfUnboundedDataTokensDescription:

Returns the total supply of all UDTs currently in circulation whose associated data contains the specified bit pattern.
Parameters:
contract–the contract address of the UDT.
pattern–the bit pattern to match the associated UDT data against. 8 ignore–the number of most recent blocks to ignore.
Returns: The total supply of all UDTs currently in circulation.

getSupplyOfUnboundedPlainTokensDescription:

Returns the total supply of all UPTs currently in circulation.
Parameters:
contract–the contract address of the UPT.
ignore–the number of most recent blocks to ignore.
Returns: The total supply of all UPTs currently in circulation.

getUnboundedDataTokenFullHistoryDescription:

Returns an orderedlist of chronological events. This is a complete list of all events fired off by the UDT contract over its lifetime.
Parameters:
contract–the contract address of the UDT.
ignore–the number of most recent blocks to ignore.
Returns: An orderedlist of chronological events. This is a complete list of all events fired off by the UDT contract over its lifetime.

getUnboundedPlainTokenFullHistoryDescription:

Returns an ordered list of chronological events. This is a complete list of all events fired off by the UPT contract over its lifetime. Parameters:
contract–the contract address of the UPT.
ignore–the number of most recent blocks to ignore.
Returns:Anordered list of chronological events. This is a complete list of all events fired off by the UDT contract over its lifetime.

getUnboundedDataTokenAccountHistoryDescription:

Returns an ordered list of chronological events. This is a complete list of all events fired off by the UDT contract over its lifetime involving the specified address (ie. the specified address is either the initiator or recipient of the event).
Parameters:
contract–the contract address of the UDT.
address–the address to filter the events against.
ignore–the number of most recent blocks to ignore.
Returns:An ordered list of chronological events. This is a complete list of all events fired off by the UDT contract over its lifetime involving the specified address (ie. the specified address is either the initiator or recipient of the event).

getUnboundedPlainTokenAccountHistoryDescription:

Returns an ordered list of chronological events. This is a complete list of all events fired off by the UPT contract over its lifetime involving the specified address (ie. the specified address is either the initiator or recipient of the event).
Parameters:contract–the contract address of the UPT address–the address to filter the events against.
ignore–the number of most recent blocks to ignore.
Returns:An ordered list of chronological events. This is a complete list of all events fired off by the UPT contract over its lifetime involving the specified address (ie. the specified address is either the initiator or recipient of the event).

getUnboundedDataTokenDataHistoryDescription:

Returns an ordered list of chronological events. This is a complete list of all events fired off by the UDT contract over its lifetime involving any token whose associated data matches the specified bit pattern. Parameters:
contract–the contract address of the UDT.
bit pattern–the data bit pattern to filter the events againstignore–the number of most recent blocks to ignore.
Returns: An ordered list of chronological events. This is a complete list of all events fired off by the UDT contract over its lifetime involving any token whose associated data matches the specified bit pattern.Really, these last few history calls will likely not be separated out like this, but will be a single call where you can choose to filter by optional multiple factors (bit pattern, address).

getUnboundedDataTokenAccountStatsDescription:

Returns a list of all accounts that own at least one UDT. Each listed account displays which kinds of UDTs they own and their respective quantities.
Parameters:
contract–the contract address of the UDT.
Returns:Alist of all accounts that own at least one UDT. Each listed account displays which kinds of UDTs they own and their respective quantities.

getUnboundedPlainTokenAccountStatsDescription:

Returns a list of all accounts that own at least one UPTand how many of that UPT they own.
Parameters:
contract–the contract address of the UPT.
Returns: Alist of all accounts that own at least one UPTand how many of that UPT they own.