Develop Chaincode CRD

[bjwswang]

• samples in fabric-operator: https://github.com/bestchains/fabric-operator/blob/main/sample-network/scripts/run-e2e-test.sh#L80
• official document: https://hyperledger-fabric.readthedocs.io/en/release-1.3/chaincode4noah.html
• official document on chaincode external builder: https://hyperledger-fabric.readthedocs.io/en/latest/cc_launcher.html#external-builders-and-launchers

Prerequisites before Chaincode

• a active Federation
• a active Network
• a active Channel
  • at least one peer joined

After a Channel created successfully, we can use Chaincode to deploy a blockchain contract

Design

We use fabric-builder-k8s as the external builder to manage chaincodes

type ChaincodeSpec struct {
    License License `json:"license"`
    Channel string `json:"channel"`
        ID string `json:"id"`
        Version string `json:"version"`
        EndorsePolicyRef `json:"endorsePolicyRef,omitempty"`
        ExternalBuilder string `json:"externalBuilder,omitempty"`
        Images map[string]ChaincodeImage `json:"images,omitempty"`
}

type EndorsePolicyRef struct {
    Name string `json:"name,omitempty"`
}

type ChaincodeImage struct {
       Name string    `json:"name,omitempty"`
       Digest string   `json:"digest,omitempty"`
       PullSecret string `json:"pullSecret,omitempty"`
}

type ChaincodePhase string
const (
   ChaincodePending ChaincodePhase = "ChaincodePending"
   ChaincodeApproved  ChaincodePhase  = "ChaincodeApproved"
   ChaincodeUnapproved ChaincodePhase  = "ChaincodeUnapproved"
)

type ChaincodeConditionType string
const (
   ChaincodePackaged ChaincodeConditionType = "Packaged" // chaincode package succ
   ChaincodeInstalled ChaincodeConditionType = "Installed" // chaincode install succ on peer
   ChaincodeApproved  ChaincodeConditionType  = "Approved" //  chaincode approved by  peer
   ChaincodeCommitted ChaincodeConditionType  = "Committed" // chaincode committed to blockchain
   ChaincodeRunning ChaincodeConditionType  = "Running"
   ChaincodeError ChaincodeConditionType = "Error" // error when install/approve/commit
)

type ChaincodeCondition struct {
    // Type is the type of the condition.
    Type ChaincodeConditionType `json:"type"`
    // Status is the status of the condition.
    // Can be True, False, Unknown.
    Status metav1.ConditionStatus `json:"status"`
    // Last time the condition transitioned from one status to another.
    // +optional
    LastTransitionTime metav1.Time `json:"lastTransitionTime,omitempty"`
    // Unique, one-word, CamelCase reason for the condition's last transition.
    // +optional
    Reason string `json:"reason,omitempty"`
    // Human-readable message indicating details about last transition.
    // +optional
    Message string `json:"message,omitempty"`
}

type ChaincodeHistory struct {
       Version string
       Image ChaincodeImage
}

type ChaincodeStatus struct {
     History []ChaincodeHistory `json:"history"`
      Phase   ChaincodePhase `json:"phase"`
     Conditions []ChaincodeCondition `json:"conditions"`

      Message string `json:"message,omitempty"`

       Reason string `json:"reason,omitempty"`
}

// Proposal_types.go
type DeployChaincodeProposal struct {
     Chaincode string `json:"chaincode"`
}

type UpgradeChaincodeProposal struct {
     Chaincode string `json:"chaincode"`
     NewVersion string `json:"newVersion"`
     NewChaincodeImage ChaincodeImage `json:"newChaincodeImage"`
}

Operations on Chaincode(fabric builder k8s)

Prerequsities

1. fabric peer must use image built from https://github.com/bestchains/fabric-builder-k8s/blob/main/Dockerfile
2. build chaincode image,then get image digest like https://github.com/bestchains/fabric-builder-k8s/tree/main/samples/go-contract

deploy a new Chaincode

1. create a CR Chaincode.must provide:

- Channel
- Name
- Version
- EndorsePolicy
- Chaincode image for this version

2. create a proposal DeployChaincode(Only ALL is allowed at this kind of proposal)

• create votes to all channel members

3. every channel member votes

• if anyone vote no,this proposal fails
• if everyone vote yes,this proposal succ

4. reconcile proposal result

4.1 reconcile propsoal fail

• mark chaincode's phase as unapproved

4.2 reconcile proposal succ

• mark chaincode's phase as approved

5. reconcile if approved

1. package chaincode like https://github.com/hyperledgendary/conga-nft-contract/releases/download/v0.1.1/conga-nft-contract-v0.1.1.tgz

• if succ,append condition ChaincodePackaged
• if fail, append condition ChaincodeError with error message

2. install chaincode to all channel peers https://github.com/bestchains/fabric-operator/blob/main/sample-network/scripts/run-e2e-test.sh#L92

• if succ,append condition ChaincodeInstalled
• if fail, append condition ChaincodeError with error message

3. do approve chaincode for each member org https://github.com/bestchains/fabric-operator/blob/main/sample-network/scripts/run-e2e-test.sh#L96

• if succ,append condition ChaincodeApproved
• if fail, append condition ChaincodeError with error message

4. do commit chaincode by any org in this channel https://github.com/bestchains/fabric-operator/blob/main/sample-network/scripts/run-e2e-test.sh#L107

• if succ,append condition ChaincodeCommitted
• if fail, append condition ChaincodeError with error message

5. check chaincode service status https://github.com/bestchains/fabric-operator/blob/main/sample-network/scripts/run-e2e-test.sh#L117

• if succ,append condition ChaincodeRunning
• if fail, append condition ChaincodeError with error message

upgrade a Chaincode

1. create a proposal UpgradeChaincode

2. member votes on UpgradeChaincode

3. when UpgradeChaincode ends

3.1 when succ

1. update CR Chaincode
   • spec.version : set from UpgradeChaincode
   • spec. Images: set from UpgradeChaincode
   • status.history append previous chaincode version

3.2 when fail

do nothing

4. reconcile Chaincode update

1. redo - reconcile Chaincode create

• package
• install
• approve
• commit
• check chaincode service status

delete a Chaincode

only when chaincode.status is unapproved

[bjwswang]

Sub tasks:

• [x] investigate fabric chaincode deploy process and external builder
• [x] build fabric-peer image with external builder k8s
• [x] develp CRD EndorsePolicy fixed by https://github.com/bestchains/fabric-operator/pull/131
• [ ] create Chaincode API and basic controller logic
• [ ] develop proposal deployChaincode
• [ ] develop Chaincode reconcile logic upon proposal deployChaincode succ
• [ ] develop proposal upgradeChaincode
• [ ] develop Chaincode reconcile logic upon proposal upgradeChaincode succ