Architecture of Marlowe Discovery

[bwbush]

The "Marlowe Discovery" component of Marlowe Runtime provides services for the discovery of Marlowe contracts on the blockchain and the interrogation of metadata (version, certification, etc.) about the contract.

Marlowe contracts are uniquely identified by the TxOutRef of their creation transaction. Metadata asserts the version of Marlowe Core used for the contract; such assertions are cryptographically verified.

The discovery mechanism in Language.Marlowe.Client currently relies upon computing the Marlowe validator script address from a native token and seeing if that address has any transactions.

[jhbertra]

Here is a first approximation of how the discovery component could work.

Similar to the History module, the Discovery module exposes an API that speaks a synchronization protocol called MarloweHeaderSync. This protocol is similar to MarloweSync in its structure but communicates a different event type and operates in the global context instead of the context of a single contract.

Below is a state transition diagram of the protocol.

stateDiagram-v2
  [*] --> Idle
  Idle --> Intersect : MsgIntersect
  Intersect --> Idle : MsgIntersectFound
  Intersect --> Idle : MsgIntersectNotFound
  Idle --> [*] : MsgDone
  Idle --> Next : MsgRequestNext
  Next --> Wait : MsgWait
  Wait --> Next : MsgPoll
  Wait --> Idle : MsgCancel
  Next --> Idle : MsgRollForward
  Next --> Idle : MsgRollBackward

Loading

The message payloads would all be very similar to MarloweSync (i.e. MsgRollForward and MsgRollBackward would carry block headers, MsgIntersect would accept a list of chain points, etc.). In this protocol, MsgRollForward would carry a [DiscoveryEvent], where

data DiscoveryEvent
  = RoleTokensTransfered TxOutRef Tokens Address
  | V1ContractPublished V1ContractHeader

data V1ContractHeader = V1ContractHeaderV1
  { contractId :: ContractId
  , rolesCurrency :: PolicyId
  , initialRoleTokenDistribution :: Map TokenName Address
  , metadata :: Map Int Aeson.Value
  , marloweScriptHash :: ScriptHash
  , marloweScriptAddress :: Address
  , payoutScriptHash :: ScriptHash
  }

This functionality should provide enough information to implement a variety of Marlowe contract watchers, for example, something like the WalletCompanion from Marlowe Run could easily be implemented using this protocol.

[bwbush]

initialRoleTokenDistribution :: Map TokenName Address

If role tokens were distribute separately from the Marlowe creation transaction, would this be empty, or would the chain be queried to discover where the tokens reside?

Technically, we might need a multi-map because two addresses could hold the same role token if the tokens are minted in duplicate. FYI, I think this is a real use case for institutions or individuals that want backups (in cold storage) of their role tokens.

[bwbush]

marloweScriptHash :: ScriptHash

Redundant with marloweScriptAddress :: Address

[jhbertra]

It's not redundant - there isn't a total function for extracting a script hash from an address, there is only a partial one:

getScriptHash :: Address -> Maybe ScriptHash
getScriptHash = paymentCredential >=> \case
  ScriptCredential hash -> Just hash
  _ -> Nothing

[bwbush]

data DiscoveryEvent
  = RoleTokensTransfered TxOutRef Tokens Address
  | V1ContractPublished V1ContractHeader

Do we need RoleTokenBurned or RoleTokenMinted? Sorry, but I cannot help thinking of use cases with non-standard monetary policies, but burning a role token is a real use case for mainnet.

Regarding burning role tokens, many users will not want to have permanent role tokens created for a Marlowe contract with temporary duration. (Personally, I will never use a role-based Marlowe contract on mainnet unless the monetary policy allows me to burn my role token after the contract is completed.)

[jhbertra]

Let's have a chat about this, it relates to the questions in the CLI PR as well around minting and the different use cases we want to support.

[jhbertra]

Summarizing the outcome of our sidechain discussion:

We are going to remove the role token distribution tracking from this component. The discovery component will now only offer:

A) A synchronization API for subscribing to a stream of contract headers.
B) A query API for fetching all contract headers.
C) A query API for fetching a list of contract headers by their role token policy ID.

The rationale for this is that the contract headers already include the policy ID, and a client can check to see if they have a matching role token in their wallet. Conversely, when a client receives a new token in their wallet, they can query the discovery service to see if there is a Marlowe contract that could use it as a role token.

[jhbertra]

Here is a typed-protocols definition for the synchronization protocol:

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE GADTs #-}
{-# LANGUAGE TypeFamilies #-}

module Language.Marlowe.Protocol.HeaderSync.Types
  where

import Data.Map (Map)
import Data.Word (Word64)
import Language.Marlowe.Runtime.ChainSync.Api (Address, BlockHeader, Metadata, PolicyId, ScriptHash)
import Language.Marlowe.Runtime.Core.Api (ContractId, IsMarloweVersion(..), MarloweVersion, MarloweVersionTag)
import Network.TypedProtocol (Protocol(..))

data ContractHeader = forall (v :: MarloweVersionTag). ContractHeader
  { contractId :: ContractId
  , rolesCurrency :: PolicyId
  , metadata :: Map Word64 Metadata
  , marloweScriptHash :: ScriptHash
  , marloweScriptAddress :: Address
  , payoutScriptHash :: ScriptHash
  , payoutScriptAddress :: Address
  , marloweVersion :: MarloweVersion v
  , datum :: Datum v
  }

data MarloweHeaderSync where
  StIdle :: MarloweHeaderSync
  StIntersect :: MarloweHeaderSync
  StNext :: MarloweHeaderSync
  StWait :: MarloweHeaderSync
  StDone :: MarloweHeaderSync

instance Protocol MarloweHeaderSync where
  data Message MarloweHeaderSync from to where
    MsgIntersect :: [BlockHeader] -> Message MarloweHeaderSync
      'StIdle
      'StIntersect
    MsgDone :: Message MarloweHeaderSync
      'StIdle
      'StDone
    MsgRequestNext :: Message MarloweHeaderSync
      'StIdle
      'StNext
    MsgNewHeaders :: BlockHeader -> [ContractHeader] -> Message MarloweHeaderSync
      'StNext
      'StIdle
    MsgRollBackward :: BlockHeader -> Message MarloweHeaderSync
      'StNext
      'StIdle
    MsgWait :: Message MarloweHeaderSync
      'StNext
      'StWait
    MsgPoll :: Message MarloweHeaderSync
      'StWait
      'StNext
    MsgCancel :: Message MarloweHeaderSync
      'StWait
      'StIdle
    MsgIntersectFound :: BlockHeader -> Message MarloweHeaderSync
      'StIntersect
      'StIdle
    MsgIntersectNotFound :: Message MarloweHeaderSync
      'StIntersect
      'StIdle

  data ClientHasAgency st where
    TokIdle :: ClientHasAgency 'StIdle
    TokWait :: ClientHasAgency 'StWait

  data ServerHasAgency st where
    TokNext :: ServerHasAgency 'StNext
    TokIntersect :: ServerHasAgency 'StIntersect

  data NobodyHasAgency st where
    TokDone :: NobodyHasAgency 'StDone

  exclusionLemma_ClientAndServerHaveAgency TokIdle = \case
  exclusionLemma_ClientAndServerHaveAgency TokWait = \case

  exclusionLemma_NobodyAndClientHaveAgency TokDone = \case

  exclusionLemma_NobodyAndServerHaveAgency TokDone = \case

[jhbertra]

For the initial version, going to remove the datum from the header. We can add this in if there is a clear need for it that emerges naturally.