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 Details

    • getArgs

      List<byte[]> getArgs()
      Returns the arguments corresponding to the call to Chaincode.init(ChaincodeStub) or Chaincode.invoke(ChaincodeStub), each argument represented as byte array.
      Returns:
      a list of arguments (bytes arrays)

    • getStringArgs

      List<String> getStringArgs()
      Returns the arguments corresponding to the call to Chaincode.init(ChaincodeStub) or Chaincode.invoke(ChaincodeStub), cast to UTF-8 string.
      Returns:
      a list of arguments cast to UTF-8 strings

    • getFunction

      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

      List<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

      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

      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(String chaincodeName, List<byte[]> args, 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(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(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(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(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(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(String startKey, 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(String startKey, String endKey, int pageSize, 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 (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(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(String objectType, 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, 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 (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(String objectType, 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(String compositeKey)
      Parses a composite key CompositeKey from a string.
      Parameters:
      compositeKey - a composite key string
      Returns:
      a composite key

    • getQueryResult

      QueryResultsIterator<KeyValue> getQueryResult(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:
      UnsupportedOperationException - if the underlying state database does not support rich queries.

    • getQueryResultWithPagination

      QueryResultsIteratorWithMetadata<KeyValue> getQueryResultWithPagination(String query, int pageSize, 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 (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(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(String collection, 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(String collection, String key)
      Parameters:
      collection - name of the collection
      key - name of the value
      Returns:
      the private data hash

    • getPrivateDataValidationParameter

      byte[] getPrivateDataValidationParameter(String collection, 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(String collection, 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(String collection, 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(String collection, 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

    • purgePrivateData

      void purgePrivateData(String collection, String key)
      Reqauests purging of the specified key to be from the private data stores.

      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 purged from the collection. This is an asynchronous activity.

      Purge is a complete removal of the history of the key. There is existing purge possible mased on block height. This API allows the contract to be pro-active in requesting data be purged. This can contribute towards meeting privacy requirements.

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

    • getPrivateDataByRange

      QueryResultsIterator<KeyValue> getPrivateDataByRange(String collection, String startKey, 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(String collection, 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(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(String collection, String objectType, 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(String collection, 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:
      UnsupportedOperationException - if the underlying state database does not support rich queries.

    • setEvent

      void setEvent(String name, byte[] payload)
      Allows the chaincode to propose an event on the transaction proposal response. When the transaction is included in a block and the block is successfully committed to the ledger, the block event (including transaction level chaincode events) will be delivered to the current client application event listeners that have been registered with the peer's event producer. Consult each SDK's documentation for details. Only a single chaincode event can be included in a transaction. If setEvent() is called multiple times only the last event will be included in the transaction. The event must originate from the outer-most invoked chaincode in chaincode-to-chaincode scenarios. The marshaled ChaincodeEvent will be available in the transaction's ChaincodeAction.events field.
      Parameters:
      name - Name of event. Cannot be null or empty string.
      payload - Optional event payload.

    • invokeChaincode

      default Chaincode.Response invokeChaincode(String chaincodeName, 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(String chaincodeName, List<String> args, 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(String chaincodeName, List<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(String chaincodeName, 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 String getStringState(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(String collection, String key, 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 String getPrivateDataUTF8(String collection, 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(String key, 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.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.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

      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

      Map<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

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