org.hyperledger.fabric.shim.ChaincodeStub Maven / Gradle / Ivy
Show all versions of fabric-chaincode-shim Show documentation
/*
* Copyright 2019 IBM All Rights Reserved.
*
* SPDX-License-Identifier: Apache-2.0
*/
package org.hyperledger.fabric.shim;
import static java.nio.charset.StandardCharsets.UTF_8;
import static java.util.stream.Collectors.toList;
import java.time.Instant;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
import org.hyperledger.fabric.protos.peer.ChaincodeEvent;
import org.hyperledger.fabric.protos.peer.SignedProposal;
import org.hyperledger.fabric.shim.Chaincode.Response;
import org.hyperledger.fabric.shim.ledger.CompositeKey;
import org.hyperledger.fabric.shim.ledger.KeyModification;
import org.hyperledger.fabric.shim.ledger.KeyValue;
import org.hyperledger.fabric.shim.ledger.QueryResultsIterator;
import org.hyperledger.fabric.shim.ledger.QueryResultsIteratorWithMetadata;
/**
* An object which manages the transaction context, provides access to state variables, and supports calls to other chaincode implementations.
*/
public interface ChaincodeStub {
/**
* Returns the arguments corresponding to the call to
* {@link Chaincode#init(ChaincodeStub)} or
* {@link Chaincode#invoke(ChaincodeStub)}, each argument represented as byte
* array.
*
* @return a list of arguments (bytes arrays)
*/
List getArgs();
/**
* Returns the arguments corresponding to the call to
* {@link Chaincode#init(ChaincodeStub)} or
* {@link Chaincode#invoke(ChaincodeStub)}, cast to UTF-8 string.
*
* @return a list of arguments cast to UTF-8 strings
*/
List getStringArgs();
/**
* 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.
*
* @return the function name
*/
String getFunction();
/**
* A convenience method that returns all except the first argument of the
* chaincode invocation for use as the parameters to the function returned by
* #{@link ChaincodeStub#getFunction()}.
*
* The bytes of the arguments are decoded as a UTF-8 strings and returned as a
* list of string parameters.
*
* @return a list of parameters
*/
List getParameters();
/**
* Returns the transaction id for the current chaincode invocation request.
*
* The transaction id uniquely identifies the transaction within the scope of
* the channel.
*
* @return the transaction id
*/
String getTxId();
/**
* 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.
*
* @return the channel id
*/
String getChannelId();
/**
* 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.
*
* @param chaincodeName Name of chaincode to be invoked.
* @param args Arguments to pass on to the called chaincode.
* @param channel If not specified, the caller's channel is assumed.
* @return {@link Response} object returned by called chaincode
*/
Response invokeChaincode(String chaincodeName, List args, String channel);
/**
* 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.
*
* @param key name of the value
* @return value the value read from the ledger
*/
byte[] getState(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.
*
* @param key key to get key level endorsement
* @return endorsement policy
*/
byte[] getStateValidationParameter(String key);
/**
* 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
*
* @param key name of the value
* @param value the value to write to the ledger
*/
void putState(String key, byte[] value);
/**
* Sets the key-level endorsement policy for key.
*
* @param key key to set key level endorsement
* @param value endorsement policy
*/
void setStateValidationParameter(String key, byte[] value);
/**
* 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.
*
* @param key name of the value to be deleted
*/
void delState(String key);
/**
* 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 {@link QueryResultsIterator#close()} object when
* done.
*
* @param startKey key as the start of the key range (inclusive)
* @param endKey key as the end of the key range (exclusive)
* @return an {@link Iterable} of {@link KeyValue}
*/
QueryResultsIterator getStateByRange(String startKey, String endKey);
/**
* 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
* ({@link org.hyperledger.fabric.protos.peer.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.
*
* @param startKey the start key
* @param endKey the end key
* @param pageSize the page size
* @param bookmark the bookmark
* @return QueryIterator
*/
QueryResultsIteratorWithMetadata getStateByRangeWithPagination(String startKey, String endKey, int pageSize, String bookmark);
/**
* Returns all existing keys, and their values, that are prefixed by the
* specified partial {@link 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 {@link CompositeKey}
* from a String and behaves exactly as
* {@link ChaincodeStub#getStateByPartialCompositeKey(CompositeKey)}.
*
*
* Call close() on the returned {@link QueryResultsIterator#close()} object when
* done.
*
* @param compositeKey partial composite key
* @return an {@link Iterable} of {@link KeyValue}
*/
QueryResultsIterator getStateByPartialCompositeKey(String compositeKey);
/**
* Returns all existing keys, and their values, that are prefixed by the
* specified partial {@link 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 {@link CompositeKey} and behaves exactly as
* {@link ChaincodeStub#getStateByPartialCompositeKey(CompositeKey)}.
*
* Call close() on the returned {@link QueryResultsIterator#close()} object when
* done.
*
* @param objectType ObjectType of the compositeKey
* @param attributes Attributes of the composite key
* @return an {@link Iterable} of {@link KeyValue}
*/
QueryResultsIterator getStateByPartialCompositeKey(String objectType, String... attributes);
/**
* Returns all existing keys, and their values, that are prefixed by the
* specified partial {@link CompositeKey}.
*
* If a full composite key is specified, it will not match itself, resulting in
* no keys being returned.
*
* @param compositeKey partial composite key
* @return an {@link Iterable} of {@link KeyValue}
*/
QueryResultsIterator getStateByPartialCompositeKey(CompositeKey compositeKey);
/**
* 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
* ({@link org.hyperledger.fabric.protos.peer.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.
*
* @param compositeKey the composite key
* @param pageSize the page size
* @param bookmark the bookmark
* @return QueryIterator
*/
QueryResultsIteratorWithMetadata getStateByPartialCompositeKeyWithPagination(CompositeKey compositeKey, int pageSize, String bookmark);
/**
* Given a set of attributes, this method combines these attributes to return a
* composite key.
*
* @param objectType A string used as the prefix of the resulting key
* @param attributes List of attribute values to concatenate into the key
* @return a composite key
*/
CompositeKey createCompositeKey(String objectType, String... attributes);
/**
* Parses a composite key {@link CompositeKey} from a string.
*
* @param compositeKey a composite key string
* @return a composite key
*/
CompositeKey splitCompositeKey(String compositeKey);
/**
* 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 {@link QueryResultsIterator} is returned which can be used to
* iterate (next) over the query result set.
*
* @param query query string in a syntax supported by the underlying state
* database
* @return {@link QueryResultsIterator} object contains query results
* @throws UnsupportedOperationException if the underlying state database does
* not support rich queries.
*/
QueryResultsIterator 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 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
* ({@link org.hyperledger.fabric.protos.peer.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.
*
* @param query the query
* @param pageSize the page size
* @param bookmark the bookmark
* @return QueryIterator
*/
QueryResultsIteratorWithMetadata getQueryResultWithPagination(String query, int pageSize, String bookmark);
/**
* 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.
*
* @param key The state variable key
* @return an {@link Iterable} of {@link KeyModification}
*/
QueryResultsIterator getHistoryForKey(String key);
/**
* Returns the value of the specified key from the specified
* collection.
*
* Note that {@link #getPrivateData(String, String)} doesn't read data from the
* private writeset, which has not been committed to the
* collection. In other words,
* {@link #getPrivateData(String, String)} doesn't consider data modified by
* {@link #putPrivateData(String, String, byte[])} * that has not been
* committed.
*
* @param collection name of the collection
* @param key name of the value
* @return value the value read from the collection
*/
byte[] getPrivateData(String collection, String key);
/**
* @param collection name of the collection
* @param key name of the value
* @return the private data hash
*/
byte[] getPrivateDataHash(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.
*
* @param collection name of the collection
* @param key key to get endorsement policy
* @return Key Level endorsement as byte array
*/
byte[] getPrivateDataValidationParameter(String collection, String key);
/**
* 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.
*
* @param collection name of the collection
* @param key name of the value
* @param value the value to write to the ledger
*/
void putPrivateData(String collection, String key, byte[] value);
/**
* Sets the key-level endorsement policy for the private data specified by
* key.
*
* @param collection name of the collection
* @param key key to set endorsement policy
* @param value endorsement policy
*/
void setPrivateDataValidationParameter(String collection, String key, byte[] value);
/**
* 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.
*
* @param collection name of the collection
* @param key name of the value to be deleted
*/
void delPrivateData(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.
*
* @param collection name of the collection
* @param key name of the value to be deleted
*/
void purgePrivateData(String collection, String key);
/**
* 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).
*
* @param collection name of the collection
* @param startKey private data variable key as the start of the key range
* (inclusive)
* @param endKey private data variable key as the end of the key range
* (exclusive)
* @return an {@link Iterable} of {@link KeyValue}
*/
QueryResultsIterator getPrivateDataByRange(String collection, String startKey, String endKey);
/**
* Returns all existing keys, and their values, that are prefixed by the
* specified partial {@link 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 {@link CompositeKey}
* from a String and behaves exactly as
* {@link ChaincodeStub#getPrivateDataByPartialCompositeKey(String, CompositeKey)}.
*
*
* @param collection name of the collection
* @param compositeKey partial composite key
* @return an {@link Iterable} of {@link KeyValue}
*/
QueryResultsIterator getPrivateDataByPartialCompositeKey(String collection, String compositeKey);
/**
* Returns all existing keys, and their values, that are prefixed by the
* specified partial {@link 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).
*
* @param collection name of the collection
* @param compositeKey partial composite key
* @return an {@link Iterable} of {@link KeyValue}
*/
QueryResultsIterator getPrivateDataByPartialCompositeKey(String collection, CompositeKey compositeKey);
/**
* Returns all existing keys, and their values, that are prefixed by the
* specified partial {@link 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 {@link CompositeKey} and behaves exactly as
* {@link ChaincodeStub#getPrivateDataByPartialCompositeKey(String, CompositeKey)}.
*
*
* @param collection name of the collection
* @param objectType ObjectType of the compositeKey
* @param attributes Attributes of the composite key
* @return an {@link Iterable} of {@link KeyValue}
*/
QueryResultsIterator getPrivateDataByPartialCompositeKey(String collection, String objectType, String... attributes);
/**
* 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.
*
* @param collection name of the collection
* @param query query string in a syntax supported by the underlying state
* database
* @return {@link QueryResultsIterator} object contains query results
* @throws UnsupportedOperationException if the underlying state database does
* not support rich queries.
*/
QueryResultsIterator getPrivateDataQueryResult(String collection, String query);
/**
* 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.
*
* @param name Name of event. Cannot be null or empty string.
* @param payload Optional event payload.
*/
void setEvent(String name, byte[] payload);
/**
* Invoke another chaincode using the same transaction context.
*
* Same as {@link #invokeChaincode(String, List, String)} using channelId to
* null
*
* @param chaincodeName Name of chaincode to be invoked.
* @param args Arguments to pass on to the called chaincode.
* @return {@link Response} object returned by called chaincode
*/
default Response invokeChaincode(final String chaincodeName, final List args) {
return invokeChaincode(chaincodeName, args, null);
}
/**
* Invoke another chaincode using the same transaction context.
*
* This is a convenience version of
* {@link #invokeChaincode(String, List, String)}. The string args will be
* encoded into as UTF-8 bytes.
*
* @param chaincodeName Name of chaincode to be invoked.
* @param args Arguments to pass on to the called chaincode.
* @param channel If not specified, the caller's channel is assumed.
* @return {@link Response} object returned by called chaincode
*/
default Response invokeChaincodeWithStringArgs(final String chaincodeName, final List args, final String channel) {
return invokeChaincode(chaincodeName, args.stream().map(x -> x.getBytes(UTF_8)).collect(toList()), channel);
}
/**
* Invoke another chaincode using the same transaction context.
*
* This is a convenience version of {@link #invokeChaincode(String, List)}. The
* string args will be encoded into as UTF-8 bytes.
*
* @param chaincodeName Name of chaincode to be invoked.
* @param args Arguments to pass on to the called chaincode.
* @return {@link Response} object returned by called chaincode
*/
default Response invokeChaincodeWithStringArgs(final String chaincodeName, final List args) {
return invokeChaincodeWithStringArgs(chaincodeName, args, null);
}
/**
* Invoke another chaincode using the same transaction context.
*
* This is a convenience version of {@link #invokeChaincode(String, List)}. The
* string args will be encoded into as UTF-8 bytes.
*
* @param chaincodeName Name of chaincode to be invoked.
* @param args Arguments to pass on to the called chaincode.
* @return {@link Response} object returned by called chaincode
*/
default Response invokeChaincodeWithStringArgs(final String chaincodeName, final String... args) {
return invokeChaincodeWithStringArgs(chaincodeName, Arrays.asList(args), null);
}
/**
* 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 {@link #getState(String)}
*
* @param key name of the value
* @return value the value read from the ledger
*/
default String getStringState(final String key) {
return new String(getState(key), UTF_8);
}
/**
* Writes the specified value and key into the sidedb collection value converted
* to byte array.
*
* @param collection collection name
* @param key name of the value
* @param value the value to write to the ledger
*/
default void putPrivateData(final String collection, final String key, final String value) {
putPrivateData(collection, key, value.getBytes(UTF_8));
}
/**
* Returns the byte array value specified by the key and decoded as a UTF-8
* encoded string, from the sidedb collection.
*
* @param collection collection name
* @param key name of the value
* @return value the value read from the ledger
*/
default String getPrivateDataUTF8(final String collection, final String key) {
return new String(getPrivateData(collection, key), UTF_8);
}
/**
* Writes the specified value and key into the ledger.
*
* @param key name of the value
* @param value the value to write to the ledger
*/
default void putStringState(final String key, final String value) {
putState(key, value.getBytes(UTF_8));
}
/**
* Returns the CHAINCODE type event that will be posted to interested clients
* when the chaincode's result is committed to the ledger.
*
* @return the chaincode event or null
*/
ChaincodeEvent getEvent();
/**
* Returns the signed transaction proposal currently being executed.
*
* @return null if the current transaction is an internal call to a system
* chaincode.
*/
SignedProposal getSignedProposal();
/**
* Returns the timestamp when the transaction was created.
*
* @return timestamp as specified in the transaction's channel header.
*/
Instant getTxTimestamp();
/**
* Returns the identity of the agent (or user) submitting the transaction.
*
* @return the bytes of the creator field of the proposal's signature header.
*/
byte[] getCreator();
/**
* Returns the transient map associated with the current transaction.
*
* @return map of transient field
*/
Map getTransient();
/**
* Returns the transaction binding.
*
* @return binding between application data and proposal
*/
byte[] getBinding();
/**
* Get the MSPID of the peer that started this chaincode.
*
* @return string MSPID
*/
String getMspId();
}