Skip to main content

MarloweSync sub-protocol

The MarloweSync sub-protocol is defined here:

Below is a state diagram for the MarloweSync sub-protocol:

The MarloweSync sub-protocol is used to synchronize the history of a specific Marlowe contract. The client receives a stream of blocks, the first of which contains a "create step", with subsequent blocks containing one or more "contract step(s)". A create step is information related to the contract creation transaction. A contract step is either an "apply inputs" step with an apply inputs transaction that advances the contract, or a "withdraw" step where funds paid by the contract are withdrawn from the payout validator.

Sub-protocol states

Protocol stateAgencyParameterDescription
1. InitClientThe initial state.
2. FollowServerThe server is processing a request to follow a contract.
3. DoneNobodyThe terminal state.
4. Idle vClientA contract is being followed, the server is waiting for the client to send a message.
vThe version of the Marlowe contract
5. Next vServerThe server is looking up the next block that contain contract steps.
vThe version of the Marlowe contract
6. Wait vClientThe client has reached the last block with steps for the current contract and is waiting for a new block to arrive.
vThe version of the Marlowe contract
7. Intersect vServerThe server is processing an intersect request for a contract.
vThe version of the Marlowe contract


MessageBegin stateEnd stateParameterDescription
1. FollowContract idInitFollowFollow a contract by ID.
idThe ID of the contract to follow (ie, the tx-in that created the contract)
2. ContractNotFoundFollowDoneThe requested contract could not be found.
3. ContractFound blk v createFollowIdle vThe requested contract was found.
blkThe block header of the block that contains the creation transaction.
vThe version of contract.
createThe create step for the contract.
4. DoneIdle vDoneEnds the session.
5. RequestNextIdle vNext vRequest the next block of contract steps.
6. RollForward blk stepsNext vIdle vThe server sends the next block of steps.
blkThe block header of the block that contains the new steps.
stepsThe (non-empty) list of steps in this block, in order.
7. RollBackward blkNext vIdle vThe server is rolling the client back to a previous block.
blkThe block header of the block that the client is now at.
8. RollBackCreationNext vDoneThe creation transaction was rolled back - the contract no longer exists.
9. WaitNext vWait vThere are no more blocks with steps for this contract. The client can wait for new ones.
10. PollWait vNext vThe client is checking if new blocks are available.
11. CancelWait vIdle vThe client does not wish to wait indefinitely for new blocks to arrive.
12. Intersect id v blksInitIntersect vSend a request to start syncing from a known point in a contract's history.
idThe id of the contract to intersect with.
vThe expected version of the contract.
blksA list of blocks in the contract's history which the client has record of. Must be a contiguous subset of blocks (none skipped) in increasing order.
13. IntersectFound blkIntersect vIdle vThe server found a matching block for this contract and will resume syncing from that point.
blkThe greatest common block the server knows about in the blocks provided by the client.
13. IntersectNotFoundIntersect vDoneThe server could not find an intersection with the client. Either the contract was not found, no points matched, or the version was wrong.