Marlowe extended contract metadata definition

[hrajchert]

While developing the PlayGround and Marlowe Run, we found the necessity of annotating the Contract with some Metadata that improved the UI.

More so, we made a built-in editor in the playground to ease the editing.

The metadata was constructed organically with the two projects, which adds a benefit and a drawback:

• 👍🏻 Most information is basic enough for a general contract runner/simulator.
• 👎🏻 The format and naming are very UI-focused.

Goals of this discussion

1. Metadata is an overloaded term, we should probably rename this structure

Some suggestions might revolve around: TemplateParameters, TemplateInformation, ContractParameters, ContractInformation, ContractPreface, ContractPreamble, ContractRecitals or similar.

Improving the name would help us focus the scope of what information should be here or somewhere else.

2. Current metadata is very UI-focused.

The current fields were added with a clear UI element that display them in mind. I'd like to shift focus to the contracts domain, to something that is general available in all contracts. While looking for a more domain specific name (instead of metadata) I found the following definition of a contract preamble, which resonates a lot with most of the current metadata fields.

The preamble of a contract is the introductory paragraph that identifies the parties to the agreement. It is typically followed by paragraphs known as recitals (also called the background section). Sometimes, these recital paragraphs are labeled “Whereas”. Taken together, the preamble and the recitals tell the who, what, when, and why of the transaction. In other words, they should tell the reader who the parties to the agreement are, the date of the agreement, and what the parties hope to accomplish by entering into the agreement.

Whatever information we end up having, I think we should make every field optional.

3. We need a way of sharing this metadata with other participants

While developing Marlowe Run we noticed that we needed a way to share the information with other contract participants so that they could also see the same UI. We ended up using a hack called Deinstantiate, in which we checked if the Core contract was an instance of a known Extended contract we knew the metadata for. Inside the Create transaction discussion we are adding the possibility to attach any custom metadata to a contract, but if we can solve the second point I think there is value to include this information as part of the 1564 metadata

Summary of current fields

Contract type

The ContractType is the most controversial field.

data ContractType
  = Escrow
  | EscrowWithCollateral
  | ZeroCouponBond
  | CouponBondGuaranteed
  | Swap
  | ContractForDifferences
  | Other

type MetaData =
  { -- ...
      contractType :: ContractType
   -- ...
   }

It was populated after the initial set of examples, and we have one type per example. At the very least Other should have an optional string, but I suggest removing this field altogether.

Contract name

A string representing the human readable name. I think it should stay as it is.

type MetaData =
  { -- ...
      contractName :: String
   -- ...
   }

Description

We have separate string for short and long description, I think they are fine as it is. We might want to put a limit on the short description and make both optional.

type MetaData =
  { -- ...
      contractShortDescription :: String
    , contractLongDescription :: String
   -- ...
   }

Role descriptions

This is a map between a TokenName and a string description.

type MetaData =
  { -- ...
   roleDescriptions :: Map TokenName String
   -- ...
   }

We might want to add a type alias for that string and maybe some size limit.

Time description

If we use a TimeParam it can be useful to have a description of what this Timeout means. It is an ordered map instead of a simple map to denotate the order in which they should appear in the UI. It is also useful in the playground to have the order as we can put sensible defaults for the timeouts in the simulation.

type MetaData =
  { -- ...
   timeParameterDescriptions :: OMap String String
   -- ... 
   }

Both the key and the value should be replaced by aliases

Parameter description

If the contract uses a ConstantParam for a Value, then it's useful to have a description of what the value means and how it should be formatted

data NumberFormat
  = DefaultFormat
  | DecimalFormat Int String
  | TimeFormat

type ValueParameterInfo =
  { valueParameterFormat :: NumberFormat
  , valueParameterDescription :: String
  }

type MetaData =
  { -- ...
   valueParameterInfo :: OMap String ValueParameterInfo
   -- ... 
   }

I'm not sure if the TimeFormat should be a part of NumberFormat, I think it is not currently being used and the Timeout already has its own metadata field. The number format is useful in the UI as it has a way to represent the amount of cents and token symbol.

This is clearly a UI specific field, but I wonder if we can translate it to a Contract domain, something that colloquially would read as follow

* Whereas ADA is the currency of Cardano and it has a 1.000.000 (6 digits) cents and it is denoted with the symbol ₳.
* Whereas "Loan Value" is the amount of be loaned from the Borrower to the Lender and it is expressed in ADA

Could be represented as:

newtype NumberFormat = NumberFormat 
  { description :: String 
  , cents :: Int 
  , symbol :: Char
  }

adaFormat :: NumberFormat
adaFormat = NumberFormat { description: "...", cents: 6, symbol: '₳' }


type MetaData =
  { -- ...
   valueParameterInfo :: OMap ValueParamId ValueParameterInfo
   -- ... 
   }

Choice information

Whenever a choice is presented we can describe what are we choosing.

data ChoiceInfo = ChoiceInfo
  { choiceFormat :: NumberFormat
  , choiceDescription :: String
  }

type MetaData =
  { -- ...
   choiceInfo :: Map S.ChoiceName ChoiceInfo
   -- ... 
   }