合约升级

原文地址:https://docs.corda.net/contract-upgrade.html

虽然在开发合约代码的过程中我们会非常小心,但是由于解决 bug(设计或者实施)升级还是不可避免的。升级可能会涉及到将合约代码从一个版本升级到另一个版本,或者变成另一个不同的合约,这个合约知道应该如何升级已有的 state 对象。当 state 对象作为 outputs 被添加到 transactions 的时候,通过 StateAndContract 类型,他们被连关联到他们要用的合约代码。修改 state 的合约代码只需要将 ContractClassName 替换成另外的名字。

升级流程 Workflow

下边是升级合约的流程:

  1. Bank A 和 B 在线下协商了一笔交易
  2. Bank A 和 B 执行了一个 flow 来构建了一个 state 对象来表示这笔交易,使用的是合约 X,并将它放到了一个 transaction 中(接下来会被签名并发送到共识服务,即 Notary Service)
  3. 一段时间过去了
  4. 合约 X 的开发者发现了合约代码中的一个 bug,然后就发布了一个新的版本,合约 Y。开发者接下来会通知所有已有的用户(比如使用一个邮件列表或者 CorDapp store)来停止他们的节点继续用合约 X 来初始新的 states 对象
  5. Bank A 和 B 通过标准的改动控制流程(change control process)来 review 新的合约代码并且识别他们同意升级的合约 states(他们可能会选择不升级某些合约 states,因为这些 states 可能被其他的一些债务合约在使用)
  6. Bank A 和 B 会告诉他们的节点(通过 RPC)将会使用双方同意的更新途径来将使用合约 X 的 state 对象更新到使用合约 Y 的 state 对象
  7. 相关方的某一方(Initiator)会初始一个 flow 来将使用合约 X 的 state 对象替换为新的使用合约 Y 的 state 对象
  8. 一个将老的 states 作为 input,将新的 states 作为 output 的 transaction(Proposal)被提出并且被使用节点的私钥进行了签名。
  9. 初始(Initiator)节点将这个 transaction 和关于如何更新到新的合约的途径详细信息发送给 state 对象的所有参与者。
  10. 每个合作方(Acceptor)验证这个提议,签名或者拒绝这个重新生成 state 的提议,然后将签名或者拒绝的结果发送给初始节点
  11. 如果从所有相关节点都收到了签名的话,Initiator 节点会整理这个完全被签署过的 transaction 并且发送给 notary

批准一个更新 Authorising an upgrade

在升级可以开始之前,将要被升级的 state 中的参与者们(participants)需要告诉他们的节点他们已经同意了这个更新。ContractUpgradeFlow 被用来管理这个授权的流程。对于将要执行的更新 state 的 flow,每个节点的管理员可以使用 RPC 来触发一个批准或不批准的命令。

@StartableByRPC
class Authorise(
        val stateAndRef: StateAndRef<*>,
        private val upgradedContractClass: Class<out UpgradedContract<*, *>>
) : FlowLogic<Void?>() {
@StartableByRPC
class Deauthorise(val stateRef: StateRef) : FlowLogic<Void?>() {
    @Suspendable
    override fun call(): Void? {

提出一个更新 Proposing an upgrade

当所有的节点都批准了对于 state 的合约更新之后,某一个合约的参与者可以通过触发 ContractUpgradeFlow.Initiate flow 来初始这个更新的流程。Initiate 创建了一个包含旧的 state 和更新的 state 的 transaction,然后发送给了每一个 state 的参与者。每个参与者都会检查这个 transaction,提供签名并将签名发送回给变更初始者。当收到所有的签名之后,这个 transaction 会被公正并且永久地被存储到每个参与者的账本(vault)中。

示例

假设 Bank A 和 Bank B 达成了一个协议,这个协议以 DummyContractState state 对象来表示。当交换完合约之后的某天,合约代码的开发者发现额合约代码中的一个 bug。

Bank A 和 Bank B 决定将合约升级为 DummyContractV2

  1. 开发者通过扩展 UpgradedContract 类创建了一个新的合约 DummyContractV2,和一个新的针对新合约的 state 对象 DummyContractV2.State

    class DummyContractV2 : UpgradedContractWithLegacyConstraint<DummyContract.State, DummyContractV2.State> {
    companion object {
        const val PROGRAM_ID: ContractClassName = "net.corda.testing.contracts.DummyContractV2"
    }
    
    override val legacyContract: String = DummyContract::class.java.name
    override val legacyContractConstraint: AttachmentConstraint = AlwaysAcceptAttachmentConstraint
    
    data class State(val magicNumber: Int = 0, val owners: List<AbstractParty>) : ContractState {
        override val participants: List<AbstractParty> = owners
    }
    
    interface Commands : CommandData {
        class Create : TypeOnlyCommandData(), Commands
        class Move : TypeOnlyCommandData(), Commands
    }
    
    override fun upgrade(state: DummyContract.State): State {
        return State(state.magicNumber, state.participants)
    }
    
    override fun verify(tx: LedgerTransaction) {
        // Other verifications.
    }
  2. Bank A 告诉他的节点接受这个针对于 contract state 的合约更新。
    val rpcClient : CordaRPCClient = << Bank A's Corda RPC Client >>
    val rpcA = rpcClient.proxy()
    rpcA.startFlow(ContractUpgradeFlow.Authorise(<<StateAndRef of the contract state>>, DummyContractV2::class.java))
  3. Bank B 初始了这个升级的 flow,这会给所有的合约的参与者节点发送一个更新的提议。合约 state 的每个参与者,当他们验证完并且同意这个更新之后,将会提供签名并返回合约 state 的更新提议。Flow 会将被更新的 transaction 记录到每个参与节点中。
    val rpcClient : CordaRPCClient = << Bank B's Corda RPC Client >>
    val rpcB = rpcClient.proxy()
    rpcB.startFlow({ stateAndRef, upgrade -> ContractUpgradeFlow(stateAndRef, upgrade) },
    <<StateAndRef of the contract state>>,
    DummyContractV2::class.java)