PRT Core Contracts
Tournament Factory Functions
Tournament factory contracts are responsible for instantiating and deploying tournaments. They handle the initialization of tournament parameters including initial machine state, data providers, and timing configurations. There are two main factory types: SingleLevelTournamentFactory for simple disputes and MultiLevelTournamentFactory for complex multi-level dispute resolution, which coordinates the creation of Top, Middle, and Bottom tournament instances.
instantiate()
function instantiate(Machine.Hash initialState, IDataProvider provider) external returns (ITournament)
Create a new single-level tournament instance.
Event Emitted: TournamentCreated(ITournament tournament) when tournament is created
Parameters:
| Name | Type | Description |
|---|---|---|
initialState | Machine.Hash | Initial machine state hash |
provider | IDataProvider | Data provider for input validation |
Return Values:
| Index | Type | Description |
|---|---|---|
| [0] | ITournament | Created tournament instance |
instantiateTop() (MultiLevelTournamentFactory)
function instantiateTop(Machine.Hash _initialHash, IDataProvider _provider) external returns (ITournament)
Create a new top-level tournament in the multi-level hierarchy.
Parameters:
| Name | Type | Description |
|---|---|---|
initialHash | Machine.Hash | Initial machine state hash |
provider | IDataProvider | Data provider for input validation |
Returns:
| Index | Type | Description |
|---|---|---|
| [0] | Tournament | Created top tournament instance |
instantiateMiddle()
function instantiateMiddle(Machine.Hash initialHash, Tree.Node contestedCommitmentOne, Machine.Hash contestedFinalStateOne, Tree.Node contestedCommitmentTwo, Machine.Hash contestedFinalStateTwo, Time.Duration allowance, uint256 startCycle, uint64 level, IDataProvider provider) external returns (ITournament)
Create a new middle-level tournament for dispute resolution.
Parameters:
| Name | Type | Description |
|---|---|---|
initialHash | Machine.Hash | Initial machine state hash |
contestedCommitmentOne | Tree.Node | First contested commitment |
contestedFinalStateOne | Machine.Hash | First contested final state |
contestedCommitmentTwo | Tree.Node | Second contested commitment |
contestedFinalStateTwo | Machine.Hash | Second contested final state |
allowance | Time.Duration | Time allowance for participants |
startCycle | uint256 | Starting cycle for the tournament |
level | uint64 | Tournament level in hierarchy |
provider | IDataProvider | Data provider for input validation |
Returns:
| Index | Type | Description |
|---|---|---|
| [0] | ITournament | Created middle tournament instance |
instantiateBottom()
function instantiateBottom(Machine.Hash initialHash, Tree.Node contestedCommitmentOne, Machine.Hash contestedFinalStateOne, Tree.Node contestedCommitmentTwo, Machine.Hash contestedFinalStateTwo, Time.Duration allowance, uint256 startCycle, uint64 level, IDataProvider provider) external returns (ITournament)
Create a new bottom-level tournament for leaf dispute resolution.
Parameters:
| Name | Type | Description |
|---|---|---|
initialHash | Machine.Hash | Initial machine state hash |
contestedCommitmentOne | Tree.Node | First contested commitment |
contestedFinalStateOne | Machine.Hash | First contested final state |
contestedCommitmentTwo | Tree.Node | Second contested commitment |
contestedFinalStateTwo | Machine.Hash | Second contested final state |
allowance | Time.Duration | Time allowance for participants |
startCycle | uint256 | Starting cycle for the tournament |
level | uint64 | Tournament level in hierarchy |
provider | IDataProvider | Data provider for input validation |
Returns:
| Index | Type | Description |
|---|---|---|
| [0] | ITournament | Created bottom tournament instance |
Tournament Core Functions
Core tournament contracts implement the asynchronous PRT-style dispute resolution mechanism. The abstract Tournament contract provides the foundational skeleton that resolves disputes among N parties in O(log N) depth under chess-clock timing, with asynchronous pairing where claims are matched as they arrive without requiring a prebuilt bracket. Concrete implementations include SingleLevelTournament for single-level disputes, TopTournament for the root of multi-level instances, MiddleTournament for intermediate levels, and BottomTournament for the leaf level that performs actual state transitions.
joinTournament()
function joinTournament(Machine.Hash finalState, bytes32[] calldata proof, Tree.Node leftNode, Tree.Node rightNode) external payable
Join a tournament by submitting a final computation hash with Merkle proof. Creates a match if another participant is waiting.
Parameters:
| Name | Type | Description |
|---|---|---|
finalState | Tree.Node | Final computational hash |
proof | bytes32[] | Merkle proof for the final state |
leftNode | Tree.Node | Left node of the commitment |
rightNode | Tree.Node | Right node of the commitment |
arbitrationResult()
function arbitrationResult() external view returns (bool finished, Tree.Node winnerCommitment, Machine.Hash finalState)
Get the final arbitration result from the root tournament.
Return Values:
| Name | Type | Description |
|---|---|---|
finished | bool | Whether the tournament is finished |
winnerCommitment | Tree.Node | The winning commitment |
finalState | Machine.Hash | Final machine state hash of winner |
advanceMatch()
function advanceMatch(Match.Id calldata matchId, Tree.Node leftNode, Tree.Node rightNode, Tree.Node newLeftNode, Tree.Node newRightNode) external
Advance a match by providing new intermediate nodes in the binary search process.
Parameters:
| Name | Type | Description |
|---|---|---|
matchId | Match.Id | Identifier of the match to advance |
leftNode | Tree.Node | Current left node in the match |
rightNode | Tree.Node | Current right node in the match |
newLeftNode | Tree.Node | New left node for next iteration |
newRightNode | Tree.Node | New right node for next iteration |
winMatchByTimeout()
function winMatchByTimeout(Match.Id calldata matchId, Tree.Node leftNode, Tree.Node rightNode) external
Win a match when the opponent has run out of time allowance.
Parameters:
| Name | Type | Description |
|---|---|---|
matchId | Match.Id | Identifier of the match to win by timeout |
eliminateMatchByTimeout()
function eliminateMatchByTimeout(Match.Id calldata matchId) external
Eliminate a match when both participants have run out of time.
Parameters:
| Name | Type | Description |
|---|---|---|
matchId | Match.Id | Identifier of the match to eliminate |
isFinished()
function isFinished() external view returns (bool)
Check if the tournament has finished (has a winner or is eliminated).
isClosed()
function isClosed() external view returns (bool)
Check if the tournament is closed to new participants.
bondValue()
function bondValue() external view returns (uint256)
Get the amount of Wei necessary to call joinTournament().
Return Values:
| Index | Type | Description |
|---|---|---|
| [0] | uint256 | The tournament bond value |
tryRecoveringBond()
function tryRecoveringBond() external returns (bool)
Try recovering the bond of the winner commitment submitter.
Return Values:
| Index | Type | Description |
|---|---|---|
| [0] | bool | Whether the recovery was successful |
sealInnerMatchAndCreateInnerTournament()
function sealInnerMatchAndCreateInnerTournament(Match.Id calldata matchId, Tree.Node leftLeaf, Tree.Node rightLeaf, Machine.Hash agreeHash, bytes32[] calldata agreeHashProof) external
Seal an inner match and create a new inner tournament to resolve the dispute at a finer granularity.
Event Emitted: NewInnerTournament(Match.IdHash indexed matchIdHash, ITournament indexed childTournament) when inner tournament is created
Parameters:
| Name | Type | Description |
|---|---|---|
matchId | Match.Id | Identifier of the match to seal |
leftLeaf | Tree.Node | Left leaf node of the disagreement |
rightLeaf | Tree.Node | Right leaf node of the disagreement |
agreeHash | Machine.Hash | Agreed upon machine state hash |
agreeHashProof | bytes32[] | Merkle proof for the agreed hash |
winInnerTournament()
function winInnerTournament(ITournament childTournament, Tree.Node leftNode, Tree.Node rightNode) external
Process the result of a finished inner tournament and advance the parent match.
Parameters:
| Name | Type | Description |
|---|---|---|
childTournament | ITournament | The inner/child tournament |
leftNode | Tree.Node | Left child of the winning commitment |
rightNode | Tree.Node | Right child of the winning commitment |
eliminateInnerTournament()
function eliminateInnerTournament(ITournament childTournament) external
Eliminate an inner tournament that has no winner and advance the parent match.
Parameters:
| Name | Type | Description |
|---|---|---|
childTournament | ITournament | The inner/child tournament to eliminate |
innerTournamentWinner()
function innerTournamentWinner() external view returns (bool, Tree.Node, Tree.Node, Clock.State memory)
Get the winner information from a finished inner tournament for parent tournament processing.
Returns:
| Index | Type | Description |
|---|---|---|
| [0] | bool | Whether the tournament is finished |
| [1] | Tree.Node | The contested parent commitment |
| [2] | Tree.Node | The winning inner commitment |
| [3] | Clock.State | Paused clock state of the winning inner commitment |
canBeEliminated()
function canBeEliminated() external view returns (bool)
Check if the tournament can be safely eliminated by its parent.
Returns:
| Index | Type | Description |
|---|---|---|
| [0] | bool | Whether the tournament can be eliminated |
Other View Functions
tournamentArguments()
function tournamentArguments() external view returns (TournamentArguments memory)
Get the tournament arguments.
Return Values:
| Index | Type | Description |
|---|---|---|
| [0] | TournamentArguments | The tournament arguments |
canWinMatchByTimeout()
function canWinMatchByTimeout(Match.Id calldata matchId) external view returns (bool)
Check if a match can be won by timeout.
Parameters:
| Name | Type | Description |
|---|---|---|
matchId | Match.Id | The identifier of the match |
Return Values:
| Index | Type | Description |
|---|---|---|
| [0] | bool | Whether the match can be won by timeout |
getCommitment()
function getCommitment(Tree.Node commitmentRoot) external view returns (Clock.State memory clock, Machine.Hash finalState)
Get the clock and final state of a commitment.
Parameters:
| Name | Type | Description |
|---|---|---|
commitmentRoot | Tree.Node | The root of the commitment |
Return Values:
| Index | Type | Description |
|---|---|---|
| [0] | Clock.State | The clock state of the commitment |
| [1] | Machine.Hash | The final state of the commitment |
getMatch()
function getMatch(Match.IdHash matchIdHash) external view returns (Match.State memory)
Get the match state for a given match identifier.
Parameters:
| Name | Type | Description |
|---|---|---|
matchIdHash | Match.IdHash | The identifier of the match |
Return Values:
| Index | Type | Description |
|---|---|---|
| [0] | Match.State | The state of the match |
getMatchCycle()
function getMatchCycle(Match.IdHash matchIdHash) external view returns (uint256)
Get the running machine cycle of a match by its ID hash.
Parameters:
| Name | Type | Description |
|---|---|---|
matchIdHash | Match.IdHash | The identifier of the match |
Return Values:
| Index | Type | Description |
|---|---|---|
| [0] | uint256 | The cycle of the match |
tournamentLevelConstants()
function tournamentLevelConstants() external view returns (uint64 maxLevel, uint64 level, uint64 log2step, uint64 height)
Get the level constants of a tournament.
Return Values:
| Name | Type | Description |
|---|---|---|
maxLevel | uint64 | The maximum number of levels in the tournament |
level | uint64 | The current level of the tournament |
log2step | uint64 | The log2 number of steps between commitment leaves |
height | uint64 | The height of the commitment tree |
timeFinished()
function timeFinished() external view returns (bool, Time.Instant)
Get the confirmation and time when the tournament finished.
Return Values:
| Index | Type | Description |
|---|---|---|
| [0] | bool | Whether the tournament has finished |
| [1] | Time.Instant | The time when the tournament finished |
Events Emitted
TournamentCreated()
event TournamentCreated(ITournament tournament)
An event emitted when a new tournament is instantiated.
Parameters:
| Name | Type | Description |
|---|---|---|
tournament | ITournament | The tournament with its arguments |
CommitmentJoined()
event CommitmentJoined(Tree.Node commitmentRoot, Machine.Hash finalState, address claimer)
An event emitted when a commitment is successfully added.
Parameters:
| Name | Type | Description |
|---|---|---|
commitmentRoot | Tree.Node | The root of the commitment |
finalState | Machine.Hash | The final computational hash |
claimer | address | The address of the claimer |
PartialBondRefund()
event PartialBondRefund(address indexed recipient, uint256 value, bool indexed success, bytes ret)
An event emitted when a partial bond refund is successful.
Parameters:
| Name | Type | Description |
|---|---|---|
recipient | address | The address of the recipient |
value | uint256 | The amount of the refund |
success | bool | Whether the refund was successful |
ret | bytes | The return data of the refund |
NewInnerTournament()
event NewInnerTournament(Match.IdHash indexed matchIdHash, ITournament indexed childTournament)
An event emitted when a new inner tournament is created.
Parameters:
| Name | Type | Description |
|---|---|---|
matchIdHash | Match.IdHash | Hashed Identifier of the match |
childTournament | ITournament | The inner/child tournament |
MatchCreated()
event MatchCreated(Match.IdHash indexed matchIdHash, Tree.Node indexed one, Tree.Node indexed two, Tree.Node leftOfTwo)
An event emitted when a new match is created.
Parameters:
| Name | Type | Description |
|---|---|---|
matchIdHash | Match.IdHash | Identifier of the match |
one | Tree.Node | One of the participants |
two | Tree.Node | Two of the participants |
leftOfTwo | Tree.Node | Left node of the two |
MatchAdvanced()
event MatchAdvanced(Match.IdHash indexed matchIdHash, Tree.Node otherParent, Tree.Node leftNode)
An event emitted when a match is advanced.
Parameters:
| Name | Type | Description |
|---|---|---|
matchIdHash | Match.IdHash | Hashed Identifier of the match |
otherParent | Tree.Node | The new otherParent value |
leftNode | Tree.Node | The new leftNode value |
MatchDeleted()
event MatchDeleted(Match.IdHash indexed matchIdHash, Tree.Node indexed one, Tree.Node indexed two, MatchDeletionReason reason, WinnerCommitment winnerCommitment)
An event emitted when a match is deleted.
Parameters:
| Name | Type | Description |
|---|---|---|
matchIdHash | Match.IdHash | Hashed Identifier of the match |
one | Tree.Node | Commitment of the 1st participant |
two | Tree.Node | Commitment of the 2nd participant |
reason | MatchDeletionReason | The reason for the deletion |
winnerCommitment | WinnerCommitment | The winner commitment |