Module convex.peer
Package convex.api

Class Convex

java.lang.Object
convex.api.Convex
All Implemented Interfaces:
AutoCloseable
Direct Known Subclasses:
ConvexDirect, ConvexLocal, ConvexRemote
public abstract class Convex extends Object implements AutoCloseable
Class providing a client API to the Convex network. An instance of the type Convex manages a stateful client connection to the Convex network that can issue transactions both synchronously and asynchronously via a peer. This can be used by both peers and JVM-based clients. "I'm doing a (free) operating system (just a hobby, won't be big and professional like gnu)" - Linus Torvalds

  • Field Details

    • timeout

      protected long timeout

    • keyPair

      protected AKeyPair keyPair
      Key pair for this Client

    • address

      protected Address address
      Current Address for this Client

    • preCompile

      protected boolean preCompile
      Determines if transactions should be pre-compiled.

    • sequence

      protected Long sequence
      Sequence number for this client, or null if not yet known. Used to number new transactions if not otherwise specified.

    • idCounter

      protected long idCounter
      Counter for outgoing message IDs. Used to give an ID to requests that expect a Result

  • Constructor Details

  • Method Details

    • connect

      public static Convex connect(Object host) throws IOException, TimeoutException, InterruptedException
      Attempts best possible connection
      Throws:
      TimeoutException
      IOException
      InterruptedException

    • connect

      public static ConvexRemote connect(InetSocketAddress hostAddress) throws IOException, TimeoutException, InterruptedException
      Creates an anonymous connection to a Peer, suitable for queries
      Parameters:
      hostAddress - Address of Peer
      Returns:
      New Convex client instance
      Throws:
      IOException - If IO Error occurs
      TimeoutException - If connection attempt times out
      InterruptedException

    • connect

      public static ConvexRemote connect(InetSocketAddress peerAddress, Address address, AKeyPair keyPair) throws IOException, TimeoutException, InterruptedException
      Create a Convex client by connecting to the specified Peer using the given key pair
      Parameters:
      peerAddress - Address of Peer
      address - Address of Account to use for Client
      keyPair - Key pair to use for client transactions
      Returns:
      New Convex client instance
      Throws:
      IOException - If connection fails due to IO error
      TimeoutException - If connection attempt times out
      InterruptedException

    • getNextID

      protected long getNextID()

    • setAddress

      public void setAddress(Address address)
      Sets the Address for this connection. This will be used for subsequent transactions and queries. User should also set a new keypair if a different keypair is required for the new Address.
      Parameters:
      address - Address to use

    • setAddress

      public void setAddress(Address address, AKeyPair kp)
      Sets the Address and Keypair for this connection. This will be used for subsequent transactions and queries.
      Parameters:
      address - Address to use
      kp - Keypair to use for the given Address

    • setKeyPair

      public void setKeyPair(AKeyPair kp)

    • setNextSequence

      public void setNextSequence(long nextSequence)

    • getSequence

      public long getSequence() throws ResultException, InterruptedException
      Gets the current sequence number for this Client, which is the sequence number of the last transaction observed for the current client's Account. Will attempt to acquire the sequence number from the network if not known. The next valid sequence number will be one higher than the result.
      Returns:
      Sequence number as a Long value (zero or positive)
      Throws:
      ResultException - If an error result occurs looking up sequence number
      InterruptedException

    • getSequence

      public long getSequence(Address addr) throws InterruptedException, ResultException
      Gets the current sequence number for an account, which is the sequence number of the last transaction observed for the Account. Will attempt to acquire the sequence number from the network if not known.
      Parameters:
      addr - Address for which to query the sequence number
      Returns:
      Sequence number as a Long value (zero or positive)
      Throws:
      InterruptedException
      ResultException

    • lookupSequence

      public long lookupSequence(Address origin) throws InterruptedException, ResultException
      Look up the sequence number for an account
      Parameters:
      origin - Account for which to check sequence
      Returns:
      Sequence number of account
      Throws:
      ResultException - If sequence number could not be obtained
      InterruptedException

    • maybeUpdateSequence

      protected void maybeUpdateSequence(SignedData<ATransaction> signed)
      Called after a transaction is submitted to update sequence (if possible)
      Parameters:
      value -

    • signData

      public <T extends ACell> SignedData<T> signData(T value)
      Signs a value on behalf of this client, using the currently assigned keypair.
      Type Parameters:
      T - Type of value to sign
      Parameters:
      value - Value to sign
      Returns:
      SignedData instance

    • createAccountSync

      public Address createAccountSync(AccountKey publicKey) throws InterruptedException, ResultException
      Creates a new account with the given public key
      Parameters:
      publicKey - Public key to set for the new account
      Returns:
      Address of account created
      Throws:
      ResultException - If account creation failed
      InterruptedException

    • createAccount

      public CompletableFuture<Address> createAccount(AccountKey publicKey)
      Creates a new account with the given public key
      Parameters:
      publicKey - Public key to set for the new account
      Returns:
      Address of account created

    • isConnected

      public abstract boolean isConnected()
      Checks if this Convex client instance has an open connection.
      Returns:
      true if connected, false otherwise

    • preCompile

      public CompletableFuture<Result> preCompile(ACell code)
      Pre-compiles code, compiling the given source to a CVM Op.
      Parameters:
      code - Code to execute
      Returns:
      A Future for the result of the compilation

    • transact

      public final CompletableFuture<Result> transact(ATransaction transaction)
      Submits a transaction to the Convex network, returning a future once the transaction has been successfully queued. Signs the transaction with the currently set key pair. Should be thread safe as long as multiple clients do not attempt to submit transactions for the same account concurrently. May block briefly if the send buffer is full.
      Parameters:
      transaction - Transaction to execute
      Returns:
      A Future for the result of the transaction

    • prepareTransaction

      public SignedData<ATransaction> prepareTransaction(ACell code) throws ResultException, InterruptedException
      Prepares a transaction for network submission - Pre-compiles if needed - Sets origin account to current address - Sets sequence number (if auto-sequencing is enabled) - Signs transaction with current key pair
      Parameters:
      code - Code to prepare as transaction
      Returns:
      Signed transaction ready to submit
      Throws:
      ResultException - If an error occurs preparing the transaction (e.g. failure to pre-compile)
      InterruptedException

    • prepareTransaction

      public SignedData<ATransaction> prepareTransaction(ATransaction transaction) throws ResultException, InterruptedException
      Prepares a transaction for network submission - Sets origin account if needed - Sets sequence number (if autosequencing is enabled) - Signs transaction with current key pair
      Parameters:
      transaction - Transaction to prepare
      Returns:
      Signed transaction ready to submit
      Throws:
      ResultException
      InterruptedException

    • transact

      public CompletableFuture<Result> transact(String code)
      Executes a transaction, compiling the given source code as an Invoke.
      Parameters:
      code - Code to execute
      Returns:
      A Future for the result of the transaction

    • transact

      public CompletableFuture<Result> transact(ACell code)
      Executes a transaction, compiling the given source code as an Invoke.
      Parameters:
      code - Code to execute
      Returns:
      A Future for the result of the transaction

    • transactSync

      public Result transactSync(String code) throws InterruptedException
      Executes a transaction, compiling the given source code as an Invoke.
      Parameters:
      code - Code to execute
      Returns:
      A Future for the result of the transaction
      Throws:
      InterruptedException - in case of interrupt while waiting

    • transact

      public abstract CompletableFuture<Result> transact(SignedData<ATransaction> signedTransaction)
      Submits a signed transaction to the Convex network, returning a Future once the transaction has been successfully queued. Updates cached sequence number on best effort basis.
      Parameters:
      signedTransaction - Signed transaction to execute
      Returns:
      A Future for the result of the transaction

    • transfer

      public CompletableFuture<Result> transfer(Address target, long amount)
      Submits a transfer transaction to the Convex network, returning a future once the transaction has been successfully queued.
      Parameters:
      target - Destination address for transfer
      amount - Amount of Convex Coins to transfer
      Returns:
      A Future for the result of the transaction

    • transferSync

      public Result transferSync(Address target, long amount) throws InterruptedException
      Submits a transfer transaction to the Convex network peer, and waits for confirmation of the result
      Parameters:
      target - Destination address for transfer
      amount - Amount of Convex Coins to transfer
      Returns:
      Result of the transaction
      Throws:
      InterruptedException - In case of interrupt

    • transactSync

      public Result transactSync(SignedData<ATransaction> transaction) throws InterruptedException
      Submits a transaction synchronously to the Convex network, returning a Result
      Parameters:
      transaction - Transaction to execute
      Returns:
      The result of the transaction
      Throws:
      InterruptedException - in case of interrupt

    • transactSync

      public final Result transactSync(ACell transaction) throws InterruptedException
      Submits a transaction synchronously to the Convex network, returning a Result
      Parameters:
      transaction - Transaction to execute
      Returns:
      The result of the transaction (may be an error)
      Throws:
      InterruptedException - in case of interrupt

    • transactSync

      public final Result transactSync(ACell transaction, long timeout) throws InterruptedException
      Submits a signed transaction synchronously to the Convex network, returning a Result
      Parameters:
      transaction - Transaction to execute
      timeout - Number of milliseconds for timeout
      Returns:
      The result of the transaction
      Throws:
      InterruptedException - if operation is interrupted

    • transactSync

      public Result transactSync(SignedData<ATransaction> signedTransaction, long timeout) throws InterruptedException
      Submits a signed transaction synchronously to the Convex network, returning a Result
      Parameters:
      signedTransaction - Transaction to execute
      timeout - Number of milliseconds for timeout
      Returns:
      The Result of the transaction, may be an error
      Throws:
      InterruptedException - if operation is interrupted

    • query

      public CompletableFuture<Result> query(ACell query)
      Submits a query to the Convex network, returning a Future once the query has been successfully queued.
      Parameters:
      query - Query to execute, as a Form or Op
      Returns:
      A Future for the result of the query

    • query

      public CompletableFuture<Result> query(String query)
      Submits a query to the Convex network, returning a Future once the query has been successfully queued.
      Parameters:
      query - Query to execute, as String containing one or more forms
      Returns:
      A Future for the result of the query

    • messageRaw

      public abstract CompletableFuture<Result> messageRaw(Blob message)
      Submits raw message data to the Convex network, returning a Future for any Result
      Parameters:
      message - Raw message data
      Returns:
      A Future for the result of the query

    • message

      public abstract CompletableFuture<Result> message(Message message)
      Submits a Message to the connected peer, returning a Future for any Result
      Parameters:
      message - Message data
      Returns:
      A Future for the Result of the query. May just be "Sent" if no other result expected, or an immediate error if sending failed.

    • resolve

      public CompletableFuture<ACell> resolve(String cnsName)
      Attempts to resolve a CNS name
      Parameters:
      cnsName - CNS name to resolve
      Returns:
      A Future for the resolved CNS value

    • acquire

      public <T extends ACell> CompletableFuture<T> acquire(Hash hash)
      Attempts to asynchronously acquire a complete persistent data structure for the given hash from the remote peer. Uses the current store configured for the calling thread.
      Parameters:
      hash - Hash of value to acquire.
      Returns:
      Future for the cell being acquired

    • acquire

      public abstract <T extends ACell> CompletableFuture<T> acquire(Hash hash, AStore store)
      Attempts to acquire a complete persistent data structure for the given hash from the connected peer. Uses the store provided as a destination.
      Parameters:
      hash - Hash of value to acquire.
      store - Store to acquire the persistent data to.
      Returns:
      Future for the Cell being acquired. May fail exceptionally or timeout if the given data cannot be acquired (most likely missing from the peer's store)

    • requestStatusSync

      public Result requestStatusSync(long timeoutMillis) throws InterruptedException
      Request status using a sync operation. This request will automatically get any missing data with the status request
      Parameters:
      timeoutMillis - Milliseconds to wait for request timeout
      Returns:
      Status Vector from target Peer
      Throws:
      InterruptedException

    • requestStatusSync

      public Result requestStatusSync() throws InterruptedException
      Throws:
      InterruptedException

    • getTimeout

      protected long getTimeout()

    • requestStatus

      public abstract CompletableFuture<Result> requestStatus()
      Submits a status request to the Convex network peer, returning a Future once the request has been successfully queued.
      Returns:
      A Future for the result of the requestStatus

    • requestChallenge

      public abstract CompletableFuture<Result> requestChallenge(SignedData<ACell> data)
      Request a challenge. This is request is made by any peer that needs to find out if another peer can be trusted.
      Parameters:
      data - Signed data to send to the peer for the challenge.
      Returns:
      A Future for the result of the requestChallenge

    • query

      public abstract CompletableFuture<Result> query(ACell query, Address address)
      Submits a query to the Convex network, returning a Future once the query has been successfully queued.
      Parameters:
      query - Query to execute, as a Form or Op
      address - Address to use for the query
      Returns:
      A Future for the result of the query

    • querySync

      public Result querySync(ACell query) throws InterruptedException
      Executes a query synchronously and waits for the Result
      Parameters:
      query - Query to execute. Map be a form or Op
      Returns:
      Result of synchronous query
      Throws:
      InterruptedException - In case of interrupt

    • querySync

      public Result querySync(String query) throws InterruptedException
      Executes a query synchronously and waits for the Result
      Parameters:
      query - Query to execute, as a String that contains one or more readable forms. Multiple forms will be wrapped in a `do` block
      Returns:
      Result of synchronous query
      Throws:
      InterruptedException - In case of interrupt while awaiting Result

    • querySync

      public Result querySync(ACell query, Address address) throws InterruptedException
      Executes a query synchronously and waits for the Result
      Parameters:
      query - Query to execute, as a Form or Op
      address - Address to use for the query
      Returns:
      Result of query
      Throws:
      InterruptedException - In case of interrupt while awaiting Result

    • querySync

      protected Result querySync(ACell query, Address address, long timeoutMillis) throws InterruptedException
      Executes a query synchronously and waits for the Result
      Parameters:
      query - Query to execute, as a Form or Op
      address - Address to use for the query
      timeoutMillis - Timeout to wait for query result. Will throw TimeoutException if not received in this time
      Returns:
      Result of query
      Throws:
      InterruptedException

    • getAccountKey

      public AccountKey getAccountKey()
      Returns the current AccountKey for the client using the API.
      Returns:
      AcountKey instance, or null if no keypair is set

    • getAccountKey

      public AccountKey getAccountKey(Address a) throws InterruptedException
      Returns the current AccountKey for the specified address. Performs a synchronous query
      Returns:
      AcountKey instance, or null if unavailable
      Throws:
      InterruptedException - In case of interrupt while awaiting Result

    • getAddress

      public Address getAddress()
      Returns the current Address for the client using the API.
      Returns:
      Address instance

    • close

      public abstract void close()
      Disconnects the client from the network, releasing any connection resources.
      Specified by:
      close in interface AutoCloseable

    • finalize

      public void finalize()
      Overrides:
      finalize in class Object

    • isAutoSequence

      protected boolean isAutoSequence()
      Determines if this Client is configured to automatically generate sequence numbers
      Returns:

    • setAutoSequence

      protected void setAutoSequence(boolean autoSequence)
      Configures auto-generation of sequence numbers
      Parameters:
      autoSequence - true to enable auto-sequencing, false otherwise

    • getBalance

      public Long getBalance() throws ResultException
      Query the balance for the current account
      Returns:
      Long balance in Convex coins,
      Throws:
      ResultException - If balance query fails

    • getBalance

      public Long getBalance(Address address) throws ResultException
      Throws:
      ResultException

    • connect

      public static ConvexLocal connect(Server server, Address address, AKeyPair keyPair)
      Connect to a local Server, using given address and keypair
      Parameters:
      server - Server to connect to
      address - Address to use
      keyPair - Keypair to use
      Returns:
      New Client Connection

    • connect

      public static ConvexLocal connect(Server server)
      Connect to a local Server, with no address and keypair set
      Parameters:
      server - Server to connect to
      Returns:
      New Client Connection

    • acquireState

      public CompletableFuture<State> acquireState()
      Gets the consensus state from the connected Peer. The acquired state will be a snapshot of the network global state as calculated by the Peer. SECURITY: Be aware that if this client instance is connected to an untrusted Peer, the Peer may lie about the latest state. If this is a security concern, the client should validate the consensus state independently.
      Returns:
      Future for consensus state

    • setTimeout

      public void setTimeout(long timeout)
      Sets the default timeout for this Convex client instance.
      Parameters:
      timeout - timeout in milliseconds. Set to 0 or negative for no timeout

    • toString

      public abstract String toString()
      Overrides:
      toString in class Object

    • getKeyPair

      public AKeyPair getKeyPair()
      Get the keypair for this Convex connection.
      Returns:
      Keypair or null if not set

    • getLocalServer

      public Server getLocalServer()
      Gets the local Server instance, or null if not a local connection
      Returns:
      Server instance (or null)

    • getHostAddress

      public abstract InetSocketAddress getHostAddress()
      Gets the remote address for this Convex client instance
      Returns:
      Socket address

    • isPreCompile

      public boolean isPreCompile()
      Returns:
      True if pre-compilation is enabled

    • setPreCompile

      public void setPreCompile(boolean preCompile)
      Sets the client connection pre-compilation mode. When enabled, any non-compiled CVM code is sent to the peer for compilation first (as a query) SECURITY: do not use if the target peer is untrusted, as it may be able to manipulate code during compilation. May be safe if the peer and the connection to it is trusted (e.g. a local peer)
      Parameters:
      preCompile - the preCompile to set

    • clearSequence

      public void clearSequence()
      Clears the sequence number cache for this client instance. Sequence number will be re-queried if required.

    • reconnect

      public abstract void reconnect() throws IOException, TimeoutException, InterruptedException
      Throws:
      IOException
      TimeoutException
      InterruptedException