Module io.hotmoka.nodes
Package io.hotmoka.nodes

Interface Node

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
AbstractNode
public interface Node extends AutoCloseable
A node of the Hotmoka network, that provides the storage facilities for the execution of Takamaka code. Calls to code in the node can be added, run or posted. Posted calls are executed, eventually, and their value can be retrieved through the future returned by the calls. Added calls are shorthand for posting a call and waiting until the value of their future is available. Run calls are only available for view methods, without side-effects. They execute immediately and never modify the store of the node.

  • Method Details

    • getTakamakaCode

      TransactionReference getTakamakaCode() throws NoSuchElementException
      Yields the reference, in the store of the node, where the base Takamaka base classes are installed. If this node has some form of commit, then this method returns a reference only if the installation of the jar with the Takamaka base classes has been already committed.
      Throws:
      NoSuchElementException - if the node has not been initialized yet

    • getManifest

      StorageReference getManifest() throws NoSuchElementException
      Yields the manifest installed in the store of the node. The manifest is an object of type io.takamaka.code.system.Manifest that contains some information about the node, useful for the users of the node. If this node has some form of commit, then this method returns a reference only if the installation of the manifest has been already committed.
      Returns:
      the reference to the node
      Throws:
      NoSuchElementException - if no manifest has been set for this node

    • getNodeInfo

      NodeInfo getNodeInfo()
      Yields node-specific information about the node. This is likely different for each node of the network, hence are out of consensus.
      Returns:
      the node-specific information about the node

    • getClassTag

      ClassTag getClassTag(StorageReference object) throws NoSuchElementException
      Yields the class tag of the object with the given storage reference. If this method succeeds and this node has some form of commit, then the transaction of the storage reference has been definitely committed in this node. A node is allowed to keep in store all, some or none of the objects. Hence, this method might fail to find the class tag although the object previously existed in store.
      Parameters:
      object - the storage reference of the object
      Returns:
      the class tag, if any
      Throws:
      NoSuchElementException - if there is no object with that reference or if the class tag could not be found

    • getState

      Stream<Update> getState(StorageReference object) throws NoSuchElementException
      Yields the current state of the object at the given storage reference. If this method succeeds and this node has some form of commit, then the transaction of the storage reference has been definitely committed in this node. A node is allowed to keep in store all, some or none of the objects. Hence, this method might fail to find the state of the object although the object previously existed in store.
      Parameters:
      object - the storage reference of the object
      Returns:
      the last updates of all its instance fields; these updates include the class tag update for the object
      Throws:
      NoSuchElementException - if there is no object with that reference

    • getNameOfSignatureAlgorithmForRequests

      String getNameOfSignatureAlgorithmForRequests()
      Yields the name of the algorithm used to sign requests with this node.
      Returns:
      the name of the algorithm

    • getRequest

      TransactionRequest<?> getRequest(TransactionReference reference) throws NoSuchElementException
      Yields the request that generated the transaction with the given reference. If this node has some form of commit, then this method can only succeed when the transaction has been definitely committed in this node. Nodes are allowed to keep in store all, some or none of the requests that they received during their lifetime.
      Parameters:
      reference - the reference of the transaction
      Returns:
      the request
      Throws:
      NoSuchElementException - if there is no request with that reference

    • getResponse

      TransactionResponse getResponse(TransactionReference reference) throws TransactionRejectedException, NoSuchElementException
      Yields the response generated for the request for the given transaction. If this node has some form of commit, then this method can only succeed or yield a TransactionRejectedException only when the transaction has been definitely committed in this node. Nodes are allowed to keep in store all, some or none of the responses that they computed during their lifetime.
      Parameters:
      reference - the reference of the transaction
      Returns:
      the response
      Throws:
      TransactionRejectedException - if there is a request for that transaction but it failed with this exception
      NoSuchElementException - if there is no request, and hence no response, with that reference

    • getPolledResponse

      TransactionResponse getPolledResponse(TransactionReference reference) throws TransactionRejectedException, TimeoutException, InterruptedException
      Waits until a transaction has been committed, or until its delivering fails. If this method succeeds and this node has some form of commit, then the transaction has been definitely committed. Nodes are allowed to keep in store all, some or none of the responses computed during their lifetime. Hence, this method might time out also when a response has been computed in the past for the transaction of reference, but it has not been kept in store.
      Parameters:
      reference - the reference of the transaction
      Returns:
      the response computed for request
      Throws:
      TransactionRejectedException - if the request failed to be committed, because of this exception
      TimeoutException - if the polling delay has expired but the request did not get committed
      InterruptedException - if the current thread has been interrupted while waiting for the response

    • addJarStoreInitialTransaction

      TransactionReference addJarStoreInitialTransaction(JarStoreInitialTransactionRequest request) throws TransactionRejectedException
      Expands the store of this node with a transaction that installs a jar in it. It has no caller and requires no gas. The goal is to install, in the node, some basic jars that are likely needed as dependencies by future jars. For instance, the jar containing the basic contract classes. This installation have special privileges, such as that of installing packages in io.takamaka.code.lang.*.
      Parameters:
      request - the transaction request
      Returns:
      the reference to the transaction, that can be used to refer to the jar in a class path or as future dependency of other jars
      Throws:
      TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged

    • addGameteCreationTransaction

      StorageReference addGameteCreationTransaction(GameteCreationTransactionRequest request) throws TransactionRejectedException
      Expands the store of this node with a transaction that creates a gamete, that is, a red/green externally owned contract with the given initial amount of coins, of class io.takamaka.code.lang.Gamete. This transaction has no caller and requires no gas.
      Parameters:
      request - the transaction request
      Returns:
      the reference to the freshly created gamete
      Throws:
      TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged

    • addInitializationTransaction

      void addInitializationTransaction(InitializationTransactionRequest request) throws TransactionRejectedException
      Expands the store of this node with a transaction that marks the node as initialized and installs its manifest. After this transaction, no more initial transactions can be executed on the node.
      Parameters:
      request - the transaction request
      Throws:
      TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged

    • addJarStoreTransaction

      TransactionReference addJarStoreTransaction(JarStoreTransactionRequest request) throws TransactionRejectedException, TransactionException
      Expands the store of this node with a transaction that installs a jar in it.
      Parameters:
      request - the transaction request
      Returns:
      the reference to the transaction, that can be used to refer to the jar in a class path or as future dependency of other jars
      Throws:
      TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged
      TransactionException - if the transaction could be executed and the store of the node has been expanded with a failed transaction

    • addConstructorCallTransaction

      StorageReference addConstructorCallTransaction(ConstructorCallTransactionRequest request) throws TransactionRejectedException, TransactionException, CodeExecutionException
      Expands this node's store with a transaction that runs a constructor of a class.
      Parameters:
      request - the request of the transaction
      Returns:
      the created object, if the constructor was successfully executed, without exception
      Throws:
      TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged
      CodeExecutionException - if the transaction could be executed and the node has been expanded with a failed transaction, because of an exception in the user code in blockchain, that is allowed to be thrown by the constructor
      TransactionException - if the transaction could be executed and the node has been expanded with a failed transaction, because of an exception outside the user code in blockchain, or not allowed to be thrown by the constructor

    • addInstanceMethodCallTransaction

      StorageValue addInstanceMethodCallTransaction(InstanceMethodCallTransactionRequest request) throws TransactionRejectedException, TransactionException, CodeExecutionException
      Expands this node's store with a transaction that runs an instance method of an object already in this node's store.
      Parameters:
      request - the transaction request
      Returns:
      the result of the call, if the method was successfully executed, without exception. If the method is declared to return void, this result will be null
      Throws:
      TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged
      CodeExecutionException - if the transaction could be executed and the node has been expanded with a failed transaction, because of an exception in the user code in blockchain, that is allowed to be thrown by the method
      TransactionException - if the transaction could be executed and the node has been expanded with a failed transaction, because of an exception outside the user code in blockchain, or not allowed to be thrown by the method

    • addStaticMethodCallTransaction

      StorageValue addStaticMethodCallTransaction(StaticMethodCallTransactionRequest request) throws TransactionRejectedException, TransactionException, CodeExecutionException
      Expands this node's store with a transaction that runs a static method of a class in this node.
      Parameters:
      request - the transaction request
      Returns:
      the result of the call, if the method was successfully executed, without exception. If the method is declared to return void, this result will be null
      Throws:
      TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged
      CodeExecutionException - if the transaction could be executed and the node has been expanded with a failed transaction, because of an exception in the user code in blockchain, that is allowed to be thrown by the method
      TransactionException - if the transaction could be executed and the node has been expanded with a failed transaction, because of an exception outside the user code in blockchain, or not allowed to be thrown by the method

    • runInstanceMethodCallTransaction

      StorageValue runInstanceMethodCallTransaction(InstanceMethodCallTransactionRequest request) throws TransactionRejectedException, TransactionException, CodeExecutionException
      Runs an instance @@View method of an object already in this node's store. The node's store is not expanded, since the execution of the method has no side-effects.
      Parameters:
      request - the transaction request
      Returns:
      the result of the call, if the method was successfully executed, without exception
      Throws:
      TransactionRejectedException - if the transaction could not be executed
      CodeExecutionException - if the transaction could be executed but led to an exception in the user code in blockchain, that is allowed to be thrown by the method
      TransactionException - if the transaction could be executed but led to an exception outside the user code in blockchain, or that is not allowed to be thrown by the method

    • runStaticMethodCallTransaction

      StorageValue runStaticMethodCallTransaction(StaticMethodCallTransactionRequest request) throws TransactionRejectedException, TransactionException, CodeExecutionException
      Runs a static @@View method of a class in this node. The node's store is not expanded, since the execution of the method has no side-effects.
      Parameters:
      request - the transaction request
      Returns:
      the result of the call, if the method was successfully executed, without exception
      Throws:
      TransactionRejectedException - if the transaction could not be executed
      CodeExecutionException - if the transaction could be executed but led to an exception in the user code in blockchain, that is allowed to be thrown by the method
      TransactionException - if the transaction could be executed but led to an exception outside the user code in blockchain, or that is not allowed to be thrown by the method

    • postJarStoreTransaction

      Node.JarSupplier postJarStoreTransaction(JarStoreTransactionRequest request) throws TransactionRejectedException
      Posts a transaction that expands the store of this node with a transaction that installs a jar in it.
      Parameters:
      request - the transaction request
      Returns:
      the future holding the reference to the transaction where the jar has been installed
      Throws:
      TransactionRejectedException - if the transaction could not be posted

    • postConstructorCallTransaction

      Node.CodeSupplier<StorageReference> postConstructorCallTransaction(ConstructorCallTransactionRequest request) throws TransactionRejectedException
      Posts a transaction that runs a constructor of a class in this node.
      Parameters:
      request - the request of the transaction
      Returns:
      the future holding the result of the computation
      Throws:
      TransactionRejectedException - if the transaction could not be posted

    • postInstanceMethodCallTransaction

      Node.CodeSupplier<StorageValue> postInstanceMethodCallTransaction(InstanceMethodCallTransactionRequest request) throws TransactionRejectedException
      Posts a transaction that runs an instance method of an object already in this node's store.
      Parameters:
      request - the transaction request
      Returns:
      the future holding the result of the transaction
      Throws:
      TransactionRejectedException - if the transaction could not be posted

    • postStaticMethodCallTransaction

      Node.CodeSupplier<StorageValue> postStaticMethodCallTransaction(StaticMethodCallTransactionRequest request) throws TransactionRejectedException
      Posts a request that runs a static method of a class in this node.
      Parameters:
      request - the transaction request
      Returns:
      the future holding the result of the transaction
      Throws:
      TransactionRejectedException - if the transaction could not be posted

    • subscribeToEvents

      Node.Subscription subscribeToEvents(StorageReference creator, BiConsumer<StorageReference,StorageReference> handler)
      Subscribes the given handler for events with the given creator.
      Parameters:
      creator - the creator of the events that will be forwarded to the handler; if this is null, all events will be forwarded to the handler
      handler - a handler that gets executed when an event with the given creator occurs; a handler can be subscribed to more creators; for each event, it receives its creator and the event itself
      Returns:
      the subscription, that can be used later to stop event handling with handler