Marlowe Tx metadata

[paluh]

I propose to register Marlowe metadata label as (1564 - Ch. Marlowe date of birth):

{
    "transaction_metadatum_label": 1564,
    "description": "Marlowe - a DSL for writing and executing financial contracts"
}

Our internal and minimal schema for Tx metadata for Marlowe could be:

{
  "1564": {
     <version>: <int>
     <other properties>
  }
}

For example:

{
  "1564": {
     "version": 1,
     "title": "Escrow"
  }
}

The version tag indicates the metadata schema version.

Validator version is not included in the metadata - we just assume constant validator so its version is directly accessible from the transaction output.

Marlowe version is not included in the metadata - it is determined by the validator version.

In other words the main purpose of this metadata schema is to just tag Marlowe related transactions on chain so they can be processed further.

[bwbush]

@paluh, shouldn't "transaction_metadatum_label": 87 be "transaction_metadatum_label": 1564?

[paluh]

Fixed ;-)

[paluh]

I reserved an id for us in the registry: https://github.com/cardano-foundation/CIPs/blob/0ea15fc09d3c664ecf1826505eb21f544f2d3c5a/CIP-0010/registry.json#L35

[bwbush]

@paluh, could we make this more precise by adding type information to the specification, and an example?

{
  "1564": {
     "language_version": 3
     <other properties>
  }
}

Also, the version of the validator may differ from the version of the DSL itself. Right now the DSL is on version 3, but the validator might start with version 1. Not sure.

[paluh]

I included the example and added a comment about validator version. Thanks!

[palas]

We could say "marlowe_version" to be more specific. I think that we may need other language versions, like "extended_marlowe_version" or even "generator_language" and then "generator_language_version" in the future

[hrajchert]

As we were talking with @jhbertra before, is it still necessary to add just the validator version to the metadata or is that something that we could infer from the transaction?

Relevant to the metadata of the contract, in PR 192 I've added a top-level construct which has the Marlowe Extended version and also the contract metadata as defined in Extended (template parameters, name, description, etc).

I think in the Tx metadata we should add the following fields:

{
  "1564": {
     <tx-metadata-version>: <int>
     <contract-url>: <optional string>
     <contract-hash>: <string>
  }
}

Where the properties are:

• tx-metadata-version: A integer that represents the version of this schema, so we can update it in the future.
• contract-url: A URL that points to new top-level construct (Marlowe module). The serialized module information includes the Marlowe Extended Version (which implies the Marlowe Core Version) and also the contract metadata (name, type and template parameters). The URL should finish with either .json or .cbor, that implies the serialization type.
• contract-hash: An MD5Sum (or other hash algorithm) of the serialized Marlowe module provided by contract-url. This way if the URL is not available anymore (or was never provided) but you have a local copy somehow, you can still validate that it is the intended contract.

Other information that is useful to have is the template parameter values that were used to instantiate this contract, basically this ContractParams data type without the nickname.

But I think we should have a function like

getContractParams :: Extended.Contract -> Core.Contract -> Maybe ContractParams

to infer the parameters.

[OlofBlomqvist]

Could we also add the hash of the initial contract-creation tx in here (To make it easy to query for all txs related to a marlowe contract instance)? Making marlowe contracts and its transitional states visible in blockchain explorers etc. using this metadata would be pretty sweet!

.. unless there already exists an easy and well defined way for a 3rd party to find such txs :)

[hrajchert]

I wonder if chainseekd, marlowe-history and marlowe-discovery covers what you are looking for.

Docs here

[OlofBlomqvist]

Technically yes, altough it seems a bit overkill to have to deploy those for something that could be greatly simplified by having the tx's containing a ref hash.

In my case, I already can query for related txs (and parse the datums) without the mentioned services; I just feel that it is more complex to do so than it should have to be.

Edit: To be clear, I have very limited domain knowledge here so if you say it does not belong in the meta-data I believe you :)

[bwbush]

I like the idea of including hints like the contract-creation TxOutRef. These take very little space in the transaction, simplify queries, and take some of the load off of the backend (making it more scalable). For security, users would have to verify metadata like this by querying the ledger, but the hints would simplify the process.

This also opens use cases where Marlowe is run completely in the browser, without backend services like chainseekd.