Marlowe Runtime v1.0.0

Highlights

This release focuses on upgrades required by Conway. Additionally, we have improved the coverage and stability of our integration framework, and added extra safety analyses and contract execution enhancements. With these changes, we have achieved the main goals of delivering a stable and secure release.

Conway related upgrades

These changes were required by the Conway hard fork but did not introduce any new functionality. It seems that we are nearly ready for the hard fork event.

Contract execution improvements

Accounts initialization

We have added the ability to initialize the accounts during contract creation. Usually this allows you to perform an initial deposit together with the contract creation in a single transaction. This feature is exposed on the REST API level through accounts field in the creation request.

Safety improvements

We added extra safety analytical step which is performed during input application so contracts created either outside of the system or by malicious actors can be detected and rejected.

The REST API changes

Added

• Enhanced Error Information: Introducing detailed error categories, including CoinsSelectionError and MarloweTransactionError, to aid in debugging and development.
• Optional Account Initialization During Contract Creation: Allows for simultaneous deposits during the contract creation process, enhancing flexibility and efficiency.
• Accessible Safety Errors: Safety errors are now detectable during key operations:
  • At contract creation (POST /contracts)
  • When applying inputs (POST /contracts/:contractId/transactions)
• Enhanced Transaction Semantics Information: Additional details are now included in the response from GET /contracts/:contractId/transactions/:transactionId:
  • inputState: The Marlowe state from the transaction's input datum.
  • inputContract: The Marlowe contract from the transaction's input datum.
  • reconstructedSemanticInput: Details the TransactionInput used during transaction validation, providing the correct TimeInterval for input evaluation.
  • reconstructedSemanticsOutput: Offers insights into the transaction outcome processed by the Marlowe semantics validator, including intra-state payments and warning details not available elsewhere in the response.

Changed

• Improved REST API Error Handling: We've transitioned from a generic error encoding to a more structured and explicit error format in our REST API, enhancing clarity and user experience.

marlowe-runtime 1.0.0 - 2024-04-22

Removed

• marlowe-runtime-cli

Added

• Support for initial account balances when creating contracts

• Upgrade to cardano-api 8.37.1.1

• A safety analysis to the apply input step

• Support for compiling/building/running the repository using new Mac CPUs (M1/M2/M3) within a linux VM (aarch64-linux system).

Changed

• history-api has been merged within sync-api

• Updated Marlowe Plutus scripts to use optmized asData for Case.

• Default batch size for chain-indexer decreased to 1/4 to prevent OOM errors.

• Upgrade cardano-api 8.37.1.1 to 8.39.2.0 (Conway Hard Fork Adaptation)

• Upgrade plutus from 1.15 to 1.21 (plutus-core, plutus-ledger-api, plutus-tx) (Conway Hard Fork Adaptation)

• Upgrade cardano-ledger (Conway Hard Fork Adaptation)

  • cardano-ledger-conway from 1.11 to 1.12
  • cardano-ledger-core from 1.9 to 1.10
  • cardano-ledger-mary from 1.4 to 1.5
  • cardano-ledger-shelley from 1.8 to 1.9
  • cardano-ledger-binary from 1.2 to 1.3

• Upgrade ouroboros-network (Conway Hard Fork Adaptation)

  • ouroboros-network-api from 0.6.0 to 0.7.0
  • ouroboros-consensus from 0.14 to 0.16
  • ouroboros-network-protocols from 0.6.0 to 0.8

Fixed

• Marlowe Indexer can crash when chain indexer is syncing from Genesis.

• marlowe-contract consumes a lot of memory.

  • The garbage collector was holding onto a rolling window of snapshots
    spanning 2160 blocks of all live Marlowe contracts. It only ever needed to
    hold onto the datum hashes of the merkleized continuations in the
    contracts, so rather than keeping all the contracts around it now just
    holds onto these.

• Space leak in marlowe-contract

• Duplicate blocks can break marlowe-chain-sync queries

• Delete all blocks when rolling back to Genesis.

• Arbitrary Marlowe instances which were not generating invalid currencies and tokens.

• Safety analysis transaction filtering which was causing selective tx reporting.

marlowe-runtime-web 1.0.0 — 2024-04-22

Added

• Enhanced error information (including CoinsSelectionError, MarloweTransactionError, etc.).

• Optional Initialization of Participant's Account during contract creation

  • Allows simultaneous deposits during the creation process

• Safety Errors are available at :

  • Contract creation (Building the Tx) : POST /contracts
  • Input application (Building the Tx) : POST /contracts/:contractId/transactions

• Additional semantics info to response from GET /contracts/:contractId/transactions/:transactionId

  • inputState is the Marlowe state from the transaction's input datum.
  • inputContract is the Marlowe contract from the transaction's input datum.
  • reconstructedSemanticInput is the reconstructed TransactionInput that
    was passed to computeTransaction during the execution of the Marlowe
    semantics validator. This includes the correct TimeInterval against which
    to evaluate the input contract and state. The upper bound of this interval
    differs from invalidHereafter by -1 milliseconds.
  • reconstructedSemanticsOutput is the reconstructed TransactionOutput
    that calling computeTransaction inside the validator produces. This can
    be used to recover any intra-state payment information, as well as anyO
    warnings which were raised during evaluation. This information is not
    otherwise available in the response.

Changed

• Transitioned REST API error encoding from a generic format to a more explicit error structure.

marlowe-apps 1.0.0 — 2024-04-22

Removed

• Removed marlowe-scaling executable because marlowe-benchmark now serves this function.

• Removed marlowe-finder executable because marlowe-benchmark now serves this function.

• Removed marlowe-streamer executable because marlowe-benchmark now serves this function.

• Removed marlower-signer executable.

Changed

• Upgrade to cardano-api 8.37.1.1

• Upgrade cardano-api 8.37.1.1 to 8.39.2.0 (Conway Hard Fork Adaptation)

• Upgrade plutus from 1.15 to 1.21 (plutus-core, plutus-ledger-api, plutus-tx) (Conway Hard Fork Adaptation)

marlowe-benchmark 0.1.0.0 2024-04-22

Changed

• Added sanchonet as a new network example (Conway Hard Fork Adaptation)

Added

• Implemented basic benchmarking for Marlowe Runtime sync and query protocols.

• Added benchmark for the basic lifecycle of a Marlowe contract.

• Benchmarking of arbitrary complex queries.

marlowe-cli # 1.0.0 — 2024-04-22

Removed

• watch command
• Alonzo era support

Added

• Upgrade to cardano-api 8.37.1.1

Changed

• Marlowe CLI swap template tokens default to ada if not specified.

• Upgrade cardano-api 8.37.1.1 to 8.39.2.0 (Conway Hard Fork Adaptation)

• Upgrade plutus from 1.15 to 1.21 (plutus-core, plutus-ledger-api, plutus-tx) (Conway Hard Fork Adaptation)

• Upgrade cardano-ledger (Conway Hard Fork Adaptation)

  • cardano-ledger-conway from 1.11 to 1.12
  • cardano-ledger-core from 1.9 to 1.10
  • cardano-ledger-mary from 1.4 to 1.5
  • cardano-ledger-shelley from 1.8 to 1.9
  • cardano-ledger-binary from 1.2 to 1.3

• Upgrade ouroboros-network (Conway Hard Fork Adaptation)

  • ouroboros-network-api from 0.6.0 to 0.7.0
  • ouroboros-consensus from 0.14 to 0.16
  • ouroboros-network-protocols from 0.6.0 to 0.8

Fixed

• Marlowe CLI withdrawal no longer includes a validity interval.

• analyze command so it doesn't override provided state.

marlowe-contracts 1.0.0 — 2024-04-22

Changed

• Upgrade cardano-api 8.37.1.1 to 8.39.2.0 (Conway Hard Fork Adaptation)
• Upgrade plutus from 1.15 to 1.21 (plutus-core, plutus-ledger-api, plutus-tx) (Conway Hard Fork Adaptation)
• Upgrade cardano-ledger (Conway Hard Fork Adaptation)
  • cardano-ledger-conway from 1.11 to 1.12
  • cardano-ledger-core from 1.9 to 1.10
  • cardano-ledger-mary from 1.4 to 1.5
  • cardano-ledger-shelley from 1.8 to 1.9
  • cardano-ledger-binary from 1.2 to 1.3
• Upgrade ouroboros-network (Conway Hard Fork Adaptation)
  • ouroboros-network-api from 0.6.0 to 0.7.0
  • ouroboros-consensus from 0.14 to 0.16
  • ouroboros-network-protocols from 0.6.0 to 0.8

marlowe-object 1.0.0.0 — 2024-04-22

Changed

• Upgrade cardano-api 8.37.1.1 to 8.39.2.0 (Conway Hard Fork Adaptation)
• Upgrade plutus from 1.15 to 1.21 (plutus-core, plutus-ledger-api, plutus-tx) (Conway Hard Fork Adaptation)
• Upgrade cardano-ledger (Conway Hard Fork Adaptation)
  • cardano-ledger-conway from 1.11 to 1.12
  • cardano-ledger-core from 1.9 to 1.10
  • cardano-ledger-mary from 1.4 to 1.5
  • cardano-ledger-shelley from 1.8 to 1.9
  • cardano-ledger-binary from 1.2 to 1.3

Marlowe Runtime v0.0.6

Highlights

Runtime 0.0.6 introduces several new features and addresses some performance issues.

Open Roles

The most significant addition to this release is support for open roles, which allow anyone to participate in a contract after it has been created. Roles secure contracts by requiring an NFT to be spent to perform actions. Only individuals capable of spending the role token can perform these actions. In a regular "closed" role, this token is sent to the wallet intended to fill the role. In an open role, the token is sent to a script output that can be spent by anyone under the following conditions:

• The contract has the correct role token minting policy ID in the datum
• The contract holds a thread token that matches the token name in the datum of the script output holding the open role.
• The contract action does not send any payments (this is to prevent a double satisfaction attack).
• The contract is awaiting input for an action authorized to the open role (i.e. a deposit or a choice).

The Runtime will send the role token to the wallet that created the transaction, converting it to a closed role owned by that wallet afterwards.

Role Token Minting Improvements

Role token minting is more flexible:

• Multiple tokens can be minted per role
• Tokens for a given role can be sent to multiple recipients
• CIP-25 is fully implemented, allowing for arbitrary additional properties in the token metadata and file metadata objects.

Bulk Sync Protocol

Another significant new feature is the new bulk sync protocol. This protocol combines the capabilities of the existing header sync and Marlowe sync protocols: header sync streams all on-chain contract creation events; Marlowe sync streams all Marlowe contract events (creation, input application, and withdrawal) for a single contract; and bulk sync streams all Marlowe contract events for all contracts.

Before bulk sync, obtaining a stream of all events was extremely difficult and costly: doing so involved running a header sync client to detect all contract creations and running parallel Marlowe sync clients for each contract to stream their events.

This functionality is particularly useful to agent processes which monitor Marlowe traffic. For example, an oracle might watch for contracts which require its input in the form of a choice action, or a janitor service might watch for contracts that have timed out and which can be closed.

Marlowe Runtime 0.0.6 — 2023-12-06

Added

• New bulk sync protocol which allows clients to subscribe to all events from
  all marlowe contracts.

• Garbage collection added to marlowe-contract

• More documentation in --help text

• Added support for creating and applying input to "open role" contracts.

• Safety analysis support for open-role contracts.

• marlowe-chain-copy executable for efficiently seeding a new chain database.

• Support for advanced role token distribution.

  • Mint multiple tokens per role
  • Send tokens to multiple recipients.

• Arbitrary extra properties can be added to role token metadata.

• Published Marlowe validators compiled under plutus-1.15.0.0.

Changed

• Min lovelace deposit is optional, and a default will be computed if omitted.

• Improve signal-to-noise ratio of chain sync protocol logging.

• Dropped asset table from chain schema, inlining fields into assetOut
  and assetMint.

• Improved sync performance of marlowe-chain-indexer by switching from
  INSERT to COPY.

• Internal: consolidated database row extraction logic for cardano blocks into
  reusable modules.

• Improved sync performance of marlowe-indexer.

• marlowe-indexer now indexes contracts by parties in the accounts as well as
  the contract.

Fixed

• Building a transaction for a contract that uses ADA role tokens fails.

• The TransactionInput definition in the generated OpenApi schema for Marlowe Runtime Web is now explicitly typed as an object.

• Safety checks fail when open roles and default thread token name are used.

• The generated OpenApi schema represented tuples as heterogenous arrays which was not allowed with OpenApi specification 3.0.0. The schema was set to target OpenApi specification 3.1.0.

Marlowe Runtime Web 0.0.6 — 2023-12-06

Added

• Added support for creating and applying input to "open role" contracts.

Changed

• Fixed errors and added clarification to Open API documentation.

Fixed

• 5xx responses do not include CORS headers.

Marlowe Runtime v0.0.5

Summary

This release introduces new queries for Payouts, as well as a /payouts REST API. It also changes the way withdrawals are done, and adds contract query filtering by party address and role. It is also the first release to target cardano-node 8.1.2.

Changelog - Marlowe Runtime

Added

• New payouts API that supports:

  • Querying payouts with filtering support for contract IDs, role tokens, and
    claim status.
  • Querying a single payout by its ID

• New filters to GetHeaders query to allow filtering contract headers by party
  (addresses and role tokens). Specifying parties in the filter will limit
  results to contracts which (visibly) contain either the address or role token as a
  party.

  • Regarding "visibly contain": this applies to merkleized contract. A
    merkleized contract visibly contains a party if the party can be extracted
    from its on-chain history without having access to the continuations. This
    means any parties contained in unexecuted paths of the contract are not
    included, because they aren't visible.

• New query parameters for /contracts endpoint partyAddress and partyRole.
  These give REST API access to the party filtering functionality mentioned
  above.

• Added new validator scripts to script registry.

• GHC 9.2 support

Changed

• BREAKING: marlowe-tx: Create, ApplyInputs, and Withdraw now use the era reported by the node to build the TxBody.

  • Era is queried from the node at the time of job execution.
  • The era information is returned in the results of the jobs.
  • If the era does not support reference scripts (i.e. prior to Babbage) the
    command will fail wit an EraUnsupported error.

• BREAKING: marlowe-tx: Submit now accepts transactions from any era that
  supports reference scripts, not exclusively babbage. This is a breaking
  change because the era information must now be included in the command.

• BREAKING Withdraw now accepts a set of payout tx outs instead of a contract
  ID and a role token. The old behaviour can be emulated via a query to fetch
  unclaimed payouts for a contract.

• Updated script hashes in script-registry test.

• BREAKING: cardano-api, plutus, cardano-ledger dependencies track with cardano-api 8.2

• BREAKING: marlowe-tx and marlowe-runtime now require a command line option for a program to generate the role token minting validator.

• BREAKING: Requires cardano-node 8.1.2

Changelog - Marlowe Runtime Web

Added

• Assets to several response schemas
  • In Payout - shows the assets in the tx output corresponding to the payout.
  • In ContractState - shows the assets in the current UTxO of the contract (the account balances). Empty if the contract has no UTxO (i.e. the contract is closed).
  • In Tx - shows the assets in the marlowe script output of that transaction (the account balances). Empty if the transaction does not produce an output.
• Payouts produced by a transaction are added to Tx

Changed

• Custom error formatter for request body parsing failures

• More details displayed about internal server errors

• Tokens json objects are deserialized now without the unTokens field.

• Use of generics for REST error reporting

• Improved quality of generated Open API documentation

Fixed

• Serialization for Token Names containing "."

Marlowe CLI v0.1.0.0

Removed

• BREAKING inoperative chain sync connection options from test command removed.

Added

• Format conversion with marlowe-cli format

• Open role Plutus script, which releases role token on deposit.

• Simulation mode to the testing DSL, which maintains in memory UTxO set.

• Extra safety analytical cases for accompanying scripts.

Changed

• Print a list of commands when marlowe-cli is invoked without a command

• Pre-compiled scripts are used for all commands using validators.

• BREAKING: Requires cardano-node 8.1.2

Marlowe Apps v0.3.0.0

Removed

• BREAKING inoperative chain sync connection options removed from all executables.

Added

• Executable marlowe-streamer for server-sent event (SSE) stream of Marlowe contracts.

• Added a random-number oracle.

• Added an external-process oracle.

• Docker images for executables.

• Added marlowe-streamer client that streams Marlowe contracts using HTTP server-side events (SSE).

Marlowe CLI v0.0.12.0

Added

• Support for client side merkleization in both Runtime and CLI based runners.

• Support for externaly minted currencies through currency symbol in the DSL.

• Support for loading external wallets.

• Support for direct usage of external addresses in the minting process and in contracts.

• Golden test for Plutus execution-cost analysis (PLT-6907).

Changed

• Minting logic so it creates minimal set of token bundled UTxOs

Marlowe Runtime v0.0.4

Release Notes

Marlowe Runtime

Removed

• BREAKING MarloweTracedT - now there is only MarloweT.

• Custom Marlowe JSON with imports format for marlowe-runtime-cli load

• Traces from chain sync and chain seek clients

Added

• marlowe-runtime executable and Docker image providing an all-in-one runtime option.

• Safety analysis integrated into contract creation result.

• New ReqStatus query to Marlowe Query that returns sync info and version info.

• Status information is now included in response headers of all REST API calls.

• Added --stake-address to marlowe-runtime-cli create command, for attaching stake credentials to Marlowe's validator address.

• New main protocol MarloweTransfer for copying contracts to / from contract store.

• marlowe-runtime-cli export command to download a contract bundle from the store.

• POST /contracts/sources endpoint provides access to contract import in the
  REST API (via MarloweTransfer).

• /contracts/sources/:contractSourceId endpoint with GET method and two sub-resources for adjacency and closure.

• Request body for POST /contracts now accepts a contract source ID as well as contract JSON.

• Console logs for marlowe-chain-indexer and marlowe-indexer sync progress

Changed

• marlowe-runtime-cli load now accepts a contract bundle

• Sync performance of marlowe-indexer improved via bulk queries.

• New partitions added to accommodate slots upt to 200 million in chain database.

• BREAKING MerkleizeInputs accepts a contract instead of a hash.

• Signature of Language.Marlowe.Runtime.Transaction.Safety.checkTransactions change to use protocol parameters in place of constraint solver.

Fixed

• Metadata tag length cannot be longer than 64 characters

  • metadata tags now get chunked into lists of text of max. 64 characters
    each to comply with the CDDL specification for transaction metadata.

• Importing a JSON contract doesn't work

• Importing an exported contract archive doesn't work

• Computation of maximum possible Plutus execution costs now rounds upwards.

• Transaction submission hangs when chain sync loses connection to node.

• Auto-merkleization of inputs fails if contract in datum got reduced.

• Removed inconsistency in system start for safety checks (PLT-6849).

Marlowe Runtime Web

Added

• New Endpoint GET : contracts/:contractId/next (Provide a description of what can be done for a given contract)

• Results of contract's safety analysis reported in create response.

• Unclaimed payouts added in /contracts/:contractId

• Optional Filetring by Party for GET : contracts/:contractId/next

• Added header X-Stake-Address for creating contracts.

Marlowe Runtime v0.0.3

This is a hotfix release that addresses a schema issue in marlowe-indexer.

Fixed

• Added migration to change tags column from varchar(64) to text.

Marlowe Runtime v0.0.2

This is a prerelease - it may contain breaking changes from a previous version.

0.0.2 — 2023-06-15

Removed

• JSON console logs
• BREAKING - --log-config-file command line options
• BREAKING - --print-log-config commands

Added

• Safety checks for Marlowe contracts.

• OpenTelemetry-based tracing

• Second port to marlowe-proxy for clients that provide their own tracing
  information.

• marlowe-contract service for contract definition storage.

  • Includes a file-based store and a server for the MarloweLoad protocol.

• BREAKING MarloweLoad as a sub-protocol of MarloweRuntime service

  • marlowe-proxy now requires a host and port for marlowe-contract

• functions for running MarloweLoad clients to marlowe-client

• load command to marlowe-runtime-cli

• Contract query to marlowe-proxy

• query store commands to marlowe-runtime-cli

• MarkleizeInputs request to ContractRequest (marlowe-contract query API)

• Option to pass a DatumHash to marlowe-tx's Create command. This will
  load the matching contract from the contract store.

• --contract-hash option to marlowe-runtime-cli create to pass a contract hash
  obtained via marlowe-runtime-cli load when creating a contract.

• Safety checks for invalid Plutus addresses.

• Uncaught exceptions in server threads are now logged to stderr rather than
  being swallowed.

Changed

• [Internal] tracing code refactored to use a mtl-style class instead of
  explicit tracer passing.

• BREAKING - Extracted generic query protocol and reworked marlowe-sync's
  query protocol to use it.

• Apply will auto-merkleize normal inputs to a contract if the contract is in
  the store.

  • E.g. Given an on-chain contract When [MerkleizedCase (Notify TrueObs) "foo"] 0 Close,
    a client can call Apply with [NormalInput INotify] and marlowe-tx will
    merkleize it automatically if it can find the contract in the store.
    Clients can still pass manually merkleized inputs to Apply if desired.

• Console log formatting.

• Increased the maximum confirmation wait time in marlowe-tx to 1 hour.

• If OTEL_EXPORTER_OTLP_ENDPOINT env var is not set, runtime will not attempt
  to send traces anywhere.

Fixed

• Implements missing support in the Marlowe Runtime CLI apply command to accept input files through the --input-file argument.

• Driver state threading in runPeerDriverTraced

• marlowe-runtime-cli choose --help displayed description for notify.

• Console logs are now thread-safe.

• marlowe-scaling did not delay polling at all when submitting a transaction.

Marlowe Runtime v0.0.1

Initial release for Marlowe Runtime. This is a pre-release, not intended for production use. Subsequent releases will include release notes.