Endorsement Policies

Every chaincode has an endorsement policy specifying a set of peers on a channel that must execute the chaincode and endorse the execution results for a transaction to be valid. Endorsement policies define those organizations that have to endorse, or approve, the execution of a proposal.

The chaincode endorsement policy can be specified at the deployment or upgrade time in the chaincode definition, using the --signature-policy argument followed by the policy below:

peer lifecycle chaincode approveformyorg -o orderer.example.com:7050 --channelID mychannel --name chaincode --version 1.0 --package-id $CC_PACKAGE_ID --sequence 1 --signature-policy "OR('Org1MSP.member','Org2MSP.member')"

As you can see above, policies are expressed in terms of principals — identities matched to a role. Principals are described as 'MSP.ROLE', where MSP represents the required MSP ID and ROLE represents one of the four accepted roles: member, admin, client, and peer.

Below are the examples of valid principals:

• 'Org0MSP.admin', any administrator of the Org0 MSP

• 'Org1MSP.member', any member of the Org1 MSP

• 'Org1MSP.client', any client of the Org1 MSP

• 'Org1MSP.peer', any peer of the Org1 MSP.

Endorsement policies can be composed with the help of a domain-specific language (DSL) with the following expressions:

• AND(P1,…,PN) requires a signature from each of the principles P1,…,PN

• OR(P1,…,PN) requires at least one signature from the principles P1,…,PN

• OutOf(n, P1,…,PN) requires at least n signatures from the principles P1,…,PN

These expressions can be combined (one expression can take another as an argument) to create flexible endorsement policies for any case, e.g.,

AND('Org1MSP.member', OutOf(2, 'Org2MSP.member', 'Org3MSP.member', 'Org4MSP.member'))

means that signatures are required from Org1 and at least two out of three organizations Org2, Org3, and Org4.

In addition to specifying an endorsement policy using the --signature-policy argument, a chaincode can also use channel configuration policies as endorsement policies. The --channel-config-policy flag can be used to select a channel policy with format used by the channel configuration and by ACLs. An example of such a policy is demonstrated below.

peer lifecycle chaincode approveformyorg -o orderer.example.com:7050 --channelID mychannel --name chaincode --version 1.0 --package-id $CC_PACKAGE_ID --sequence 1 --channel-config-policy Channel/Application/Admins

The advantage of using channel policies over signature ones is that they can be written to be updated automatically when organizations are added to or removed from a channel. If no policy is specified, the chaincode definition will use the Channel/Application/Endorsement policy by default, which requires a transaction to be validated by a majority of channel members.

If a signature policy is set, it will not be automatically updated when parties join or leave the channel. A new organization added to the channel after the chaincode has been defined will be able to query a chaincode but will not be able to execute or endorse the chaincode. Only organizations listed in the endorsement policy syntax will be able to sign transactions. Therefore, signature policies should be carefully managed to grant sufficient rights to all the participants.

The endorsement policies described in this section are set at the chaincode deployment time and cover all of the states associated with a chaincode. However, there are cases where it may be necessary for a particular key-value pair to have a different endorsement policy. Additional policies can be required to manage private data.