Package avm

Class Blockchain

  • public final class Blockchain
extends java.lang.Object
    Every DApp has an associated Blockchain which allows the application to interface with the environment the app is running.

    Typically, it includes the transaction and block context, and other blockchain functionality.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static byte[] blake2b​(byte[] data)
      Calculates the blake2b digest of the input data.
      static Result call​(Address targetAddress, java.math.BigInteger value, byte[] data, long energyLimit)
      Calls another account, whether it's normal account or dapp.
      static Result create​(java.math.BigInteger value, byte[] data, long energyLimit)
      Creates an account.
      static boolean edVerify​(byte[] data, byte[] signature, byte[] publicKey)
      Verify that the given data is signed by providing the public key and the signed signature.
      static Address getAddress()
      Returns the owner's address, whose state is being accessed.
      static java.math.BigInteger getBalance​(Address address)
      Returns the balance of an account.
      static java.math.BigInteger getBalanceOfThisContract()
      Returns the balance of the contract in which this method was invoked.
      static Address getBlockCoinbase()
      Returns the block coinbase.
      static java.math.BigInteger getBlockDifficulty()
      Returns the block difficulty.
      static long getBlockEnergyLimit()
      Returns the block energy limit.
      static long getBlockNumber()
      Returns the block number.
      static long getBlockTimestamp()
      Returns the block timestamp.
      static Address getCaller()
      Returns the callers's address.
      static int getCodeSize​(Address address)
      Returns the size of the code, of the given account.
      static byte[] getData()
      Returns the data passed to this dapp.
      static long getEnergyLimit()
      Returns the energy limit for this current invocation.
      static long getEnergyPrice()
      Returns the energy price specified in the transaction.
      static Address getOrigin()
      Returns the originator's address.
      static long getRemainingEnergy()
      Returns the remaining energy, at the moment this method is being called.
      static byte[] getStorage​(byte[] key)
      Returns the storage value
      static java.math.BigInteger getValue()
      Returns the value being transferred to this dapp.
      static void invalid()
      Stop the current execution and roll back all state changes.
      static byte[] keccak256​(byte[] data)
      Calculates the keccak256 digest of the input data.
      static void log​(byte[] data)
      Records a log on blockchain.
      static void log​(byte[] topic1, byte[] data)
      Records a log on blockchain.
      static void log​(byte[] topic1, byte[] topic2, byte[] data)
      Records a log on blockchain.
      static void log​(byte[] topic1, byte[] topic2, byte[] topic3, byte[] data)
      Records a log on blockchain.
      static void log​(byte[] topic1, byte[] topic2, byte[] topic3, byte[] topic4, byte[] data)
      Records a log on blockchain.
      static void print​(java.lang.String message)
      Prints a message, for debugging purpose
      static void println​(java.lang.String message)
      Prints a message, for debugging purpose
      static void putStorage​(byte[] key, byte[] value)
      puts the key-value data of an account
      static void require​(boolean condition)
      Checks that the provided condition is true and if it is false, triggers a revert.
      static void revert()
      Stop the current execution and roll back all state changes.
      static void selfDestruct​(Address beneficiary)
      Destroys this dapp and refund all balance to the beneficiary address.
      static byte[] sha256​(byte[] data)
      Calculates the sha256 digest of the input data.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • getAddress

        public static Address getAddress()
        Returns the owner's address, whose state is being accessed. That is, the address of the currently-running DApp.
        Returns:
        an address

      • getCaller

        public static Address getCaller()
        Returns the callers's address. Note that the caller and the origin may be the same but differ in cross-calls: the origin is the sender of the "first" invocation in the chain while the caller is whoever directly called the current DApp.
        Returns:
        an address

      • getOrigin

        public static Address getOrigin()
        Returns the originator's address. Note that the caller and the origin may be the same but differ in cross-calls: the origin is the sender of the "first" invocation in the chain while the caller is whoever directly called the current DApp. Also, the origin never has associated code.
        Returns:
        an address

      • getEnergyLimit

        public static long getEnergyLimit()
        Returns the energy limit for this current invocation. Note that this is the total limit for the entire invocation, not just what is remaining.
        Returns:
        the max consumable energy

      • getEnergyPrice

        public static long getEnergyPrice()
        Returns the energy price specified in the transaction.
        Returns:
        energy price.

      • getValue

        public static java.math.BigInteger getValue()
        Returns the value being transferred to this dapp.
        Returns:
        the value in 10^-18 Aion

      • getData

        public static byte[] getData()
        Returns the data passed to this dapp.
        Returns:
        an byte array, non-NULL.

      • getBlockTimestamp

        public static long getBlockTimestamp()
        Returns the block timestamp.
        Returns:
        a timestamp indicates when the block is forged.

      • getBlockNumber

        public static long getBlockNumber()
        Returns the block number.
        Returns:
        the number of the block, in which the transaction is included

      • getBlockEnergyLimit

        public static long getBlockEnergyLimit()
        Returns the block energy limit.
        Returns:
        the energy cap of the block.

      • getBlockCoinbase

        public static Address getBlockCoinbase()
        Returns the block coinbase.
        Returns:
        the miner's address of the block.

      • getBlockDifficulty

        public static java.math.BigInteger getBlockDifficulty()
        Returns the block difficulty.
        Returns:
        the PoW difficulty of the block.

      • putStorage

        public static void putStorage​(byte[] key,
                              byte[] value)
                       throws java.lang.IllegalArgumentException
        puts the key-value data of an account
        Parameters:
        key - key of the key-value data pair
        value - value of the key-value data pair
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalud, e.g. NULL address

      • getStorage

        public static byte[] getStorage​(byte[] key)
                         throws java.lang.IllegalArgumentException
        Returns the storage value
        Parameters:
        key - key of the key-value data pair
        Returns:
        the value in storage associated to the given address and key
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalid, e.g. NULL address

      • getBalance

        public static java.math.BigInteger getBalance​(Address address)
                                       throws java.lang.IllegalArgumentException
        Returns the balance of an account.
        Parameters:
        address - the account address.
        Returns:
        the account balance, or 0 if the account does not exist
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalid, e.g. NULL address.

      • getBalanceOfThisContract

        public static java.math.BigInteger getBalanceOfThisContract()
        Returns the balance of the contract in which this method was invoked.
        Returns:
        the contract balance.

      • getCodeSize

        public static int getCodeSize​(Address address)
                       throws java.lang.IllegalArgumentException
        Returns the size of the code, of the given account.
        Parameters:
        address - the account address.
        Returns:
        the code size in bytes, or 0 if no contract is deployed at that address
        Throws:
        java.lang.IllegalArgumentException - when the argument is invalid, e.g. NULL address.

      • getRemainingEnergy

        public static long getRemainingEnergy()
        Returns the remaining energy, at the moment this method is being called.
        Returns:
        the remaining energy

      • call

        public static Result call​(Address targetAddress,
                          java.math.BigInteger value,
                          byte[] data,
                          long energyLimit)
                   throws java.lang.IllegalArgumentException
        Calls another account, whether it's normal account or dapp. In terms of the provided targetAddress, a call is legitimate only if: 1. The targetAddress has no code (ie. it is not a contract) 2. The targetAddress has code and its code can be executed by the Avm. If neither of these conditions is true then this method will throw an exception.
        Parameters:
        targetAddress - the account address
        value - the value to transfer
        data - the value to pass
        energyLimit - the max energy the invoked dapp can use.
        Returns:
        the invocation result.
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalid, e.g. insufficient balance, NULL address or the targetAddress is a contract that requires a foreign virtual machine in order to be executed.

      • create

        public static Result create​(java.math.BigInteger value,
                            byte[] data,
                            long energyLimit)
                     throws java.lang.IllegalArgumentException
        Creates an account.
        Parameters:
        value - the value to transfer to the account to be created.
        data - the data, in the format of size_of_code + code + size_of_data + data
        energyLimit - the max energy the invoked dapp can use.
        Returns:
        the invocation result.
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalid, e.g. insufficient balance or NULL data.

      • selfDestruct

        public static void selfDestruct​(Address beneficiary)
                         throws java.lang.IllegalArgumentException
        Destroys this dapp and refund all balance to the beneficiary address.
        Parameters:
        beneficiary - the beneficiary's address
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalid, e.g. NULL address.

      • log

        public static void log​(byte[] data)
                throws java.lang.IllegalArgumentException
        Records a log on blockchain.
        Parameters:
        data - any arbitrary data, non-NULL
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalid, e.g. any are NULL.

      • log

        public static void log​(byte[] topic1,
                       byte[] data)
                throws java.lang.IllegalArgumentException
        Records a log on blockchain.
        Parameters:
        topic1 - the 1st topic
        data - any arbitrary data, non-NULL
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalid, e.g. any are NULL.

      • log

        public static void log​(byte[] topic1,
                       byte[] topic2,
                       byte[] data)
                throws java.lang.IllegalArgumentException
        Records a log on blockchain.
        Parameters:
        topic1 - the 1st topic
        topic2 - the 2nd topic
        data - any arbitrary data, non-NULL
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalid, e.g. any are NULL.

      • log

        public static void log​(byte[] topic1,
                       byte[] topic2,
                       byte[] topic3,
                       byte[] data)
                throws java.lang.IllegalArgumentException
        Records a log on blockchain.
        Parameters:
        topic1 - the 1st topic
        topic2 - the 2nd topic
        topic3 - the 3rd topic
        data - any arbitrary data, non-NULL
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalid, e.g. any are NULL.

      • log

        public static void log​(byte[] topic1,
                       byte[] topic2,
                       byte[] topic3,
                       byte[] topic4,
                       byte[] data)
                throws java.lang.IllegalArgumentException
        Records a log on blockchain.
        Parameters:
        topic1 - the 1st topic
        topic2 - the 2nd topic
        topic3 - the 3rd topic
        topic4 - the 4th topic
        data - any arbitrary data, non-NULL
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalid, e.g. any are NULL.

      • blake2b

        public static byte[] blake2b​(byte[] data)
                      throws java.lang.IllegalArgumentException
        Calculates the blake2b digest of the input data.
        Parameters:
        data - the input data
        Returns:
        the hash digest
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalid, e.g. data is NULL.

      • sha256

        public static byte[] sha256​(byte[] data)
                     throws java.lang.IllegalArgumentException
        Calculates the sha256 digest of the input data.
        Parameters:
        data - the input data
        Returns:
        the hash digest
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalid, e.g. data is NULL.

      • keccak256

        public static byte[] keccak256​(byte[] data)
                        throws java.lang.IllegalArgumentException
        Calculates the keccak256 digest of the input data.
        Parameters:
        data - the input data
        Returns:
        the hash digest
        Throws:
        java.lang.IllegalArgumentException - when the arguments are invalid, e.g. data is NULL.

      • revert

        public static void revert()
        Stop the current execution and roll back all state changes.

        the remaining energy will be refunded.

      • invalid

        public static void invalid()
        Stop the current execution and roll back all state changes.

        the remaining energy will be consumed.

      • require

        public static void require​(boolean condition)
        Checks that the provided condition is true and if it is false, triggers a revert.

        In other words, if condition == true this method does nothing, otherwise it is equivalent to calling revert().

        Parameters:
        condition - The condition that is required to be true.

      • print

        public static void print​(java.lang.String message)
        Prints a message, for debugging purpose
        Parameters:
        message - the message to print

      • println

        public static void println​(java.lang.String message)
        Prints a message, for debugging purpose
        Parameters:
        message - the message to print

      • edVerify

        public static boolean edVerify​(byte[] data,
                               byte[] signature,
                               byte[] publicKey)
                        throws java.lang.IllegalArgumentException
        Verify that the given data is signed by providing the public key and the signed signature.
        Parameters:
        data - message to be signed
        signature - signature of the message
        publicKey - public key of the keypair used to sign the message
        Returns:
        result
        Throws:
        java.lang.IllegalArgumentException - thrown when an input parameter has the wrong size