Package score

Class Context

  • public final class Context
extends java.lang.Object
    Every SCORE has an associated Context which allows the application to interface with the environment the SCORE 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 <T> T call​(java.lang.Class<T> cls, java.math.BigInteger value, Address targetAddress, java.lang.String method, java.lang.Object... params)
      Calls the method of the given account address with the value.
      static <T> T call​(java.lang.Class<T> cls, Address targetAddress, java.lang.String method, java.lang.Object... params)
      Calls the method of the account designated by the targetAddress.
      static java.lang.Object call​(java.math.BigInteger value, Address targetAddress, java.lang.String method, java.lang.Object... params)
      Calls the method of the given account address with the value.
      static java.lang.Object call​(Address targetAddress, java.lang.String method, java.lang.Object... params)
      Calls the method of the account designated by the targetAddress.
      static Address deploy​(byte[] content, java.lang.Object... params)
      Deploys a SCORE with the given byte streams.
      static Address deploy​(Address targetAddress, byte[] content, java.lang.Object... params)
      Deploys a SCORE with the given byte streams to the target address.
      static Address getAddress()
      Returns the address of the currently-running SCORE.
      static Address getAddressFromKey​(byte[] pubKey)
      Returns the address that is associated with the given public key.
      static java.math.BigInteger getBalance​(Address address)
      Returns the balance of an account.
      static long getBlockHeight()
      Returns the block height.
      static long getBlockTimestamp()
      Returns the block timestamp.
      static Address getCaller()
      Returns the caller's address.
      static int getFeeSharingProportion()
      Returns the current fee sharing proportion of the SCORE.
      static Address getOrigin()
      Returns the originator's address.
      static Address getOwner()
      Returns the address of the account who initially deployed the contract.
      static byte[] getTransactionHash()
      Returns the hash of the transaction.
      static int getTransactionIndex()
      Returns the transaction index in a block.
      static java.math.BigInteger getTransactionNonce()
      Returns the nonce of a transaction request.
      static long getTransactionTimestamp()
      Returns the timestamp of a transaction request.
      static java.math.BigInteger getValue()
      Returns the value being transferred to this SCORE.
      static byte[] hash​(java.lang.String alg, byte[] msg)
      Returns hash value of the given message.
      static void logEvent​(java.lang.Object[] indexed, java.lang.Object[] data)
      Records a log on the blockchain.
      static <E> ArrayDB<E> newArrayDB​(java.lang.String id, java.lang.Class<E> valueClass)
      Returns a new array DB.
      static <K,​V>
      BranchDB<K,​V>      		 newBranchDB​(java.lang.String id, java.lang.Class<?> leafValueClass)
      Returns a new branch DB.
      static ObjectReader newByteArrayObjectReader​(java.lang.String codec, byte[] byteArray)
      Returns a new object reader reading from a byte array.
      static ByteArrayObjectWriter newByteArrayObjectWriter​(java.lang.String codec)
      Returns a new object writer writing to a byte array.
      static <K,​V>
      DictDB<K,​V>      		 newDictDB​(java.lang.String id, java.lang.Class<V> valueClass)
      Returns a new dictionary DB.
      static <E> VarDB<E> newVarDB​(java.lang.String id, java.lang.Class<E> valueClass)
      Returns a new variable DB.
      static void println​(java.lang.String message)
      Prints a message, for debugging purpose.
      static byte[] recoverKey​(java.lang.String alg, byte[] msg, byte[] sig, boolean compressed)
      Recovers the public key from the message and the recoverable signature.
      static void require​(boolean condition)
      Checks that the provided condition is true and if it is false, triggers a revert.
      static void require​(boolean condition, java.lang.String message)
      Checks that the provided condition is true and if it is false, triggers a revert.
      static void revert()
      Stops the current execution and rolls back all state changes.
      static void revert​(int code)
      Stops the current execution and rolls back all state changes.
      static void revert​(int code, java.lang.String message)
      Stops the current execution and rolls back all state changes.
      static void revert​(java.lang.String message)
      Stops the current execution and rolls back all state changes.
      static void setFeeSharingProportion​(int proportion)
      Sets the proportion of transaction fees that the SCORE will pay.
      static void transfer​(Address targetAddress, java.math.BigInteger value)
      Transfers the value to the given target address from this SCORE's account.
      static boolean verifySignature​(java.lang.String alg, byte[] msg, byte[] sig, byte[] pubKey)
      Returns true if the given signature for the given message by the given public key is correct.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • getTransactionHash

        public static byte[] getTransactionHash()
        Returns the hash of the transaction.
        Returns:
        the transaction hash

      • getTransactionIndex

        public static int getTransactionIndex()
        Returns the transaction index in a block.
        Returns:
        the transaction index

      • getTransactionTimestamp

        public static long getTransactionTimestamp()
        Returns the timestamp of a transaction request.
        Returns:
        the transaction timestamp

      • getTransactionNonce

        public static java.math.BigInteger getTransactionNonce()
        Returns the nonce of a transaction request.
        Returns:
        the transaction nonce

      • getAddress

        public static Address getAddress()
        Returns the address of the currently-running SCORE.
        Returns:
        an address

      • getCaller

        public static Address getCaller()
        Returns the caller'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 SCORE.
        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 SCORE. Also, the origin never has associated code.
        Returns:
        an address

      • getOwner

        public static Address getOwner()
        Returns the address of the account who initially deployed the contract.
        Returns:
        an address

      • getValue

        public static java.math.BigInteger getValue()
        Returns the value being transferred to this SCORE.
        Returns:
        the value in loop (1 ICX == 10^18 loop)

      • getBlockTimestamp

        public static long getBlockTimestamp()
        Returns the block timestamp.
        Returns:
        the timestamp of the current block in microseconds

      • getBlockHeight

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

      • 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 - if the address is invalid, e.g. NULL address

      • call

        public static <T> T call​(java.lang.Class<T> cls,
                         java.math.BigInteger value,
                         Address targetAddress,
                         java.lang.String method,
                         java.lang.Object... params)
        Calls the method of the given account address with the value.
        Type Parameters:
        T - return type
        Parameters:
        cls - class of return type
        value - the value in loop to transfer
        targetAddress - the account address
        method - method
        params - parameters
        Returns:
        the invocation result
        Throws:
        java.lang.IllegalArgumentException - if the arguments are invalid, e.g. insufficient balance, NULL address
        RevertedException - if call target reverts the newly created frame
        UserRevertedException - if call target reverts the newly created frame by calling revert(int, java.lang.String)

      • call

        public static java.lang.Object call​(java.math.BigInteger value,
                                    Address targetAddress,
                                    java.lang.String method,
                                    java.lang.Object... params)
        Calls the method of the given account address with the value.
        Parameters:
        value - the value in loop to transfer
        targetAddress - the account address
        method - method
        params - parameters
        Returns:
        the invocation result
        Throws:
        java.lang.IllegalArgumentException - if the arguments are invalid, e.g. insufficient balance, NULL address
        RevertedException - if call target reverts the newly created frame
        UserRevertedException - if call target reverts the newly created frame by calling revert(int, java.lang.String)

      • call

        public static <T> T call​(java.lang.Class<T> cls,
                         Address targetAddress,
                         java.lang.String method,
                         java.lang.Object... params)
        Calls the method of the account designated by the targetAddress.
        Type Parameters:
        T - return type
        Parameters:
        cls - class of return type
        targetAddress - the account address
        method - method
        params - parameters
        Returns:
        the invocation result
        Throws:
        java.lang.IllegalArgumentException - if the arguments are invalid, e.g. insufficient balance, NULL address
        RevertedException - if call target reverts the newly created frame
        UserRevertedException - if call target reverts the newly created frame by calling revert(int, java.lang.String)

      • call

        public static java.lang.Object call​(Address targetAddress,
                                    java.lang.String method,
                                    java.lang.Object... params)
        Calls the method of the account designated by the targetAddress.
        Parameters:
        targetAddress - the account address
        method - method
        params - parameters
        Returns:
        the invocation result
        Throws:
        java.lang.IllegalArgumentException - if the arguments are invalid, e.g. insufficient balance, NULL address
        RevertedException - if call target reverts the newly created frame
        UserRevertedException - if call target reverts the newly created frame by calling revert(int, java.lang.String)

      • transfer

        public static void transfer​(Address targetAddress,
                            java.math.BigInteger value)
        Transfers the value to the given target address from this SCORE's account.
        Parameters:
        targetAddress - the account address
        value - the value in loop to transfer
        Throws:
        java.lang.IllegalArgumentException - if the arguments are invalid, e.g. insufficient balance, NULL address

      • deploy

        public static Address deploy​(byte[] content,
                             java.lang.Object... params)
        Deploys a SCORE with the given byte streams.
        Parameters:
        content - the byte streams of the SCORE
        params - parameters
        Returns:
        the newly created SCORE address
        Throws:
        java.lang.IllegalArgumentException - if the arguments are invalid, e.g. corrupted content, etc.

      • deploy

        public static Address deploy​(Address targetAddress,
                             byte[] content,
                             java.lang.Object... params)
        Deploys a SCORE with the given byte streams to the target address.
        Parameters:
        targetAddress - the SCORE address that is to be updated
        content - the byte streams of the SCORE
        params - parameters
        Returns:
        the target SCORE address
        Throws:
        java.lang.IllegalArgumentException - if the arguments are invalid, e.g. corrupted content, NULL address

      • revert

        public static void revert​(int code,
                          java.lang.String message)
        Stops the current execution and rolls back all state changes. In case of cross-calls, UserRevertedException would be raised to the caller with the given code and message data.
        Parameters:
        code - an arbitrary user-defined code
        message - a message to be delivered to the caller

      • revert

        public static void revert​(int code)
        Stops the current execution and rolls back all state changes.
        Parameters:
        code - an arbitrary user-defined code
        See Also:
        revert(int, String)

      • revert

        public static void revert​(java.lang.String message)
        Stops the current execution and rolls back all state changes.
        Parameters:
        message - a message
        See Also:
        revert(int, String)

      • revert

        public static void revert()
        Stops the current execution and rolls back all state changes. This is equivalent to revert(0).
        See Also:
        revert(int)

      • require

        public static void require​(boolean condition,
                           java.lang.String message)
        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(String).

        Parameters:
        condition - the condition that is required to be true.
        message - a message

      • 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.

      • println

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

      • hash

        public static byte[] hash​(java.lang.String alg,
                          byte[] msg)
        Returns hash value of the given message.
        Parameters:
        alg - hash algorithm. One of sha-256, sha3-256, keccak-256, xxhash-128, blake2b-128 and blake2b-256.
        msg - message
        Returns:
        hash value
        Throws:
        java.lang.IllegalArgumentException - if the algorithm is unsupported.

      • verifySignature

        public static boolean verifySignature​(java.lang.String alg,
                                      byte[] msg,
                                      byte[] sig,
                                      byte[] pubKey)
        Returns true if the given signature for the given message by the given public key is correct.
        Parameters:
        alg - signature algorithm. One of ed25519 and ecdsa-secp256k1
        msg - message
        sig - signature
        pubKey - public key
        Returns:
        true if the given signature for the given message by the given public key is correct.
        Throws:
        java.lang.IllegalArgumentException - if the algorithm is unsupported.

      • recoverKey

        public static byte[] recoverKey​(java.lang.String alg,
                                byte[] msg,
                                byte[] sig,
                                boolean compressed)
        Recovers the public key from the message and the recoverable signature.
        Parameters:
        alg - signature algorithm. ecdsa-secp256k1 is supported.
        msg - message
        sig - signature
        compressed - the type of public key to be returned
        Returns:
        the public key recovered from message and signature
        Throws:
        java.lang.IllegalArgumentException - if the algorithm is unsupported.

      • getAddressFromKey

        public static Address getAddressFromKey​(byte[] pubKey)
        Returns the address that is associated with the given public key.
        Parameters:
        pubKey - a byte array that represents the public key
        Returns:
        the address that is associated with the public key

      • getFeeSharingProportion

        public static int getFeeSharingProportion()
        Returns the current fee sharing proportion of the SCORE. 100 means the SCORE will pay 100% of transaction fees on behalf of the transaction sender.
        Returns:
        the current fee sharing proportion that the SCORE will pay (0 to 100)

      • setFeeSharingProportion

        public static void setFeeSharingProportion​(int proportion)
        Sets the proportion of transaction fees that the SCORE will pay. proportion should be between 0 to 100. If this method is invoked multiple times, the last proportion value will be used.
        Parameters:
        proportion - the desired proportion of transaction fees that the SCORE will pay
        Throws:
        java.lang.IllegalArgumentException - if the proportion is not between 0 to 100

      • newBranchDB

        public static <K,​V> BranchDB<K,​V> newBranchDB​(java.lang.String id,
                                                          java.lang.Class<?> leafValueClass)
        Returns a new branch DB.
        Type Parameters:
        K - key type
        V - sub-DB type
        Parameters:
        id - DB ID
        leafValueClass - class of leaf value. For example, a branch DB of type BranchDB<BigInteger, DictDB<Address, Boolean>> has Boolean.class as its leaf value class.
        Returns:
        new branch DB
        See Also:
        BranchDB

      • newDictDB

        public static <K,​V> DictDB<K,​V> newDictDB​(java.lang.String id,
                                                      java.lang.Class<V> valueClass)
        Returns a new dictionary DB.
        Type Parameters:
        K - key type
        V - value type
        Parameters:
        id - DB ID
        valueClass - class of V
        Returns:
        new dictionary DB
        See Also:
        DictDB

      • newArrayDB

        public static <E> ArrayDB<E> newArrayDB​(java.lang.String id,
                                        java.lang.Class<E> valueClass)
        Returns a new array DB.
        Type Parameters:
        E - element type
        Parameters:
        id - DB ID
        valueClass - class of E
        Returns:
        new array DB
        See Also:
        ArrayDB

      • newVarDB

        public static <E> VarDB<E> newVarDB​(java.lang.String id,
                                    java.lang.Class<E> valueClass)
        Returns a new variable DB.
        Type Parameters:
        E - variable type
        Parameters:
        id - DB ID
        valueClass - class of E
        Returns:
        new variable DB
        See Also:
        ArrayDB

      • logEvent

        public static void logEvent​(java.lang.Object[] indexed,
                            java.lang.Object[] data)
        Records a log on the blockchain. It is recommended to use EventLog annotation rather than this method directly.
        Parameters:
        indexed - indexed data
        data - extra data

      • newByteArrayObjectReader

        public static ObjectReader newByteArrayObjectReader​(java.lang.String codec,
                                                    byte[] byteArray)
        Returns a new object reader reading from a byte array.
        Parameters:
        codec - codec. Currently "RLPn" is supported.
        byteArray - byte array.
        Returns:
        object reader.
        Throws:
        java.lang.IllegalArgumentException - if the codec is unsupported.

      • newByteArrayObjectWriter

        public static ByteArrayObjectWriter newByteArrayObjectWriter​(java.lang.String codec)
        Returns a new object writer writing to a byte array.
        Parameters:
        codec - codec. Currently "RLPn" is supported.
        Returns:
        byte array object writer
        Throws:
        java.lang.IllegalArgumentException - if the codec is unsupported.