@marlowe.io/marlowe-object

Description

The marlowe-object package is an extension of {@link @marlowe.io/language-core-v1!} that allows for referencing {@link index.Party}, {@link index.Value}, {@link index.Observation}, {@link index.Token}, {@link index.Contract}, and {@link index.Action} types in a bundle. This approach flattens the tree structure a bit and allows reusability.

This package exposes a {@link index | main module} with the extended constructs and two modules to bundle them, {@link bundle-list} and {@link bundle-map}. Both bundle types provide the same information but are useful in different contexts. {@link bundle-list.ContractBundleList} is the type expected by the runtime and is used in the {@link @marlowe.io/runtime-rest-client!index.RestClient#createContractSources} of the {@link @marlowe.io/runtime-rest-client!} package. On the other hand, {@link bundle-map.ContractBundleMap} is more ergonomic for developers as it is order-independent and is used when creating source maps to have O(1) access. You can convert between the different bundle types using {@link index.bundleMapToList} or {@link index.bundleListToMap}.

While you can manually define a contract using {@link bundle-list.ContractBundleList} or {@link bundle-map.ContractBundleMap}, the primary intention of this package is to serve as the output of a higher-level abstraction, potentially even a new language that compiles to Marlowe. The name marlowe-object is inspired by the .o files generated when you compile a .c file, with {@link @marlowe.io/runtime-rest-client!index.RestClient#createContractSources} acting as a linker.

This package also simplifies the creation of large contracts. A Marlowe contract is a Tree structure, and if the tree is big enough it won't fit on the blockchain. To solve that, the Marlowe Core specification has a concept called Merkleization, which represents large contracts as a Merkle tree's. The splitting and hashing of a large contract into a Merkle Tree is done through the runtime calls ({@link @marlowe.io/runtime-rest-client!index.RestClient#createContractSources}), and we use marlowe-object to define the large contract in a more approachable way.

The marlowe-object package also extends the core types with the ability to {@link index.Annotated | annotate contract nodes}. This can simplify UI development by tagging nodes with information that can be used to infere a logical state and also allow source mapping from a higer level language.