Package convex.java

Class Convex

java.lang.Object

convex.java.Convex

public class Convex
extends Object

This class represents a remote client connection to the Convex Network, which can connect to any peer server that supports the REST Client API, e.g. the one at 'https://convex.world' Although this class can be used concurrently from multiple threads, it is strongly recommended to avoid executing transactions that use the same the same Account from multiple threads because each transaction requires incrementing a "sequence number" that may become mismatched if concurrent transactions are submitted. Read-only actions (e.g. queries) do not have this limitation.

Method Summary

Modifier and Type	Method	Description
static Convex	connect(String peerServerURL)	Connect to Convex network with a given peer URL.
static Convex	connect(String peerServerURL, Address address, AKeyPair keyPair)	Connect to Convex network with a given peer URL, address and keypair.
Address	createAccount(AKeyPair keyPair)	Request creation of a new Account using the given key pair
Map<String,Object>	faucet(Address address, long requestedAmount)	Request funds from the test network via the Faucet API.
Address	getAddress()	Gets the Address associated with this Convex client instance.
AKeyPair	getKeyPair()	Gets the key pair associated with this Convex connection instance.
Long	getSequence()	Gets the current sequence number for this account.
Map<String,Object>	query(String code)	Query using specific source code
Map<String,Object>	queryAccount()	Query account details on the network for the currently set account
Map<String,Object>	queryAccount(long address)	Query account details on the network.
Map<String,Object>	queryAccount(Address address)	Query account details on the network.
CompletableFuture<Map<String,Object>>	queryAccountAsync(Address address)	Query account details on the network asynchronously.
CompletableFuture<Map<String,Object>>	queryAsync(String code)	Query using specific source code
Long	queryBalance()	Query the current Convex coin balance of the current Account
Long	queryBalance(Address address)	Query the current Convex coin balance of a given Address
Long	querySequence()	Query the current sequence number of the current Account set.
Long	querySequence(Address address)	Query the current sequence number of a given Address
void	setAddress(Address addr)	Sets the Account Address for this Client instance.
void	setKeyPair(AKeyPair keyPair)	Sets this connection instance to use the specified keypair
Map<String,Object>	transact(String code)	Submit a transaction using specific source code
CompletableFuture<Map<String,Object>>	transactAsync(String code)	Asynchronously execute a transaction using the current Account.
long	updateSequence(long seq)	Updates the sequence number for this account, to the maximum of the last observed sequence number and the parameter provided.
Address	useNewAccount()	Create a new account ready for use, creating a new Ed25519 key pair.
Address	useNewAccount(long fundsRequested)	Create a new account ready for use, creating a new Ed25519 key pair.

Methods inherited from class java.lang.Object

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

Method Details

connect

public static Convex connect(String peerServerURL,
 Address address,
 AKeyPair keyPair)

Connect to Convex network with a given peer URL, address and keypair.

Parameters:

peerServerURL - Peer server address, e.g. "https://convex.world"

address - Address to use for this connection

keyPair - Key pair to use for this connection

Returns:

New Convex instance with supplied connection details

connect

public static Convex connect(String peerServerURL)

Connect to Convex network with a given peer URL. No Address or Keypair is set by default: user will either need to provide these later or perform an action that creates a new account (e.g. `useNewAccount`)

Parameters:

peerServerURL - Peer server address, e.g. "https://convex.world"

Returns:

New Convex instance with supplied connection details

getSequence

public Long getSequence()

Gets the current sequence number for this account. The sequence number is the last valid transaction submitted, and will be 0 for any new accounts. If the sequence number is not known for the current connection, attempts to query the Account set for the Address of the current connection.

Returns:

Sequence number for the current account

updateSequence

public long updateSequence(long seq)

Updates the sequence number for this account, to the maximum of the last observed sequence number and the parameter provided.

Parameters:

seq - Sequence number to set, or or the current sequence number if higher

Returns:

Sequence number for the current account

getAddress

public Address getAddress()

Gets the Address associated with this Convex client instance. May be null

Returns:

Address of current account in use, or null if not set

getKeyPair

public AKeyPair getKeyPair()

Gets the key pair associated with this Convex connection instance. May be null. A correct key pair is required to submit any transactions for an Account.

Returns:

Key pair for current account in use, or null if not set

setKeyPair

public void setKeyPair(AKeyPair keyPair)

Sets this connection instance to use the specified keypair

Parameters:

keyPair - Key pair to use for this connection.

setAddress

public void setAddress(Address addr)

Sets the Account Address for this Client instance. Future requests will use this Address unless otherwise specified. NOTE: In order to transact, you may also need to set the KeyPair to be correct for the new Address

Parameters:

addr - New Address to use

useNewAccount

public Address useNewAccount()

Create a new account ready for use, creating a new Ed25519 key pair. This Convex connection instance will be set to use the new account.

Returns:

The Address of the new Account

useNewAccount

public Address useNewAccount(long fundsRequested)

Create a new account ready for use, creating a new Ed25519 key pair. This Convex connection instance will be set to use the new account. Also requests funds for the new account from the Faucet

Parameters:

fundsRequested - Funds requested from faucet

Returns:

The Address of the new Account

createAccount

public Address createAccount(AKeyPair keyPair)

Request creation of a new Account using the given key pair

Parameters:

keyPair - Key pair to use for new account

Returns:

Address of new account

query

public Map<String,Object> query(String code)

Query using specific source code

Parameters:

code - Source code in Convex Lisp

Returns:

Result of query, as parsed JSON Object from query response

querySequence

public Long querySequence()

Query the current sequence number of the current Account set.

Returns:

Sequence number of Account, or null if the Account does not exist.

querySequence

public Long querySequence(Address address)

Query the current sequence number of a given Address

Parameters:

address - address to query

Returns:

Sequence number of Account, or null if the Account does not exist.

queryBalance

public Long queryBalance()

Query the current Convex coin balance of the current Account

Returns:

Coin Balance of Account, or null if the Account does not exist.

queryBalance

public Long queryBalance(Address address)

Query the current Convex coin balance of a given Address

Parameters:

address - Address to query

Returns:

Coin Balance of Account, or null if the Account does not exist.

queryAccount

public Map<String,Object> queryAccount(Address address)

Query account details on the network.

Parameters:

address - Address to query

Returns:

Result of query, as parsed JSON Object from query response, or null if account does not exist

queryAccount

public Map<String,Object> queryAccount(long address)

Query account details on the network.

Parameters:

address - Address to query

Returns:

Result of query, as parsed JSON Object from query response, or null if account does not exist

queryAccount

public Map<String,Object> queryAccount()

Query account details on the network for the currently set account

Returns:

Result of query, as parsed JSON Object from query response

faucet

public Map<String,Object> faucet(Address address,
 long requestedAmount)

Request funds from the test network via the Faucet API.

Parameters:

address - Destination address to get requested funds

requestedAmount - Requested amount of funds in CC

Returns:

Result of query, as parsed JSON Object from query response

queryAccountAsync

public CompletableFuture<Map<String,Object>> queryAccountAsync(Address address)

Query account details on the network asynchronously.

Parameters:

address - Address to query

Returns:

Result of query, as Future for parsed JSON Object from query response

transact

public Map<String,Object> transact(String code)

Submit a transaction using specific source code

Parameters:

code - Source code in Convex Lisp

Returns:

Result of query, as parsed JSON Object from query response

transactAsync

public CompletableFuture<Map<String,Object>> transactAsync(String code)

Asynchronously execute a transaction using the current Account. Requires a valid key pair to be set up.

Parameters:

code - Code to execute

Returns:

Future for the transaction result.

queryAsync

public CompletableFuture<Map<String,Object>> queryAsync(String code)

Query using specific source code

Parameters:

code - Source code in Convex Lisp

Returns:

Future to be completed with result of query, as parsed JSON Object from query response