com.radixdlt.client.application

Class RadixApplicationAPI

java.lang.Object

com.radixdlt.client.application.RadixApplicationAPI

public class RadixApplicationAPI
extends java.lang.Object

The Radix Application API, a high level api which hides the complexity of atoms, cryptography, and consensus. It exposes a simple high level interface for interaction with a Radix ledger.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RadixApplicationAPI.RadixApplicationAPIBuilder
static class	RadixApplicationAPI.Result
class	RadixApplicationAPI.Transaction Represents an atomic transaction to be committed to the ledger

Method Summary

Modifier and Type	Method and Description
UnsignedAtom	buildAtomWithFee(java.util.List<ParticleGroup> particleGroups) Returns an unsigned atom with the appropriate fees given a list of particle groups to compose the atom.
RadixApplicationAPI.Result	burnTokens(RRI token, java.math.BigDecimal amount) Burns an amount of tokens in the user's account
static RadixApplicationAPI	create(BootstrapConfig bootstrap, RadixIdentity identity) Creates an API with the default actions and reducers
RadixApplicationAPI.Result	createFixedSupplyToken(RRI tokenRRI, java.lang.String name, java.lang.String description, java.math.BigDecimal supply) Creates a fixed-supply token registered into the user's account with 10^-18 granularity
RadixApplicationAPI.Result	createMultiIssuanceToken(RRI tokenRRI, java.lang.String name) Creates a multi-issuance token registered into the user's account with zero initial supply, 10^-18 granularity and no description.
RadixApplicationAPI.Result	createMultiIssuanceToken(RRI tokenRRI, java.lang.String name, java.lang.String description) Creates a multi-issuance token registered into the user's account with zero initial supply and 10^-18 granularity
RadixApplicationAPI.Result	createToken(RRI tokenRRI, java.lang.String name, java.lang.String description, java.math.BigDecimal initialSupply, java.math.BigDecimal granularity, CreateTokenAction.TokenSupplyType tokenSupplyType) Creates a token registered into the user's account
RadixApplicationAPI.Transaction	createTransaction() Create a new transaction which is based off of the current data in the atom store.
static RadixApplicationAPI.RadixApplicationAPIBuilder	defaultBuilder() Creates a default API builder with the default actions and reducers without an identity
void	discoverNodes() Dispatches a discovery request, the result of which would be viewable via getNetworkState()
RadixApplicationAPI.Result	execute(Action action) Immediately executes a user action onto the ledger.
RadixApplicationAPI.Result	execute(Action action, RadixNode originNode) Immediately executes a user action onto the ledger.
RadixAddress	getAddress() Retrieve the user's address
RadixAddress	getAddress(ECPublicKey publicKey) Retrieve the address for the current universe given a public key
AtomStore	getAtomStore() Retrieve the atom store used by the API
java.util.Map<RRI,java.math.BigDecimal>	getBalances() Retrieve the balances of the current address from the current atom store.
RadixIdentity	getIdentity() Retrieve the user's key identity
RRI	getNativeTokenRef() Returns the native Token Reference found in the genesis atom
io.reactivex.Observable<RadixNodeAction>	getNetworkActions() Low level call to retrieve the actions occurring at the network level.
io.reactivex.Observable<RadixNetworkState>	getNetworkState() Get a stream of updated network states as they occur.
ECPublicKey	getPublicKey() Retrieve the user's public key
TokenState	getTokenDef(RRI tokenRRI) Retrieve the token state of the given rri
RadixApplicationAPI.Result	mintTokens(RRI token, java.math.BigDecimal amount) Mints an amount of new tokens into the user's account
<T> io.reactivex.Observable<T>	observeActions(java.lang.Class<T> actionClass, RadixAddress address) Returns a never ending stream of actions performed at a given address with the given Atom Store.
io.reactivex.Observable<java.math.BigDecimal>	observeBalance(RadixAddress address, RRI token) Returns a stream of the latest balance of a given token at a given address pull() must be called to continually retrieve the latest balance.
io.reactivex.Observable<java.math.BigDecimal>	observeBalance(RRI tokenRRI) Returns a stream of the latest balances at the current address pull() must be called to continually retrieve the latest balances.
io.reactivex.Observable<java.util.Map<RRI,java.math.BigDecimal>>	observeBalances(RadixAddress address) Returns a stream of the latest balances at a given address.
io.reactivex.Observable<DecryptedMessage>	observeMessages() Returns a never ending stream of messages stored at the current address.
io.reactivex.Observable<DecryptedMessage>	observeMessages(RadixAddress address) Returns a never ending stream of messages stored at a given address.
<T extends ApplicationState> io.reactivex.Observable<T>	observeState(java.lang.Class<T> stateClass, RadixAddress address) Returns a never ending stream of a state of a given address with the given Atom store.
io.reactivex.Observable<TokenState>	observeTokenDef(RRI tokenRRI) Returns a stream of the latest state of a given token
io.reactivex.Observable<TokenDefinitionsState>	observeTokenDefs() Returns a stream of the latest state of token definitions at the user's address
io.reactivex.Observable<TokenDefinitionsState>	observeTokenDefs(RadixAddress address) Returns a stream of the latest state of token definitions at a given address
io.reactivex.Observable<TokenTransfer>	observeTokenTransfers() Returns a never ending stream of token transfers stored at the current address.
io.reactivex.Observable<TokenTransfer>	observeTokenTransfers(RadixAddress address) Returns a never ending stream of token transfers stored at a given address.
io.reactivex.disposables.Disposable	pull() Idempotent method which prefetches atoms in user's account TODO: what to do when no puller available
io.reactivex.disposables.Disposable	pull(RadixAddress address) Idempotent method which prefetches atoms in an address TODO: what to do when no puller available
io.reactivex.Completable	pullOnce(RadixAddress address) Retrieves atoms until the node returns a synced message.
RadixApplicationAPI.Result	sendMessage(byte[] data, boolean encrypt) Sends a message to one's self
RadixApplicationAPI.Result	sendMessage(RadixAddress toAddress, byte[] data, boolean encrypt) Sends a message from the current address to another address
RadixApplicationAPI.Result	sendTokens(RRI token, RadixAddress to, java.math.BigDecimal amount) Transfers an amount of a token to an address
RadixApplicationAPI.Result	sendTokens(RRI token, RadixAddress to, java.math.BigDecimal amount, byte[] attachment) Transfers an amount of tokens with an attachment to an address
RadixApplicationAPI.Result	sendTokens(RRI token, RadixAddress to, java.math.BigDecimal amount, java.lang.String message) Transfers an amount of a token with a message attachment to an address
RadixApplicationAPI.Result	sendTokens(RRI token, RadixAddress from, RadixAddress to, java.math.BigDecimal amount) Transfers an amount of tokens to an address
RadixApplicationAPI.Result	sendTokens(RRI token, RadixAddress from, RadixAddress to, java.math.BigDecimal amount, byte[] attachment) Transfers an amount of a token with a data attachment to an address with a unique property meaning that no other transaction can be executed with the same unique bytes
RadixApplicationAPI.Result	submitAtom(Atom atom) Low level call to submit an atom into the network.
RadixApplicationAPI.Result	submitAtom(Atom atom, boolean completeOnStoreOnly) Low level call to submit an atom into the network.
RadixApplicationAPI.Result	submitAtom(Atom atom, boolean completeOnStoreOnly, RadixNode originNode) Low level call to submit an atom into the network.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static RadixApplicationAPI create(BootstrapConfig bootstrap,
                                         RadixIdentity identity)

Creates an API with the default actions and reducers

Parameters:

identity - the identity of user of API

Returns:

an api instance

defaultBuilder

public static RadixApplicationAPI.RadixApplicationAPIBuilder defaultBuilder()

Creates a default API builder with the default actions and reducers without an identity

Returns:

an api builder instance

getPublicKey

public ECPublicKey getPublicKey()

Retrieve the user's public key

Returns:

the user's public key

getIdentity

public RadixIdentity getIdentity()

Retrieve the user's key identity

Returns:

the user's identity

getAddress

public RadixAddress getAddress()

Retrieve the user's address

Returns:

the current user's address

getAddress

public RadixAddress getAddress(ECPublicKey publicKey)

Retrieve the address for the current universe given a public key

Returns:

an address based on the current universe and a given public key

pull

public io.reactivex.disposables.Disposable pull()

Idempotent method which prefetches atoms in user's account TODO: what to do when no puller available

Returns:

Disposable to dispose to stop pulling

pull

public io.reactivex.disposables.Disposable pull(RadixAddress address)

Idempotent method which prefetches atoms in an address TODO: what to do when no puller available

Parameters:

address - the address to pull atoms from

Returns:

Disposable to dispose to stop pulling

pullOnce

public io.reactivex.Completable pullOnce(RadixAddress address)

Retrieves atoms until the node returns a synced message.

Parameters:

address - the address to pull atoms for

Returns:

a cold completable which on subscribe pulls atoms from a source

getNativeTokenRef

public RRI getNativeTokenRef()

Returns the native Token Reference found in the genesis atom

Returns:

the native token reference

observeActions

public <T> io.reactivex.Observable<T> observeActions(java.lang.Class<T> actionClass,
                                                     RadixAddress address)

Returns a never ending stream of actions performed at a given address with the given Atom Store. pull() must be called to continually retrieve the latest actions.

Type Parameters:

T - the Action class

Parameters:

actionClass - the Action class

address - the address to retrieve the state of

Returns:

a cold observable of the actions at the given address

observeState

public <T extends ApplicationState> io.reactivex.Observable<T> observeState(java.lang.Class<T> stateClass,
                                                                            RadixAddress address)

Returns a never ending stream of a state of a given address with the given Atom store. pull() must be called to continually retrieve the latest state.

Type Parameters:

T - the ApplicationState class

Parameters:

stateClass - the ApplicationState class

address - the address to retrieve the state of

Returns:

a hot observable of a state of the given address

observeTokenDefs

public io.reactivex.Observable<TokenDefinitionsState> observeTokenDefs(RadixAddress address)

Returns a stream of the latest state of token definitions at a given address

Parameters:

address - the address of the account to check

Returns:

a cold observable of the latest state of token definitions

observeTokenDefs

public io.reactivex.Observable<TokenDefinitionsState> observeTokenDefs()

Returns a stream of the latest state of token definitions at the user's address

Returns:

a cold observable of the latest state of token definitions

observeTokenDef

public io.reactivex.Observable<TokenState> observeTokenDef(RRI tokenRRI)

Returns a stream of the latest state of a given token

Returns:

a cold observable of the latest state of the token

getTokenDef

public TokenState getTokenDef(RRI tokenRRI)

Retrieve the token state of the given rri

Returns:

the token state of the rri

observeMessages

public io.reactivex.Observable<DecryptedMessage> observeMessages()

Returns a never ending stream of messages stored at the current address. pull() must be called to continually retrieve the latest messages.

Returns:

a cold observable of the messages at the current address

observeMessages

public io.reactivex.Observable<DecryptedMessage> observeMessages(RadixAddress address)

Returns a never ending stream of messages stored at a given address. pull() must be called to continually retrieve the latest messages.

Parameters:

address - the address to retrieve the messages from

Returns:

a cold observable of the messages at the given address

sendMessage

public RadixApplicationAPI.Result sendMessage(byte[] data,
                                              boolean encrypt)

Sends a message to one's self

Parameters:

data - the message to send

encrypt - if true, encrypts the message with a encrypted private key

Returns:

result of the send message execution

sendMessage

public RadixApplicationAPI.Result sendMessage(RadixAddress toAddress,
                                              byte[] data,
                                              boolean encrypt)

Sends a message from the current address to another address

Parameters:

toAddress - the address to send the message to

data - the message to send

encrypt - if true, encrypts the message with an encrypted private key

Returns:

result of the send message execution

observeTokenTransfers

public io.reactivex.Observable<TokenTransfer> observeTokenTransfers()

Returns a never ending stream of token transfers stored at the current address. pull() must be called to continually retrieve the latest transfers.

Returns:

a cold observable of the token transfers at the current address

observeTokenTransfers

public io.reactivex.Observable<TokenTransfer> observeTokenTransfers(RadixAddress address)

Returns a never ending stream of token transfers stored at a given address. pull() must be called to continually retrieve the latest transfers.

Parameters:

address - the address to retrieve the token transfers from

Returns:

a cold observable of the token transfers at the given address

getBalances

public java.util.Map<RRI,java.math.BigDecimal> getBalances()

Retrieve the balances of the current address from the current atom store.

Returns:

map of balances

observeBalances

public io.reactivex.Observable<java.util.Map<RRI,java.math.BigDecimal>> observeBalances(RadixAddress address)

Returns a stream of the latest balances at a given address. pull() must be called to continually retrieve the latest balances.

Returns:

a cold observable of the latest balances at an address

observeBalance

public io.reactivex.Observable<java.math.BigDecimal> observeBalance(RRI tokenRRI)

Returns a stream of the latest balances at the current address pull() must be called to continually retrieve the latest balances.

Returns:

a cold observable of the latest balances at the current address

observeBalance

public io.reactivex.Observable<java.math.BigDecimal> observeBalance(RadixAddress address,
                                                                    RRI token)

Returns a stream of the latest balance of a given token at a given address pull() must be called to continually retrieve the latest balance.

Returns:

a cold observable of the latest balance of a token at a given address

createMultiIssuanceToken

public RadixApplicationAPI.Result createMultiIssuanceToken(RRI tokenRRI,
                                                           java.lang.String name)

Creates a multi-issuance token registered into the user's account with zero initial supply, 10^-18 granularity and no description.

Parameters:

tokenRRI - The symbol of the token to create

name - The name of the token to create

Returns:

result of the transaction

createMultiIssuanceToken

public RadixApplicationAPI.Result createMultiIssuanceToken(RRI tokenRRI,
                                                           java.lang.String name,
                                                           java.lang.String description)

Creates a multi-issuance token registered into the user's account with zero initial supply and 10^-18 granularity

Parameters:

tokenRRI - The symbol of the token to create

name - The name of the token to create

description - A description of the token

Returns:

result of the transaction

createFixedSupplyToken

public RadixApplicationAPI.Result createFixedSupplyToken(RRI tokenRRI,
                                                         java.lang.String name,
                                                         java.lang.String description,
                                                         java.math.BigDecimal supply)

Creates a fixed-supply token registered into the user's account with 10^-18 granularity

Parameters:

tokenRRI - The symbol of the token to create

name - The name of the token to create

description - A description of the token

supply - The supply of the created token

Returns:

result of the transaction

createToken

public RadixApplicationAPI.Result createToken(RRI tokenRRI,
                                              java.lang.String name,
                                              java.lang.String description,
                                              java.math.BigDecimal initialSupply,
                                              java.math.BigDecimal granularity,
                                              CreateTokenAction.TokenSupplyType tokenSupplyType)

Creates a token registered into the user's account

Parameters:

tokenRRI - The symbol of the token to create

name - The name of the token to create

description - A description of the token

initialSupply - The initial amount of supply for this token

granularity - The least multiple of subunits per transaction for this token

tokenSupplyType - The type of supply for this token: Fixed or Mutable

Returns:

result of the transaction

mintTokens

public RadixApplicationAPI.Result mintTokens(RRI token,
                                             java.math.BigDecimal amount)

Mints an amount of new tokens into the user's account

Parameters:

token - The symbol of the token to mint

amount - The amount to mint

Returns:

result of the transaction

burnTokens

public RadixApplicationAPI.Result burnTokens(RRI token,
                                             java.math.BigDecimal amount)

Burns an amount of tokens in the user's account

Parameters:

token - The symbol of the token to mint

amount - The amount to mint

Returns:

result of the transaction

sendTokens

public RadixApplicationAPI.Result sendTokens(RRI token,
                                             RadixAddress to,
                                             java.math.BigDecimal amount)

Transfers an amount of a token to an address

Parameters:

to - the address to transfer tokens to

amount - the amount and token type

Returns:

result of the transaction

sendTokens

public RadixApplicationAPI.Result sendTokens(RRI token,
                                             RadixAddress to,
                                             java.math.BigDecimal amount,
                                             @Nullable
                                             java.lang.String message)

Transfers an amount of a token with a message attachment to an address

Parameters:

to - the address to transfer tokens to

amount - the amount and token type

message - message to be encrypted and attached to transfer

Returns:

result of the transaction

sendTokens

public RadixApplicationAPI.Result sendTokens(RRI token,
                                             RadixAddress to,
                                             java.math.BigDecimal amount,
                                             @Nullable
                                             byte[] attachment)

Transfers an amount of tokens with an attachment to an address

Parameters:

to - the address to send tokens to

amount - the amount and token type

attachment - the data attached to the transaction

Returns:

result of the transaction

sendTokens

public RadixApplicationAPI.Result sendTokens(RRI token,
                                             RadixAddress from,
                                             RadixAddress to,
                                             java.math.BigDecimal amount)

Transfers an amount of tokens to an address

Parameters:

to - the address to send tokens to

amount - the amount and token type

Returns:

result of the transaction

sendTokens

public RadixApplicationAPI.Result sendTokens(RRI token,
                                             RadixAddress from,
                                             RadixAddress to,
                                             java.math.BigDecimal amount,
                                             @Nullable
                                             byte[] attachment)

Transfers an amount of a token with a data attachment to an address with a unique property meaning that no other transaction can be executed with the same unique bytes

Parameters:

to - the address to send tokens to

amount - the amount and token type

attachment - the data attached to the transaction

Returns:

result of the transaction

execute

public RadixApplicationAPI.Result execute(Action action)

Immediately executes a user action onto the ledger. Note that this method is NOT idempotent.

Parameters:

action - action to execute

Returns:

results of the execution

execute

public RadixApplicationAPI.Result execute(Action action,
                                          RadixNode originNode)

Immediately executes a user action onto the ledger. Note that this method is NOT idempotent.

Parameters:

action - action to execute

originNode - node to submit action to

Returns:

results of the execution

buildAtomWithFee

public UnsignedAtom buildAtomWithFee(java.util.List<ParticleGroup> particleGroups)

Returns an unsigned atom with the appropriate fees given a list of particle groups to compose the atom.

Parameters:

particleGroups - particle groups to include in atom

Returns:

unsigned atom with appropriate fees

createTransaction

public RadixApplicationAPI.Transaction createTransaction()

Create a new transaction which is based off of the current data in the atom store.

Returns:

a new transaction

submitAtom

public RadixApplicationAPI.Result submitAtom(Atom atom,
                                             boolean completeOnStoreOnly,
                                             RadixNode originNode)

Low level call to submit an atom into the network.

Parameters:

atom - atom to submit

completeOnStoreOnly - if true, result will only complete on a store event

Returns:

the result of the submission

submitAtom

public RadixApplicationAPI.Result submitAtom(Atom atom,
                                             boolean completeOnStoreOnly)

Low level call to submit an atom into the network.

Parameters:

atom - atom to submit

completeOnStoreOnly - if true, result will only complete on a store event

Returns:

the result of the submission

submitAtom

public RadixApplicationAPI.Result submitAtom(Atom atom)

Low level call to submit an atom into the network. Result will complete on the first STORED event.

Parameters:

atom - atom to submit

Returns:

the result of the submission

getAtomStore

public AtomStore getAtomStore()

Retrieve the atom store used by the API

Returns:

the atom store

discoverNodes

public void discoverNodes()

Dispatches a discovery request, the result of which would be viewable via getNetworkState()

getNetworkState

public io.reactivex.Observable<RadixNetworkState> getNetworkState()

Get a stream of updated network states as they occur.

Returns:

a hot observable of the current network state

getNetworkActions

public io.reactivex.Observable<RadixNodeAction> getNetworkActions()

Low level call to retrieve the actions occurring at the network level.

Returns:

a hot observable of network actions as they occur