Key-Level Endorsement Policies

By default, endorsement policies are specified for a channel chaincode at instantiation or upgrade time (i.e., a single endorsement policy covers all of the states associated with a chaincode). We have discussed chaincode-level endorsement policies in The chaincode lifecycle chapter.

However, there are cases where it may be necessary for a particular state (a particular key-value pair, in other words) to have a different endorsement policy. This state-based endorsement allows default chaincode-level endorsement policies to be overridden by a different policy for the specified keys.

To illustrate the circumstances in which these two types of endorsement policies might be used, consider a channel where cars are being exchanged. The “creation,” also known as “issuance,” of a car as an asset that can be traded (putting the key-value pair that represents it into the world state,) would have to satisfy the chaincode-level endorsement policy.

If the car requires a specific endorsement policy, it can be defined either when the car is created or afterwards. There are a number of reasons why it might be necessary or preferable to set a state-specific endorsement policy. The car might have historical importance or value that makes it necessary to have the endorsement of a licensed appraiser. Furthermore, the owner of the car (if s/he is a member of the channel) might also want to ensure that their peer signs off on a transaction. In both cases, an endorsement policy is required for a particular asset that is different from the default endorsement policies for the other assets associated with that chaincode.

Setting regular chaincode-level endorsement policies is tied to the lifecycle of the corresponding chaincode. They can only be set or modified when deploying or upgrading the corresponding chaincode on a channel.

In contrast, key-level endorsement policies can be set and modified in a more granular fashion from within a chaincode. The modification is part of the read-write set of a regular transaction.

If set, the key-level endorsement policy overrides the chaincode-level one for a specific key-value pair. In practice, this means that the key-level endorsement policy can be either less restrictive or more restrictive than the chaincode-level endorsement policy. As the chaincode-level endorsement policy must be satisfied in order to set a key-level endorsement policy for the first time, no trust assumptions have been violated.

If a transaction modifies multiple keys with different associated key-level endorsement policies, all of these policies need to be satisfied in order for the transaction to be valid.

The fabric-shim API (particularly ChaincodeStub interface) provides the following functions to set and retrieve an endorsement policy for/from a regular key:

• setStateValidationParameter(key: string, ep: Uint8Array): Promise<void>

• getStateValidationParameter(key: string): Promise<Uint8Array>

In the above-mentioned functions, ep stands for the “endorsement policy,” which can be expressed by using the signature policy syntax discussed in The Chaincode Lifecycle chapter.