Upgrading Channels

enum ChannelState {
  INIT,
  TRYOPEN,
  OPEN,
  FLUSHING,
  FLUSHCOMPLETE,
}

interface ChannelEnd {
  state: ChannelState
  ordering: ChannelOrder
  counterpartyPortIdentifier: Identifier
  counterpartyChannelIdentifier: Identifier
  connectionHops: [Identifier]
  version: string
  upgradeSequence: uint64
}

interface UpgradeFields {
  version: string
  ordering: ChannelOrder
  connectionHops: [Identifier]
}

interface Timeout {
  timeoutHeight: Height
  timeoutTimestamp: uint64
}

interface Upgrade {
  fields: UpgradeFields
  timeout: Timeout
  nextSequenceSend: uint64
}

interface ErrorReceipt {
  sequence: uint64
  errorMsg: string
}

function channelUpgradePath(portIdentifier: Identifier, channelIdentifier: Identifier): Path {
  return "channelUpgrades/upgrades/ports/{portIdentifier}/channels/{channelIdentifier}"
}

// Connection VerifyChannelUpgrade method
function verifyChannelUpgrade(
  connection: ConnectionEnd,
  height: Height,
  proof: CommitmentProof,
  counterpartyPortIdentifier: Identifier,
  counterpartyChannelIdentifier: Identifier,
  upgrade: Upgrade
) {
  clientState = queryClientState(connection.clientIdentifier)
  path = applyPrefix(
    connection.counterpartyPrefix, 
    channelUpgradePath(counterpartyPortIdentifier, counterpartyChannelIdentifier)
  )
  return verifyMembership(clientState, height, 0, 0, proof, path, upgrade)
}

function counterpartyUpgradePath(portIdentifier: Identifier, channelIdentifier: Identifier): Path {
    return "channelUpgrades/counterpartyUpgrade/ports/{portIdentifier}/channels/{channelIdentifier}"
}

function channelUpgradeErrorPath(portIdentifier: Identifier, channelIdentifier: Identifier): Path {
    return "channelUpgrades/upgradeError/ports/{portIdentifier}/channels/{channelIdentifier}"
}

// Connection VerifyChannelUpgradeError method
function verifyChannelUpgradeError(
  connection: ConnectionEnd,
  height: Height,
  proof: CommitmentProof,
  counterpartyPortIdentifier: Identifier,
  counterpartyChannelIdentifier: Identifier,
  upgradeErrorReceipt: ErrorReceipt
) {
  clientState = queryClientState(connection.clientIdentifier)
  path = applyPrefix(
    connection.counterpartyPrefix, 
    channelUpgradeErrorPath(counterpartyPortIdentifier, counterpartyChannelIdentifier)
  )
  return verifyMembership(clientState, height, 0, 0, proof, path, upgradeErrorReceipt)
}

// initUpgradeHandshake will verify that the channel is in the
// correct precondition to call the initUpgradeHandshake protocol.
// it will verify the new upgrade field parameters, and make the
// relevant state changes for initializing a new upgrade:
// - store channel upgrade
// - incrementing upgrade sequence
function initUpgradeHandshake(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  proposedUpgradeFields: UpgradeFields,
): uint64 {
  // current channel must be OPEN
  // If channel already has an upgrade but isn't in FLUSHING,
  // then this will override the previous upgrade attempt
  channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
  abortTransactionUnless(channel.state === OPEN)

  // new channel version must be nonempty
  abortTransactionUnless(proposedUpgradeFields.Version !== "")

  // proposedConnection must exist and be in OPEN state for 
  // channel upgrade to be accepted
  proposedConnection = provableStore.get(connectionPath(proposedUpgradeFields.connectionHops[0]))
  abortTransactionUnless(proposedConnection !== null && proposedConnection.state === OPEN)

  // new order must be supported by the new connection
  abortTransactionUnless(isSupported(proposedConnection, proposedUpgradeFields.ordering))

  // nextSequenceSend and timeout will be filled when we move to FLUSHING
  upgrade = Upgrade{
    fields: proposedUpgradeFields,
  }

  // store upgrade in provable store for counterparty proof verification
  provableStore.set(channelUpgradePath(portIdentifier, channelIdentifier), upgrade)

  channel.upgradeSequence = channel.upgradeSequence + 1
  provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)
  return channel.upgradeSequence
}

function isCompatibleUpgradeFields(
  proposedUpgradeFields: UpgradeFields,
  counterpartyUpgradeFields: UpgradeFields,
): boolean {
  if (proposedUpgradeFields.ordering != counterpartyUpgradeFields.ordering) {
    return false
  }
  if (proposedUpgradeFields.version != counterpartyUpgradeFields.version) {
    return false
  }

  // connectionHops can change in a channel upgrade, however both sides must
  // still be each other's counterparty. Since connection hops may be provided
  // by relayer, we will abort to avoid changing state based on relayer-provided value
  // Note: If the proposed connection came from an existing upgrade, then the 
  // off-chain authority is responsible for replacing one side's upgrade fields
  // to be compatible so that the upgrade handshake can proceed
  proposedConnection = provableStore.get(connectionPath(proposedUpgradeFields.connectionHops[0]))
  if (proposedConnection == null || proposedConnection.state != OPEN) {
    return false
  }
  if (counterpartyUpgradeFields.connectionHops[0] != proposedConnection.counterpartyConnectionIdentifier) {
    return false
  }
  return true
}

// startFlushUpgradeHandshake will verify that the channel
// is in a valid precondition for calling the startFlushUpgradeHandshake.
// it will set the channel to flushing state.
// it will store the nextSequenceSend and upgrade timeout in the upgrade state.
function startFlushUpgradeHandshake(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
) {
  channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
  abortTransactionUnless(channel.state === OPEN)

  upgrade = provableStore.get(channelUpgradePath(portIdentifier, channelIdentifier))
  abortTransactionUnless(upgrade !== null)

  channel.state = FLUSHING

  upgradeTimeout = getUpgradeTimeout(channel.portIdentifier, channel.channelIdentifier)
  // either timeout height or timestamp must be non-zero
  abortTransactionUnless(upgradeTimeout.timeoutHeight != 0 || upgradeTimeout.timeoutTimestamp != 0)

  nextSequenceSend = provableStore.get(nextSequenceSendPath(portIdentifier, channelIdentifier))

  upgrade.timeout = upgradeTimeout
  upgrade.nextSequenceSend = nextSequenceSend
  
  // store upgrade in public store for counterparty proof verification
  provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)
  provableStore.set(channelUpgradePath(portIdentifier, channelIdentifier), upgrade)
}

// openUpgradeHandshake will switch the channel fields 
// over to the agreed upon upgrade fields.
// it will reset the channel state to OPEN.
// it will delete auxiliary upgrade state.
// caller must do all relevant checks before calling this function.
function openUpgradeHandshake(
  portIdentifier: Identifier,
  channelIdentifier: Identifier
) {
  channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
  upgrade = provableStore.get(channelUpgradePath(portIdentifier, channelIdentifier))

  // if channel order changed, we need to set
  // the recv and ack sequences appropriately
  if channel.order == "UNORDERED" && upgrade.fields.ordering == "ORDERED" {
    selfNextSequenceSend = provableStore.get(nextSequenceSendPath(portIdentifier, channelIdentifier))
    counterpartyUpgrade = privateStore.get(counterpartyUpgradePath(portIdentifier, channelIdentifier))

    // set nextSequenceRecv to the counterparty nextSequenceSend since all packets were flushed
    provableStore.set(nextSequenceRecvPath(portIdentifier, channelIdentifier), counterpartyUpgrade.nextSequenceSend)
    // set nextSequenceAck to our own nextSequenceSend since all packets were flushed
    provableStore.set(nextSequenceAckPath(portIdentifier, channelIdentifier), selfNextSequenceSend)
  } else if channel.order == "ORDERED" && upgrade.fields.ordering == "UNORDERED" {
    // reset recv and ack sequences to 1 for UNORDERED channel
    provableStore.set(nextSequenceRecvPath(portIdentifier, channelIdentifier), 1)
    provableStore.set(nextSequenceAckPath(portIdentifier, channelIdentifier), 1)
  }

  // switch channel fields to upgrade fields
  // and set channel state to OPEN
  channel.ordering = upgrade.fields.ordering
  channel.version = upgrade.fields.version
  channel.connectionHops = upgrade.fields.connectionHops
  channel.state = OPEN
  provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)

  // IMPLEMENTATION DETAIL: Implementations may choose to prune stale acknowledgements and receipts at this stage
  // Since flushing has completed, any acknowledgement or receipt written before the chain went into flushing has
  // already been processed by the counterparty and can be removed.
  // Implementations may do this pruning work over multiple blocks for gas reasons. In this case, they should be sure
  // to only prune stale acknowledgements/receipts and not new ones that have been written after the channel has reopened.
  // Implementations may use the counterparty NextSequenceSend as a way to determine which acknowledgement/receipts
  // were already processed by counterparty when flushing completed

  // delete auxiliary state
  provableStore.delete(channelUpgradePath(portIdentifier, channelIdentifier))
  privateStore.delete(counterpartyUpgradePath(portIdentifier, channelIdentifier))
}

// restoreChannel will restore the channel state to its pre-upgrade state
// and delete upgrade auxiliary state so that upgrade is aborted.
// it writes an error receipt to state so counterparty can restore as well.
// NOTE: this function signature may be modified by implementers to take a custom error
function restoreChannel(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
) {
  channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
  errorReceipt = ErrorReceipt{
    channel.upgradeSequence,
    "upgrade handshake is aborted", // constant string changeable by implementation
  }
  provableStore.set(channelUpgradeErrorPath(portIdentifier, channelIdentifier), errorReceipt)
  channel.state = OPEN
  provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)

  // delete auxiliary state
  provableStore.delete(channelUpgradePath(portIdentifier, channelIdentifier))
  privateStore.delete(counterpartyUpgradePath(portIdentifier, channelIdentifier))
}

// pendingInflightPacketSequences returns the packet sequences sent on 
// this end that have not had their lifecycle completed
function pendingInflightPacketSequences(
  portIdentifier: Identifier,
  channelIdentifier: Identifier
): [uint64]

// isAuthorizedUpgrader
function isAuthorizedUpgrader(address: string): boolean

// getUpgradeTimeout
function getUpgradeTimeout(portIdentifier: string, channelIdentifier: string) Timeout {
}

// Channel Ends on both sides **must** be OPEN before this function is called
// It is the responsibility of the authorized upgrader to ensure this is the case
function chanUpgradeInit(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  proposedUpgradeFields: UpgradeFields,
  msgSender: string,
) {
  // chanUpgradeInit may only be called by addresses authorized by executing chain
  abortTransactionUnless(isAuthorizedUpgrader(msgSender))

  // if a previous upgrade attempt exists, then delete it and write error receipt, so
  // counterparty can abort it and move to next upgrade
  existingUpgrade = provableStore.get(channelUpgradePath(portIdentifier, channelIdentifier))
  if existingUpgrade != null {
    provableStore.delete(channelUpgradePath(portIdentifier, channelIdentifier))
    errorReceipt = ErrorReceipt{
      channel.upgradeSequence,
      "abort the previous upgrade attempt so counterparty can accept the new one", // constant string changeable by implementation
    }
    provableStore.set(channelUpgradeErrorPath(portIdentifier, channelIdentifier), errorReceipt)
  }

  upgradeSequence = initUpgradeHandshake(portIdentifier, channelIdentifier, proposedUpgradeFields)

  // call modules onChanUpgradeInit callback
  // onChanUpgradeInit may return a new proposed version
  // if an error is returned the upgrade is not written
  // the callback MUST NOT write state, as all state transitions will occur once
  // the channel upgrade is complete.
  module = lookupModule(portIdentifier)
  version, err = module.onChanUpgradeInit(
    portIdentifier,
    channelIdentifier,
    upgradeSequence,
    proposedUpgradeFields.ordering,
    proposedUpgradeFields.connectionHops,
    proposedUpgradeFields.version
  )
  // abort transaction if callback returned error
  abortTransactionUnless(err === null)

  // replace channel upgrade version with the version returned by application
  // in case it was modified
  upgrade = provableStore.get(channelUpgradePath(portIdentifier, channelIdentifier))
  upgrade.fields.version = version
  provableStore.set(channelUpgradePath(portIdentifier, channelIdentifier), upgrade)
}

function chanUpgradeTry(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  counterpartyUpgrade: Upgrade,
  counterpartyUpgradeSequence: uint64,
  proposedConnectionHops: [Identifier],
  proofChannel: CommitmentProof,
  proofUpgrade: CommitmentProof,
  proofHeight: Height
) {
  // current channel must be OPEN (i.e. not in FLUSHING)
  channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
  abortTransactionUnless(channel.state === OPEN)

  // construct counterpartyChannel from existing information and provided
  // counterpartyUpgradeSequence
  counterpartyChannel = ChannelEnd{
    state: OPEN,
    ordering: channel.ordering,
    counterpartyPortIdentifier: portIdentifier,
    counterpartyChannelIdentifier: channelIdentifier,
    connectionHops: counterpartyHops,
    version: channel.version,
    sequence: counterpartyUpgradeSequence,
  }

  // verify proofs of counterparty state
  abortTransactionUnless(
    verifyChannelState(
      connection,
      proofHeight,
      proofChannel,
      channel.counterpartyPortIdentifier,
      channel.counterpartyChannelIdentifier,
      counterpartyChannel
    )
  )
  abortTransactionUnless(
    verifyChannelUpgrade(
      connection,
      proofHeight,
      proofUpgrade,
      channel.counterpartyPortIdentifier,
      channel.counterpartyChannelIdentifier,
      counterpartyUpgrade
    )
  )

  existingUpgrade = provableStore.get(channelUpgradePath(portIdentifier, channelIdentifier))
  if existingUpgrade != null {
    expectedUpgradeSequence = channel.UpgradeSequence
  } else {
    // at the end of the TRY step, the current upgrade sequence will be incremented in the non-crossing
    // hello case due to calling chanUpgradeInit, we should use this expected upgrade sequence for
    // sequence mismatch comparison
    expectedUpgradeSequence = channel.UpgradeSequence + 1
  }

  // NON CROSSING HELLO CASE:
  // if the counterparty sequence is less than or equal to the current sequence,
  // then either the counterparty chain is out-of-sync or the message
  // is out-of-sync and we write an error receipt with our sequence
  // so that the counterparty can abort their attempt and resync with our sequence.
  // When the next upgrade attempt is initiated, both sides will move to a fresh
  // never-before-seen sequence number
  // CROSSING HELLO CASE:
  // if the counterparty sequence is less than the current sequence,
  // then either the counterparty chain is out-of-sync or the message
  // is out-of-sync and we write an error receipt with our sequence minus one
  // so that the counterparty can update their sequence as well.
  // This will cause the outdated counterparty to upgrade the sequence
  // and abort their out-of-sync upgrade without aborting our own since
  // the error receipt sequence is lower than ours and higher than the counterparty.
  if counterpartyUpgradeSequence < expectedUpgradeSequence {
    errorReceipt = ErrorReceipt{
      expectedUpgradeSequence - 1,
      "sequence out of sync", // constant string changeable by implementation
    }
    provableStore.set(channelUpgradeErrorPath(portIdentifier, channelIdentifier), errorReceipt)
    return
  }
  
  // create upgrade fields for this chain from counterparty upgrade and 
  // relayer-provided information version may be mutated by application callback
  upgradeFields = Upgrade{
    ordering: counterpartyUpgrade.fields.ordering,
    connectionHops: proposedConnectionHops,
    version: counterpartyUpgrade.fields.version,
  }

  // current upgrade either doesn't exist (non-crossing hello case),
  // we initialize the upgrade with constructed upgradeFields
  // if it does exist, we are in crossing hellos and must assert
  // that the upgrade fields are the same for crossing-hellos case
  if (existingUpgrade == null) {
    initUpgradeHandshake(portIdentifier, channelIdentifier, upgradeFields)
  } else {
    // we must use the existing upgrade fields
    upgradeFields = existingUpgrade.fields
  }

  abortTransactionUnless(isCompatibleUpgradeFields(upgradeFields, counterpartyUpgradeFields))

  // if the counterparty sequence is greater than the current sequence,
  // we fast forward to the counterparty sequence so that both channel 
  // ends are using the same sequence for the current upgrade.
  // initUpgradeHandshake will increment the sequence so after that call
  // both sides will have the same upgradeSequence
  if (counterpartyUpgradeSequence > channel.upgradeSequence) {
    channel.upgradeSequence = counterpartyUpgradeSequence
  }
  provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)

  // get counterpartyHops for given connection
  connection = provableStore.get(connectionPath(channel.connectionHops[0]))
  counterpartyHops = [connection.counterpartyConnectionIdentifier]

  // call startFlushUpgradeHandshake to move channel to FLUSHING, which will block
  // upgrade from progressing to OPEN until flush completes on both ends
  startFlushUpgradeHandshake(portIdentifier, channelIdentifier)

  // refresh channel to get latest state
  channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))

  // call modules onChanUpgradeTry callback
  // onChanUpgradeTry may return a new proposed version
  // if an error is returned the upgrade is not written
  // the callback MUST NOT write state, as all state transitions will occur once
  // the channel upgrade is complete.
  module = lookupModule(portIdentifier)
  version, err = module.onChanUpgradeTry(
    portIdentifier,
    channelIdentifier,
    channel.upgradeSequence,
    upgradeFields.ordering,
    upgradeFields.connectionHops,
    upgradeFields.version
  )
  // abort the transaction if the callback returns an error and
  // there was no existing upgrade. This will allow the counterparty upgrade
  // to continue existing while this chain may add support for it in the future
  abortTransactionUnless(err === null)

  // replace channel version with the version returned by application
  // in case it was modified
  upgrade = provableStore.get(channelUpgradePath(portIdentifier, channelIdentifier))
  upgrade.fields.version = version
  provableStore.set(channelUpgradePath(portIdentifier, channelIdentifier), upgrade)
}

function chanUpgradeAck(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  counterpartyUpgrade: Upgrade,
  proofChannel: CommitmentProof,
  proofUpgrade: CommitmentProof,
  proofHeight: Height
) {
  // current channel is OPEN or FLUSHING (crossing hellos)
  channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
  abortTransactionUnless(channel.state == OPEN || channel.state == FLUSHING)

  connection = provableStore.get(connectionPath(channel.connectionHops[0]))
  counterpartyHops = [connection.counterpartyConnectionIdentifier]

  // construct counterpartyChannel from existing information
  counterpartyChannel = ChannelEnd{
    state: FLUSHING,
    ordering: channel.ordering,
    counterpartyPortIdentifier: portIdentifier,
    counterpartyChannelIdentifier: channelIdentifier,
    connectionHops: counterpartyHops,
    version: channel.version,
    sequence: channel.upgradeSequence,
  }

  // verify proofs of counterparty state
  abortTransactionUnless(
    verifyChannelState(
      connection,
      proofHeight,
      proofChannel,
      channel.counterpartyPortIdentifier,
      channel.counterpartyChannelIdentifier,
      counterpartyChannel
    )
  )
  abortTransactionUnless(
    verifyChannelUpgrade(
      connection,
      proofHeight,
      proofUpgrade,
      channel.counterpartyPortIdentifier,
      channel.counterpartyChannelIdentifier,
      counterpartyUpgrade
    )
  )

  existingUpgrade = provableStore.get(channelUpgradePath(portIdentifier, channelIdentifier))

  // optimistically accept version that TRY chain proposes and pass this to callback for confirmation.
  // in the crossing hello case, we do not modify version that our TRY call returned and instead 
  // enforce that both TRY calls returned the same version
  if (channel.state == OPEN) {
    existingUpgrade.fields.version == counterpartyUpgrade.fields.version
  }
  // if upgrades are not compatible by ACK step, then we restore the channel
  if (!isCompatibleUpgradeFields(existingUpgrade.fields, counterpartyUpgrade.fields)) {
    restoreChannel(portIdentifier, channelIdentifier)
    return
  }

  if (channel.state == OPEN) {
    // prove counterparty and move our own state to flushing
    // if we are already at flushing, then no state changes occur
    // upgrade is blocked on this channelEnd from progressing until flush completes on its end
    startFlushUpgradeHandshake(portIdentifier, channelIdentifier)
    // startFlushUpgradeHandshake sets the timeout for the upgrade
    // so retrieve upgrade again here and use that timeout value
    upgrade = provableStore.get(channelUpgradePath(portIdentifier, channelIdentifier))
    existingUpgrade.timeout = upgrade.timeout
  }

  timeout = counterpartyUpgrade.timeout
  
  // counterparty-specified timeout must not have exceeded
  // if it has, then restore the channel and abort upgrade handshake
  if ((timeout.timeoutHeight != 0 && currentHeight() >= timeout.timeoutHeight) ||
      (timeout.timeoutTimestamp != 0 && currentTimestamp() >= timeout.timeoutTimestamp )) {
        restoreChannel(portIdentifier, channelIdentifier)
        return
  }

  // if there are no in-flight packets on our end, we can automatically go to FLUSHCOMPLETE
  if (pendingInflightPackets(portIdentifier, channelIdentifier) == null) {
    channel.state = FLUSHCOMPLETE
  }
  // set counterparty upgrade
  privateStore.set(counterpartyUpgradePath(portIdentifier, channelIdentifier), counterpartyUpgrade)

  provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)

  // call modules onChanUpgradeAck callback
  // module can error on counterparty version
  // ACK should not change state to the new parameters yet
  // as that will happen on the onChanUpgradeOpen callback
  module = lookupModule(portIdentifier)
  err = module.onChanUpgradeAck(
    portIdentifier,
    channelIdentifier,
    counterpartyUpgrade.fields.version
  )
  // restore channel if callback returned error
  if (err != null) {
    restoreChannel(portIdentifier, channelIdentifier)
    return
  }

  // if no error, agree on final version
  provableStore.set(channelUpgradePath(portIdentifier, channelIdentifier), existingUpgrade)
}

function chanUpgradeConfirm(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  counterpartyChannelState: state,
  counterpartyUpgrade: Upgrade,
  proofChannel: CommitmentProof,
  proofUpgrade: CommitmentProof,
  proofHeight: Height,
) {
  // current channel is in FLUSHING
  channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
  abortTransactionUnless(channel.state === FLUSHING)

  // counterparty channel is either FLUSHING or FLUSHCOMPLETE
  abortTransactionUnless(counterpartyChannelState === FLUSHING || counterpartyChannelState === FLUSHCOMPLETE)

  connection = provableStore.get(connectionPath(channel.connectionHops[0]))
  counterpartyHops = [connection.counterpartyConnectionIdentifier]

  counterpartyChannel = ChannelEnd{
    state: counterpartyChannelState,
    ordering: channel.ordering,
    counterpartyPortIdentifier: portIdentifier,
    counterpartyChannelIdentifier: channelIdentifier,
    connectionHops: counterpartyHops,
    version: channel.version,
    sequence: channel.upgradeSequence,
  }

  // verify proofs of counterparty state
  abortTransactionUnless(
    verifyChannelState(
      connection,
      proofHeight,
      proofChannel,
      channel.counterpartyPortIdentifier,
      channel.counterpartyChannelIdentifier,
      counterpartyChannel
    )
  )
  abortTransactionUnless(
    verifyChannelUpgrade(
      connection,
      proofHeight,
      proofUpgrade, 
      channel.counterpartyPortIdentifier,
      channel.counterpartyChannelIdentifier,
      counterpartyUpgrade
    )
  )

  existingUpgrade = provableStore.get(channelUpgradePath(portIdentifier, channelIdentifier))

	// in the crossing-hello case it is possible that both chains execute the
	// INIT, TRY and CONFIRM steps without any of them executing ACK, therefore
	// we also need to check that the upgrades are compatible on this step
  if (!isCompatibleUpgradeFields(existingUpgrade.fields, counterpartyUpgrade.fields)) {
    restoreChannel(portIdentifier, channelIdentifier)
    return
  }

  timeout = counterpartyUpgrade.timeout
  
  // counterparty-specified timeout must not have exceeded
  // if it has, then restore the channel and abort upgrade handshake
  if ((timeout.timeoutHeight != 0 && currentHeight() >= timeout.timeoutHeight) ||
      (timeout.timeoutTimestamp != 0 && currentTimestamp() >= timeout.timeoutTimestamp)) {
        restoreChannel(portIdentifier, channelIdentifier)
        return
  }

  // if there are no in-flight packets on our end, we can automatically go to FLUSHCOMPLETE
  if (pendingInflightPackets(portIdentifier, channelIdentifier) == null) {
    channel.state = FLUSHCOMPLETE
    provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)
  }
  // set counterparty upgrade
  privateStore.set(counterpartyUpgradePath(portIdentifier, channelIdentifier), counterpartyUpgrade)

  // if both chains are already in flushcomplete we can move to OPEN
  if (channel.state == FLUSHCOMPLETE && counterpartyChannelState == FLUSHCOMPLETE) {
    openUpgradeHandshake(portIdentifier, channelIdentifier)
    // make application state changes based on new channel parameters
    module.onChanUpgradeOpen(portIdentifier, channelIdentifier)
  }
}

function chanUpgradeOpen(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  counterpartyChannelState: ChannelState,
  counterpartyUpgradeSequence: uint64,
  proofChannel: CommitmentProof,
  proofHeight: Height,
) {
  // channel must have completed flushing
  channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
  abortTransactionUnless(channel.state === FLUSHCOMPLETE)

  // get connection for proof verification
  connection = provableStore.get(connectionPath(channel.connectionHops[0]))

  // counterparty must be in OPEN or FLUSHCOMPLETE state
  if (counterpartyChannelState == OPEN) {
    // get upgrade since counterparty should have upgraded to these parameters
    upgrade = provableStore.get(channelUpgradePath(portIdentifier, channelIdentifier))

    // get the counterparty's connection hops for the proposed upgrade connection
    proposedConnection = provableStore.get(connectionPath(upgrade.fields.connectionHops))
    counterpartyHops = [proposedConnection.counterpartyConnectionIdentifier]

    // The counterparty upgrade sequence must be greater than or equal to
    // the channel upgrade sequence. It should normally be equivalent, but
    // in the unlikely case that a new upgrade is initiated after it reopens,
    // then the upgrade sequence will be greater than our upgrade sequence.
    abortTransactionUnless(counterpartyUpgradeSequence >= channel.upgradeSequence)

    counterpartyChannel = ChannelEnd{
      state: OPEN,
      ordering: upgrade.fields.ordering,
      counterpartyPortIdentifier: portIdentifier,
      counterpartyChannelIdentifier: channelIdentifier,
      connectionHops: counterpartyHops,
      version: upgrade.fields.version,
      sequence: counterpartyUpgradeSequence,
    }
  } else if (counterpartyChannelState == FLUSHCOMPLETE) {
    counterpartyHops = [connection.counterpartyConnectionIdentifier]
    counterpartyChannel = ChannelEnd{
      state: FLUSHCOMPLETE,
      ordering: channel.ordering,
      counterpartyPortIdentifier: portIdentifier,
      counterpartyChannelIdentifier: channelIdentifier,
      connectionHops: counterpartyHops,
      version: channel.version,
      sequence: channel.upgradeSequence,
    }
  } else {
    abortTransactionUnless(false)
  }

  abortTransactionUnless(
    verifyChannelState(
      connection, 
      proofHeight, 
      proofChannel, 
      channel.counterpartyPortIdentifier, 
      channel.counterpartyChannelIdentifier, 
      counterpartyChannel
    )
  )

  // move channel to OPEN and adopt upgrade parameters
  openUpgradeHandshake(portIdentifier, channelIdentifier)

  // call modules onChanUpgradeOpen callback
  module = lookupModule(portIdentifier)
  // open callback must not return error since counterparty successfully upgraded
  // make application state changes based on new channel parameters
  module.onChanUpgradeOpen(
    portIdentifier,
    channelIdentifier
  )
}

function cancelChannelUpgrade(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  errorReceipt: ErrorReceipt,
  proofUpgradeError: CommitmentProof,
  proofHeight: Height,
  msgSender: string,
) {
  // current channel has an upgrade stored
  upgrade = provableStore.get(channelUpgradePath(portIdentifier, channelIdentifier))
  abortTransactionUnless(upgrade !== null)

  channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
  // if the msgSender is authorized to make and cancel upgrades AND 
  // the current channel has not already reached FLUSHCOMPLETE,
  // then we can restore immediately without any additional checks
  // otherwise, we can only cancel if the counterparty wrote an
  // error receipt during the upgrade handshake
  if (!(isAuthorizedUpgrader(msgSender) && channel.state != FLUSHCOMPLETE)) {
    abortTransactionUnless(!isEmpty(errorReceipt))

    if channel.state == FLUSHCOMPLETE {
      // if the channel state is in FLUSHCOMPLETE, it can **only** be aborted if there
      // is an error receipt with the exact same sequence. This ensures that the counterparty
      // did not successfully upgrade and then cancel at a new upgrade to abort our own end,
      // leading to both channel ends being OPEN with different parameters
      abortTransactionUnless(errorReceipt.sequence == channel.upgradeSequence)
    } else {
      // If counterparty sequence is less than the current sequence,
      // abort transaction since this error receipt is from a previous upgrade
      abortTransactionUnless(errorReceipt.sequence >= channel.upgradeSequence)
    }
    // fastforward channel sequence to higher sequence so that we can start
    // new handshake on a fresh sequence
    channel.upgradeSequence = errorReceipt.sequence
    provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)

    // get underlying connection for proof verification
    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    // verify that the provided error receipt is written to the upgradeError path with the counterparty sequence
    abortTransactionUnless(
      verifyChannelUpgradeError(
        connection,
        proofHeight,
        proofUpgradeError,
        channel.counterpartyPortIdentifier,
        channel.counterpartyChannelIdentifier,
        errorReceipt
      )
    )
  }

  // cancel upgrade and write error receipt
  restoreChannel(portIdentifier, channelIdentifier)
}

function timeoutChannelUpgrade(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  counterpartyChannel: ChannelEnd,
  proofChannel: CommitmentProof,
  proofHeight: Height,
) {
  // current channel must have an upgrade that is FLUSHING or FLUSHCOMPLETE
  upgrade = provableStore.get(channelUpgradePath(portIdentifier, channelIdentifier))
  abortTransactionUnless(upgrade !== null)
  channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
  abortTransactionUnless(channel.state === FLUSHING || channel.state === FLUSHCOMPLETE)

  upgradeTimeout = upgrade.timeout

  // proof must be from a height after timeout has elapsed. 
  // Either timeoutHeight or timeoutTimestamp must be defined.
  // if timeoutHeight is defined and proof is from before 
  // timeout height then abort transaction
  abortTransactionUnless(
    upgradeTimeout.timeoutHeight.IsZero() || 
    proofHeight >= upgradeTimeout.timeoutHeight
  )
  // if timeoutTimestamp is defined then the consensus time 
  // from proof height must be greater than timeout timestamp
  connection = provableStore.get(connectionPath(channel.connectionHops[0]))
  abortTransactionUnless(
    upgradeTimeout.timeoutTimestamp.IsZero() || 
    getTimestampAtHeight(connection, proofHeight) >= upgradeTimeout.timestamp
  )

  // counterparty channel must be proved to not have completed flushing after timeout has passed
  abortTransactionUnless(counterpartyChannel.state !== FLUSHCOMPLETE)
  // if counterparty channel state is OPEN, we should abort the tx
  // only if the counterparty has successfully completed upgrade
  if (counterpartyChannel.state == OPEN) {
    // get upgrade since counterparty should have upgraded to these parameters
    upgrade = provableStore.get(channelUpgradePath(portIdentifier, channelIdentifier))

    // get counterparty hops of the proposed connection
    proposedConnection = provableStore.get(connectionPath(upgrade.fields.connectionHops))
    counterpartyHops = [proposedConnection.counterpartyConnectionIdentifier]

    // check that the channel did not upgrade successfully
    if ((upgrade.fields.version == counterpartyChannel.version) &&
        (upgrade.fields.order == counterpartyChannel.order) &&
        (counterpartyHops == counterpartyChannel.connectionHops)) {
          // counterparty has already successfully upgraded so we cannot timeout
          abortTransactionUnless(false)
    }
  }
  abortTransactionUnless(counterpartyChannel.upgradeSequence >= channel.upgradeSequence)
  abortTransactionUnless(
    verifyChannelState(
      connection,
      proofHeight,
      proofChannel,
      channel.counterpartyPortIdentifier,
      channel.counterpartyChannelIdentifier,
      counterpartyChannel
    )
  )

  // we must restore the channel since the timeout verification has passed
  // error receipt is written for this sequence, counterparty can call cancelUpgradeHandshake
  restoreChannel(portIdentifier, channelIdentifier)
}