Skip to main content
Version: Next

Smart Contract Overview

HoprChannels is the main smart contract of HOPR protocol. It manages the payment channel between HOPR nodes and the announcement of public nodes.

Lifecycle of payment channel

A payment channel runs throug multiple states during its lifecycle, as shown in the figure below.

  1. Initially, each payment channel is Closed.
  2. Node can lock some assets to payment channels, which leads to the status of Wait for commitement.
  3. When the destination channel sets a commitment, the payment channel is considered as Open. If the counterparty has already set commitment, then funding immediately changes the state to Open.
  4. When closing a payment channel, the payment channel first goes into Pending to close. Channels need to wait for a timeout for nodes to redeem tickets and thus retrieve the assets. In rare cases it can happen that the counterparty does not submit an on-chain commit after a node intends to open a payment channel. Under this circumstance, the channel can be turned immediately into Pending to close.
  5. Once the timeout is done, any of the involving nodes can finalize the closure and turn the payment channel state into Closed.

Payment channel states and possible state transitions.

Struct

Channel

struct Channel {
uint256 balance;
bytes32 commitment;
uint256 ticketEpoch;
uint256 ticketIndex;
ChannelStatus status;
uint256 channelEpoch;
uint32 closureTime;
}

Parameters:

NameTypeDescription
balanceuint256Stake of HOPR token in the channel.
commitmentbytes32Commitment of the channel, set by the destination node.
ticketEpochuint256Ticket epoch of the channel.
ticketIndexuint256Ticket index of the channel.
statusenum(ChannelStatus)The Proof-of-Relay secret.
channelEpochuint256Current channel epoch.
closureTimeuint32Block timestamp when the channel can be closed. Note that it overloads at year >2105.

Events

ChannelUpdated

event ChannelUpdated(
address indexed source,
address indexed destination,
Channel newState
);

Emitted on every channel state change.

Parameters:

NameTypeIndexedDescription
sourceaddresstrueEthereum address of the source node of a payment channel.
destinationaddresstrueEthereum address of the destination node of a payment channel.
newStatetuple(Channel)falseLatest state of the payment channel.

Announcement

event Announcement(
address indexed account,
bytes publicKey,
bytes multiaddr
);

Emitted once an account announces.

Parameters:

NameTypeIndexedDescription
accountaddresstrueEthereum address of the public HOPR node.
publicKeybytesfalsePublic key of the announced HOPR node.
multiaddrbytesfalseMultiaddress of the announced HOPR node.

ChannelFunded

event ChannelFunded(
address indexed funder,
address indexed source,
address indexed destination,
uint256 amount
);

Emitted once a channel if funded.

Parameters:

NameTypeIndexedDescription
funderaddresstrueAddress of the account that funds the channel.
sourceaddresstrueAddress of the source node of a payment channel.
destinationaddresstrueAddress of the destination node of a payment channel.
amountuint256falseAmount of HOPR being staked into the channel

ChannelOpened

event ChannelOpened(
address indexed source,
address indexed destination
);

Emitted once a channel is opened.

Parameters:

NameTypeIndexedDescription
sourceaddresstrueAddress of the source node of a payment channel.
destinationaddresstrueAddress of the destination node of a payment channel.

ChannelBumped

event ChannelBumped(
address indexed source,
address indexed destination,
bytes32 newCommitment,
uint256 ticketEpoch,
uint256 channelBalance
);

Emitted once bumpChannel is called and the commitment is changed.

Parameters:

NameTypeIndexedDescription
sourceaddresstrueAddress of the source node of a payment channel.
destinationaddresstrueAddress of the destination node of a payment channel.
newCommitmentbytes32falseNew channel commitment
ticketEpochuint256falseCurrent ticket epoch of the channel.
channelBalanceuint256falseAmount of HOPR being staked into the channel

ChannelClosureInitiated

event ChannelClosureInitiated(
address indexed source,
address indexed destination,
uint32 closureInitiationTime
);

Emitted once a channel closure is initialized.

Parameters:

NameTypeIndexedDescription
sourceaddresstrueAddress of the source node of a payment channel.
destinationaddresstrueAddress of the destination node of a payment channel.
closureInitiationTimeuint32falseBlock timestamp at which the channel closure is initialized.

ChannelClosureFinalized

event ChannelClosureFinalized(
address indexed source,
address indexed destination,
uint32 closureFinalizationTime,
uint256 channelBalance
);

Emitted once a channel closure is finalized.

Parameters:

NameTypeIndexedDescription
sourceaddresstrueAddress of the source node of a payment channel.
destinationaddresstrueAddress of the destination node of a payment channel.
closureFinalizationTimeuint32falseBlock timestamp at which the channel closure is finalized.
channelBalanceuint256falseCurrent stake in the channel.

TicketRedeemed

event TicketRedeemed(
address indexed source,
address indexed destination,
bytes32 nextCommitment,
uint256 ticketEpoch,
uint256 ticketIndex,
bytes32 proofOfRelaySecret,
uint256 amount,
uint256 winProb,
bytes signature
);

Emitted once a ticket is redeemed.

Parameters:

NameTypeIndexedDescription
sourceaddresstrueAddress of the source node of a payment channel.
destinationaddresstrueAddress of the destination node of a payment channel.
nextCommitmentbytes32falseCommitment that hashes to the redeemers previous commitment.
ticketEpochuint256falseCurrent ticket epoch of the channel.
ticketIndexuint256falseCurrent ticket index of the channel.
proofOfRelaySecretbytes32falseThe Proof-of-Relay secret.
amountuint256falseAmount of HOPR token embedded in the ticket.
winProbuint256falseThe probability of which the ticket wins. This value is set by the sender.
signaturebytesfalseSignature associated with the ticket, which is signed by the source node.