Package org.hyperledger.fabric.shim

Interface ChaincodeStub

  • public interface ChaincodeStub
    An object which manages the transaction context, provides access to state variables, and supports calls to other chaincode implementations.

    • Method Detail

      • getFunction

        java.lang.String getFunction()
        A convenience method that returns the first argument of the chaincode invocation for use as a function name.

        The bytes of the first argument are decoded as a UTF-8 string.

        Returns:
        the function name

      • getParameters

        java.util.List<java.lang.String> getParameters()
        A convenience method that returns all except the first argument of the chaincode invocation for use as the parameters to the function returned by #getFunction().

        The bytes of the arguments are decoded as a UTF-8 strings and returned as a list of string parameters.

        Returns:
        a list of parameters

      • getTxId

        java.lang.String getTxId()
        Returns the transaction id for the current chaincode invocation request.

        The transaction id uniquely identifies the transaction within the scope of the channel.

        Returns:
        the transaction id

      • getChannelId

        java.lang.String getChannelId()
        Returns the channel id for the current proposal.

        This would be the 'channel_id' of the transaction proposal except where the chaincode is calling another on a different channel.

        Returns:
        the channel id

      • invokeChaincode

        Chaincode.Response invokeChaincode​(java.lang.String chaincodeName,
                                   java.util.List<byte[]> args,
                                   java.lang.String channel)
        Locally calls the specified chaincode invoke() using the same transaction context.

        chaincode calling chaincode doesn't create a new transaction message.

        If the called chaincode is on the same channel, it simply adds the called chaincode read set and write set to the calling transaction.

        If the called chaincode is on a different channel, only the Response is returned to the calling chaincode; any putState calls from the called chaincode will not have any effect on the ledger; that is, the called chaincode on a different channel will not have its read set and write set applied to the transaction. Only the calling chaincode's read set and write set will be applied to the transaction. Effectively the called chaincode on a different channel is a `Query`, which does not participate in state validation checks in subsequent commit phase.

        If `channel` is empty, the caller's channel is assumed.

        Invoke another chaincode using the same transaction context.

        Parameters:
        chaincodeName - Name of chaincode to be invoked.
        args - Arguments to pass on to the called chaincode.
        channel - If not specified, the caller's channel is assumed.
        Returns:
        Chaincode.Response object returned by called chaincode

      • getState

        byte[] getState​(java.lang.String key)
        Returns the value of the specified key from the ledger.

        Note that getState doesn't read data from the writeset, which has not been committed to the ledger. In other words, GetState doesn't consider data modified by PutState that has not been committed.

        Parameters:
        key - name of the value
        Returns:
        value the value read from the ledger

      • getStateValidationParameter

        byte[] getStateValidationParameter​(java.lang.String key)
        retrieves the key-level endorsement policy for key. Note that this will introduce a read dependency on key in the transaction's readset.
        Parameters:
        key - key to get key level endorsement
        Returns:
        endorsement policy

      • putState

        void putState​(java.lang.String key,
              byte[] value)
        Puts the specified key and value into the transaction's writeset as a data-write proposal.

        putState doesn't effect the ledger until the transaction is validated and successfully committed. Simple keys must not be an empty string and must not start with 0x00 character, in order to avoid range query collisions with composite keys

        Parameters:
        key - name of the value
        value - the value to write to the ledger

      • setStateValidationParameter

        void setStateValidationParameter​(java.lang.String key,
                                 byte[] value)
        Sets the key-level endorsement policy for key.
        Parameters:
        key - key to set key level endorsement
        value - endorsement policy

      • delState

        void delState​(java.lang.String key)
        Records the specified key to be deleted in the writeset of the transaction proposal.

        The key and its value will be deleted from the ledger when the transaction is validated and successfully committed.

        Parameters:
        key - name of the value to be deleted

      • getStateByRange

        QueryResultsIterator<KeyValue> getStateByRange​(java.lang.String startKey,
                                               java.lang.String endKey)
        Returns all existing keys, and their values, that are lexicographically between startkey (inclusive) and the endKey (exclusive).

        The keys are returned by the iterator in lexical order. Note that startKey and endKey can be empty string, which implies unbounded range query on start or end.

        Call close() on the returned AutoCloseable.close() object when done.

        Parameters:
        startKey - key as the start of the key range (inclusive)
        endKey - key as the end of the key range (exclusive)
        Returns:
        an Iterable of KeyValue

      • getStateByRangeWithPagination

        QueryResultsIteratorWithMetadata<KeyValue> getStateByRangeWithPagination​(java.lang.String startKey,
                                                                         java.lang.String endKey,
                                                                         int pageSize,
                                                                         java.lang.String bookmark)
        Returns a range iterator over a set of keys in the ledger. The iterator can be used to fetch keys between the startKey (inclusive) and endKey (exclusive). When an empty string is passed as a value to the bookmark argument, the returned iterator can be used to fetch the first pageSize keys between the startKey and endKey. When the bookmark is a non-empty string, the iterator can be used to fetch first pageSize keys between the bookmark and endKey. Note that only the bookmark present in a prior page of query results (ChaincodeShim.QueryResponseMetadata) can be used as a value to the bookmark argument. Otherwise, an empty string must be passed as bookmark. The keys are returned by the iterator in lexical order. Note that startKey and endKey can be empty string, which implies unbounded range query on start or end. This call is only supported in a read only transaction.
        Parameters:
        startKey - the start key
        endKey - the end key
        pageSize - the page size
        bookmark - the bookmark
        Returns:
        QueryIterator

      • getStateByPartialCompositeKey

        QueryResultsIterator<KeyValue> getStateByPartialCompositeKey​(java.lang.String compositeKey)
        Returns all existing keys, and their values, that are prefixed by the specified partial CompositeKey.

        If a full composite key is specified, it will not match itself, resulting in no keys being returned.

        This method takes responsibility to correctly parse the CompositeKey from a String and behaves exactly as getStateByPartialCompositeKey(CompositeKey).

        Call close() on the returned AutoCloseable.close() object when done.

        Parameters:
        compositeKey - partial composite key
        Returns:
        an Iterable of KeyValue

      • getStateByPartialCompositeKey

        QueryResultsIterator<KeyValue> getStateByPartialCompositeKey​(java.lang.String objectType,
                                                             java.lang.String... attributes)
        Returns all existing keys, and their values, that are prefixed by the specified partial CompositeKey.

        It combines the attributes and the objectType to form a partial composite key.

        If a full composite key is specified, it will not match itself, resulting in no keys being returned.

        This method takes responsibility to correctly combine Object type and attributes creating a CompositeKey and behaves exactly as getStateByPartialCompositeKey(CompositeKey).

        Call close() on the returned AutoCloseable.close() object when done.
        Parameters:
        objectType - ObjectType of the compositeKey
        attributes - Attributes of the composite key
        Returns:
        an Iterable of KeyValue

      • getStateByPartialCompositeKey

        QueryResultsIterator<KeyValue> getStateByPartialCompositeKey​(CompositeKey compositeKey)
        Returns all existing keys, and their values, that are prefixed by the specified partial CompositeKey.

        If a full composite key is specified, it will not match itself, resulting in no keys being returned.

        Parameters:
        compositeKey - partial composite key
        Returns:
        an Iterable of KeyValue

      • getStateByPartialCompositeKeyWithPagination

        QueryResultsIteratorWithMetadata<KeyValue> getStateByPartialCompositeKeyWithPagination​(CompositeKey compositeKey,
                                                                                       int pageSize,
                                                                                       java.lang.String bookmark)
        Queries the state in the ledger based on a given partial composite key. This function returns an iterator which can be used to iterate over the composite keys whose prefix matches the given partial composite key.

        When an empty string is passed as a value to the bookmark argument, the returned iterator can be used to fetch the first pageSize composite keys whose prefix matches the given partial composite key.

        When the bookmark is a non-empty string, the iterator can be used to fetch first pageSize keys between the bookmark (inclusive) and and the last matching composite key.

        Note that only the bookmark present in a prior page of query results (ChaincodeShim.QueryResponseMetadata) can be used as a value to the bookmark argument. Otherwise, an empty string must be passed as bookmark.

        This call is only supported in a read only transaction.

        Parameters:
        compositeKey - the composite key
        pageSize - the page size
        bookmark - the bookmark
        Returns:
        QueryIterator

      • createCompositeKey

        CompositeKey createCompositeKey​(java.lang.String objectType,
                                java.lang.String... attributes)
        Given a set of attributes, this method combines these attributes to return a composite key.
        Parameters:
        objectType - A string used as the prefix of the resulting key
        attributes - List of attribute values to concatenate into the key
        Returns:
        a composite key

      • splitCompositeKey

        CompositeKey splitCompositeKey​(java.lang.String compositeKey)
        Parses a composite key CompositeKey from a string.
        Parameters:
        compositeKey - a composite key string
        Returns:
        a composite key

      • getQueryResult

        QueryResultsIterator<KeyValue> getQueryResult​(java.lang.String query)
        Performs a "rich" query against a state database.

        It is only supported for state databases that support rich query, e.g. CouchDB. The query string is in the native syntax of the underlying state database. An QueryResultsIterator is returned which can be used to iterate (next) over the query result set.

        Parameters:
        query - query string in a syntax supported by the underlying state database
        Returns:
        QueryResultsIterator object contains query results
        Throws:
        java.lang.UnsupportedOperationException - if the underlying state database does not support rich queries.

      • getQueryResultWithPagination

        QueryResultsIteratorWithMetadata<KeyValue> getQueryResultWithPagination​(java.lang.String query,
                                                                        int pageSize,
                                                                        java.lang.String bookmark)
        Performs a "rich" query against a state database. It is only supported for state databases that support rich query, e.g., CouchDB. The query string is in the native syntax of the underlying state database. An iterator is returned which can be used to iterate over keys in the query result set. When an empty string is passed as a value to the bookmark argument, the returned iterator can be used to fetch the first pageSize of query results..

        When the bookmark is a non-empty string, the iterator can be used to fetch first pageSize keys between the bookmark (inclusive) and the last key in the query result.

        Note that only the bookmark present in a prior page of query results (ChaincodeShim.QueryResponseMetadata) can be used as a value to the bookmark argument. Otherwise, an empty string must be passed as bookmark.

        This call is only supported in a read only transaction.

        Parameters:
        query - the query
        pageSize - the page size
        bookmark - the bookmark
        Returns:
        QueryIterator

      • getHistoryForKey

        QueryResultsIterator<KeyModification> getHistoryForKey​(java.lang.String key)
        Returns a history of key values across time.

        For each historic key update, the historic value and associated transaction id and timestamp are returned. The timestamp is the timestamp provided by the client in the proposal header. This method requires peer configuration core.ledger.history.enableHistoryDatabase to be true.

        Parameters:
        key - The state variable key
        Returns:
        an Iterable of KeyModification

      • getPrivateData

        byte[] getPrivateData​(java.lang.String collection,
                      java.lang.String key)
        Returns the value of the specified key from the specified collection.

        Note that getPrivateData(String, String) doesn't read data from the private writeset, which has not been committed to the collection. In other words, getPrivateData(String, String) doesn't consider data modified by putPrivateData(String, String, byte[]) * that has not been committed.

        Parameters:
        collection - name of the collection
        key - name of the value
        Returns:
        value the value read from the collection

      • getPrivateDataHash

        byte[] getPrivateDataHash​(java.lang.String collection,
                          java.lang.String key)
        Parameters:
        collection - name of the collection
        key - name of the value
        Returns:
        the private data hash

      • getPrivateDataValidationParameter

        byte[] getPrivateDataValidationParameter​(java.lang.String collection,
                                         java.lang.String key)
        Retrieves the key-level endorsement policy for the private data specified by key. Note that this introduces a read dependency on key in the transaction's readset.
        Parameters:
        collection - name of the collection
        key - key to get endorsement policy
        Returns:
        Key Level endorsement as byte array

      • putPrivateData

        void putPrivateData​(java.lang.String collection,
                    java.lang.String key,
                    byte[] value)
        Puts the specified key and value into the transaction's private writeset.

        Note that only hash of the private writeset goes into the transaction proposal response (which is sent to the client who issued the transaction) and the actual private writeset gets temporarily stored in a transient store. putPrivateData doesn't effect the collection until the transaction is validated and successfully committed. Simple keys must not be an empty string and must not start with null character (0x00), in order to avoid range query collisions with composite keys, which internally get prefixed with 0x00 as composite key namespace.

        Parameters:
        collection - name of the collection
        key - name of the value
        value - the value to write to the ledger

      • setPrivateDataValidationParameter

        void setPrivateDataValidationParameter​(java.lang.String collection,
                                       java.lang.String key,
                                       byte[] value)
        Sets the key-level endorsement policy for the private data specified by key.
        Parameters:
        collection - name of the collection
        key - key to set endorsement policy
        value - endorsement policy

      • delPrivateData

        void delPrivateData​(java.lang.String collection,
                    java.lang.String key)
        Records the specified key to be deleted in the private writeset of the transaction.

        Note that only hash of the private writeset goes into the transaction proposal response (which is sent to the client who issued the transaction) and the actual private writeset gets temporarily stored in a transient store. The key and its value will be deleted from the collection when the transaction is validated and successfully committed.

        Parameters:
        collection - name of the collection
        key - name of the value to be deleted

      • getPrivateDataByRange

        QueryResultsIterator<KeyValue> getPrivateDataByRange​(java.lang.String collection,
                                                     java.lang.String startKey,
                                                     java.lang.String endKey)
        Returns all existing keys, and their values, that are lexicographically between startkey (inclusive) and the endKey (exclusive) in a given private collection.

        Note that startKey and endKey can be empty string, which implies unbounded range query on start or end. The query is re-executed during validation phase to ensure result set has not changed since transaction endorsement (phantom reads detected).

        Parameters:
        collection - name of the collection
        startKey - private data variable key as the start of the key range (inclusive)
        endKey - private data variable key as the end of the key range (exclusive)
        Returns:
        an Iterable of KeyValue

      • getPrivateDataByPartialCompositeKey

        QueryResultsIterator<KeyValue> getPrivateDataByPartialCompositeKey​(java.lang.String collection,
                                                                   java.lang.String compositeKey)
        Returns all existing keys, and their values, that are prefixed by the specified partial CompositeKey in a given private collection.

        If a full composite key is specified, it will not match itself, resulting in no keys being returned.

        The query is re-executed during validation phase to ensure result set has not changed since transaction endorsement (phantom reads detected).

        This method takes responsibility to correctly parse the CompositeKey from a String and behaves exactly as getPrivateDataByPartialCompositeKey(String, CompositeKey).

        Parameters:
        collection - name of the collection
        compositeKey - partial composite key
        Returns:
        an Iterable of KeyValue

      • getPrivateDataByPartialCompositeKey

        QueryResultsIterator<KeyValue> getPrivateDataByPartialCompositeKey​(java.lang.String collection,
                                                                   CompositeKey compositeKey)
        Returns all existing keys, and their values, that are prefixed by the specified partial CompositeKey in a given private collection.

        If a full composite key is specified, it will not match itself, resulting in no keys being returned.

        The query is re-executed during validation phase to ensure result set has not changed since transaction endorsement (phantom reads detected).

        Parameters:
        collection - name of the collection
        compositeKey - partial composite key
        Returns:
        an Iterable of KeyValue

      • getPrivateDataByPartialCompositeKey

        QueryResultsIterator<KeyValue> getPrivateDataByPartialCompositeKey​(java.lang.String collection,
                                                                   java.lang.String objectType,
                                                                   java.lang.String... attributes)
        Returns all existing keys, and their values, that are prefixed by the specified partial CompositeKey in a given private collection.

        If a full composite key is specified, it will not match itself, resulting in no keys being returned.

        The query is re-executed during validation phase to ensure result set has not changed since transaction endorsement (phantom reads detected).

        This method takes responsibility to correctly combine Object type and attributes creating a CompositeKey and behaves exactly as getPrivateDataByPartialCompositeKey(String, CompositeKey).

        Parameters:
        collection - name of the collection
        objectType - ObjectType of the compositeKey
        attributes - Attributes of the composite key
        Returns:
        an Iterable of KeyValue

      • getPrivateDataQueryResult

        QueryResultsIterator<KeyValue> getPrivateDataQueryResult​(java.lang.String collection,
                                                         java.lang.String query)
        Perform a rich query against a given private collection.

        It is only supported for state databases that support rich query, e.g.CouchDB. The query string is in the native syntax of the underlying state database. An iterator is returned which can be used to iterate (next) over the query result set. The query is NOT re-executed during validation phase, phantom reads are not detected. That is, other committed transactions may have added, updated, or removed keys that impact the result set, and this would not be detected at validation/commit time. Applications susceptible to this should therefore not use GetQueryResult as part of transactions that update ledger, and should limit use to read-only chaincode operations.

        Parameters:
        collection - name of the collection
        query - query string in a syntax supported by the underlying state database
        Returns:
        QueryResultsIterator object contains query results
        Throws:
        java.lang.UnsupportedOperationException - if the underlying state database does not support rich queries.

      • setEvent

        void setEvent​(java.lang.String name,
              byte[] payload)
        Defines the CHAINCODE type event that will be posted to interested clients when the chaincode's result is committed to the ledger.
        Parameters:
        name - Name of event. Cannot be null or empty string.
        payload - Optional event payload.

      • invokeChaincode

        default Chaincode.Response invokeChaincode​(java.lang.String chaincodeName,
                                           java.util.List<byte[]> args)
        Invoke another chaincode using the same transaction context.

        Same as invokeChaincode(String, List, String) using channelId to null

        Parameters:
        chaincodeName - Name of chaincode to be invoked.
        args - Arguments to pass on to the called chaincode.
        Returns:
        Chaincode.Response object returned by called chaincode

      • invokeChaincodeWithStringArgs

        default Chaincode.Response invokeChaincodeWithStringArgs​(java.lang.String chaincodeName,
                                                         java.util.List<java.lang.String> args,
                                                         java.lang.String channel)
        Invoke another chaincode using the same transaction context.

        This is a convenience version of invokeChaincode(String, List, String). The string args will be encoded into as UTF-8 bytes.

        Parameters:
        chaincodeName - Name of chaincode to be invoked.
        args - Arguments to pass on to the called chaincode.
        channel - If not specified, the caller's channel is assumed.
        Returns:
        Chaincode.Response object returned by called chaincode

      • invokeChaincodeWithStringArgs

        default Chaincode.Response invokeChaincodeWithStringArgs​(java.lang.String chaincodeName,
                                                         java.util.List<java.lang.String> args)
        Invoke another chaincode using the same transaction context.

        This is a convenience version of invokeChaincode(String, List). The string args will be encoded into as UTF-8 bytes.

        Parameters:
        chaincodeName - Name of chaincode to be invoked.
        args - Arguments to pass on to the called chaincode.
        Returns:
        Chaincode.Response object returned by called chaincode

      • invokeChaincodeWithStringArgs

        default Chaincode.Response invokeChaincodeWithStringArgs​(java.lang.String chaincodeName,
                                                         java.lang.String... args)
        Invoke another chaincode using the same transaction context.

        This is a convenience version of invokeChaincode(String, List). The string args will be encoded into as UTF-8 bytes.

        Parameters:
        chaincodeName - Name of chaincode to be invoked.
        args - Arguments to pass on to the called chaincode.
        Returns:
        Chaincode.Response object returned by called chaincode

      • getStringState

        default java.lang.String getStringState​(java.lang.String key)
        Returns the byte array value specified by the key and decoded as a UTF-8 encoded string, from the ledger.

        This is a convenience version of getState(String)

        Parameters:
        key - name of the value
        Returns:
        value the value read from the ledger

      • putPrivateData

        default void putPrivateData​(java.lang.String collection,
                            java.lang.String key,
                            java.lang.String value)
        Writes the specified value and key into the sidedb collection value converted to byte array.
        Parameters:
        collection - collection name
        key - name of the value
        value - the value to write to the ledger

      • getPrivateDataUTF8

        default java.lang.String getPrivateDataUTF8​(java.lang.String collection,
                                            java.lang.String key)
        Returns the byte array value specified by the key and decoded as a UTF-8 encoded string, from the sidedb collection.
        Parameters:
        collection - collection name
        key - name of the value
        Returns:
        value the value read from the ledger

      • putStringState

        default void putStringState​(java.lang.String key,
                            java.lang.String value)
        Writes the specified value and key into the ledger.
        Parameters:
        key - name of the value
        value - the value to write to the ledger

      • getEvent

        org.hyperledger.fabric.protos.peer.ChaincodeEventPackage.ChaincodeEvent getEvent()
        Returns the CHAINCODE type event that will be posted to interested clients when the chaincode's result is committed to the ledger.
        Returns:
        the chaincode event or null

      • getSignedProposal

        org.hyperledger.fabric.protos.peer.ProposalPackage.SignedProposal getSignedProposal()
        Returns the signed transaction proposal currently being executed.
        Returns:
        null if the current transaction is an internal call to a system chaincode.

      • getTxTimestamp

        java.time.Instant getTxTimestamp()
        Returns the timestamp when the transaction was created.
        Returns:
        timestamp as specified in the transaction's channel header.

      • getCreator

        byte[] getCreator()
        Returns the identity of the agent (or user) submitting the transaction.
        Returns:
        the bytes of the creator field of the proposal's signature header.

      • getTransient

        java.util.Map<java.lang.String,​byte[]> getTransient()
        Returns the transient map associated with the current transaction.
        Returns:
        map of transient field

      • getBinding

        byte[] getBinding()
        Returns the transaction binding.
        Returns:
        binding between application data and proposal

      • getMspId

        java.lang.String getMspId()
        Get the MSPID of the peer that started this chaincode.
        Returns:
        string MSPID