Marlowe Runtime Web API

[jhbertra]

The purpose of this thread is to discuss the design of the Marlowe Runtime Web API. The purpose of the Web API is to provide a more programmer-friendly interface to the Marlowe Runtime compared with the binary protocols. The API server will be built on top of the binary protocols and may offer more abstract / higher-level capabilities.

Components

The two main components of the API are:

• Marlowe REST API
  • Provides a RESTful interface to the resources and capabilities of the runtime
  • Supports multiple media types for different purposes
    • JSON for programmatic use
    • HTML for human interaction via web browsers
• Marlowe WebSocket API
  • Provides a realtime subscription interface to the runtime
  • Allows clients to subscribe to streams of events (e.g. contract deployments, contract transactions, payouts)

Marlowe REST API

Following RESTful architecture, this API maps all entities, operations, and system states to a set of resources identified by URIs. These resources are linked to one another via hypermedia links. Thus, all operations available on a resource can be discovered by querying that resource. One of the goals of this discussion is to define these resources, the structure of their URIs and the topology of their links to one another.

Another goal of the discussion is to discuss what media types to support. JSON is an obvious (and ubiquitous) choice, but supporting HTML would also be useful, as it would allow web browsers to display the resources as web pages. Furthermore, the links can be rendered in HTML as clickable hyperlinks as well as forms for allowing manual execution of operations.

Marlowe WebSocket API

We need to define the domain's subscribable events and provide WebSocket APIs. Here are some candidates:

• History events for a contract (transactions, payouts, payout redemption) with state updates (marlowe-history)
• Deployment of contracts on chain (marlowe-discovery)
• Status of submitted transactions (marlowe-tx)

Additionally, we could consider adding WebSocket APIs for changes of other state, but this may be unnecessary.

Additional Components

Some additional components that are necessary to form the core of the ecosystem are:

• Client libraries
  • Can largely be generated from Servant
  • Can target different client languages
  • Abstracts raw HTTP requests
  • A necessity if we seriously expect anyone to use the API
• API documentation
  • We can generate OpenAPI documentation from Servant types
  • Can be connected to a server to allow interactive testing of endpoints via swagger UI
• Docker image
  • include in Docker Compose configuration
  • Publish separately
• Hosted deployments
  • For people to test with
  • Possibly rate limit requests with API keys to override rate limiting

[jhbertra]

Resources

Here is one possible RESTful representation of the runtime as resources:

Root

The root resource is the resource that links to all top-level resources.

URI(s)

• /
  • GET returns the root resource

Representation

null

Links

• /v1/contracts - the list of contracts

Contract

This refers to a Marlowe contract deployed on chain.

URI(s)

• /v1/contracts[?followed]
  • GET paginates through all contracts (corresponds to marlowe ls [-a])
  • POST builds an unsigned contract creation transaction (corresponds to marlowe create)
• /v1/contracts/{contracId}
  • GET returns the state of a specific contract, or a submission status message if it is being submitted.
  • POST submits the signed creation transaction for a specific contract (corresponds to marlowe submit)
  • PUT allows the followed status to be set (corresponds to marlowe add as well as marlowe rm)

Representation

The current state of the contract (i.e. the datum of the most recent UTxO or Close contract/state if the contract is closed) and whether or not it is followed (actively managed and monitored by the runtime).

Links

• /v1/contracts/{contractId}/payouts - the list of payouts from the contract
• /v1/contracts/{contractId}/withdrawals - the list of withdrawals from the contract
• /v1/contracts/{contractId}/transactions - the history of transactions for the contract
• /v1/contracts/{contractId}/roles - the roles for the contract

Transaction

An event that changes the state of a Marlowe contract.

URI(s)

• /v1/contracts/{contractId}/transactions
  • GET paginates through the history of transactions for a contract (corresponds to marlowe log)
  • POST builds an unsigned apply inputs transaction for a contract (corresponds to marlowe apply)
• /v1/contracts/{contractId}/transactions/{transactionId}
  • GET returns the details of the specific transaction, or a submission status message if it is being submitted.
  • POST submits a signed apply inputs transaction for a contract (corresponds to marlowe submit)

Representation

An object consisting of the Cardano Tx data, the Marlowe inputs, the resulting state and contract.

Links

• /v1/contracts/{contractId}/transactions/{transactionId}/payouts the list of payouts from the transaction
• /v1/contracts/{contractId} the parent contract

Payout

A payment to a role from a contract. (Qeustion should this include non-role payouts too?)

URI(s)

• /v1/contracts/{contractId}/payouts[?role={roleName}][&redeemed=(true|false)]
  • GET paginates through the set of payouts for a contract
• /v1/contracts/{contractId}/transactions/{transactionId}/payouts[?role={roleName}][&redeemed=(true|false)]
  • GET paginates through the set of payouts from a specific transaction
• /v1/contracts/{contractId}/payouts/{payoutId}
  • GET returns the details of a specific payout

Representation

An object containing the UTxO that created the payout, the role the payout was sent to, and whether or not it is redeemed.

Links

• /v1/contracts/{contractId}/withdrawals/{withdrawalId} the withdrawal that redeemed the payout
• /v1/contracts/{contractId}/roles/{roleName} the role to which the payout was sent
• /v1/contracts/{contractId} the parent contract

Withdrawal

A transaction that redeems a payout to a role in a contract

URI(s)

• /v1/contracts/{contractId}/withdrawals[?roleName={roleName}]
  • GET returns the list of withdrawal transactions for a contract
  • POST builds an unsigned withdrawal transaction for a contract (corresponds to marlowe withdraw)
• /v1/contracts/{contractId}/withdrawals/{withdrawalId}
  • GET returns the details of a specific withdrawal, or a submission status message if it is being submitted.
  • POST submits a signed withdrawal transaction for a contract (corresponds to marlowe submit)

Representation

An object containing the payout(s) that was/were redeemed, the role to which the payouts were sent, and the address of the wallet that withdrew the funds.

Links

• /v1/contracts/{contractId}/payouts/{payoutId} the payout(s) that the withdrawal redeemed
• /v1/contracts/{contractId}/roles/{roleName} the role that withdrew the funds
• /v1/contracts/{contractId} the parent contract

Role

A role in a contract is an abstract entity. In Cardano, you must hold the correct role token in your wallet to perform actions on behalf of a role.

URI(s)

• /v1/contracts/{contractId}/roles
  • GET returns the minting policy ID for the contract and the list of role token names for the contract.
• /v1/contracts/{contractId}/roles/{roleName}
  • GET returns the details of the role
• /v1/contracts/{contractId}/roles/{roleName}/owners
  • GET returns the ownership history of the role token

Representation

An object containing the minting transaction, current owning address, minting policy ID, token name, and metadata of the role token.

Links

• /v1/contracts/{contractId}/payouts/{payoutId} payouts made to a role in a contract.
• /v1/contracts/{contractId} the contract(s) a role is party to.

[arthur-cmd]

How can i install this marlowe runtime webserver.I only see instructions to install marlowe-cli and marlowe-runtime-cli ,please can i get your assistance.

[jhbertra]

Other domains to consider (thanks for listing these @bwbush)

• Versions
  • List Marlowe versions and reference script addresses and TxOutRefs
  • Fetch the Marlowe validators for a specified Marlowe version

This clearly fits into a REST API quite nicely. Here's an idea of the routes we could support:

• GET /versions -list all versions
• GET /versions/{version} - list all published reference scripts for a version
• GET /versions/{version}/{marloweScriptHash} - show the details of a published reference script set (app + payout validator hash and data, tx out info).
• GET /{version}/contracts - list all contracts by version (already part of proposed API).

• Merkleization
  • Merkleize a contract (deep or shallow)
  • Demerkleize a contract (deep or shallow)
• Language
  • Convert from Core to Extended Marlowe
  • Convert from Extended to Core Marlowe (I'm not sure what this would look like really)
• Analysis
  • Compute the validity interval for an input to a contract
  • Simulate the application of an input to a contract
  • List next possible inputs to a contract
  • List all execution paths of a contract
  • Perform static analysis of the semantics of a Marlowe contract
  • Check/lint a Marlowe contract for viability on the Cardano blockchain

I find these a little less clear in terms of their mapping to URIs/resources. I assume most would be POST requests to some URI where you provide the contract in the request body and it responds with the result. Would these be persistent? I.e. would the POST request create a resource which you could then GET? This is not strictly necessary, but it is a good mental model to check if you're designing a REST API that people will not be surprised by.

One possible representation of this is to create an intermediary environment resource that keeps track of contracts and operations performed on them for the user, e.g.

• POST /environments - list all active environments
• GET /environments/{environmentId}/contracts - list contracts in the environment
• GET /environments/{environmentId}/contracts/{contractHash} - show a specific contract in the environment
• POST /environments/{environmentId}/contracts - add a new (extended or core) contract to the environment
• GET /environments/{environmentId}/contracts/{contractHash}/core[?param1={val}&...] - get the core Marlowe representation of a contract given a set of parameters.
  (assume the rest of these also have the params in the query string, or that /core returns a new contractHash that can be used to interact with the core contract)
• POST /environments/{environmentId}/contracts/{contractHash}/reductions -- apply inputs and get the resulting contract hash (to fetch with GET /environments/{environmentId}/contract/{contractHash}
• GET /environments/{environmentId}/contracts/{contractHash}/inputs list all possible inputs for a contract
• GET /environments/{environmentId}/contracts/{contractHash}/paths list all possible execution paths through a contract (paginate) (also, wouldn't it be cool to specify an LTL filter to limit the resulting paths to ones that matches the filter?)
• GET /environments/{environmentId}/contracts/{contractHash}/analysis get static analysis for a contract
• GET /environments/{environmentId}/contracts/{contractHash}/warnings lint a contract
• DELETE /environment/{environmentId} delete an environment
• DELETE /environment/{environmentId}/contracts/{contractHash} delete a contract from an environment

This would be an interesting REST API, but the question of persistence is a bit unclear - would we want to add this functionality to the runtime? Or would this be implemented by the web server or a separate Marlowe IDE service?

[jhbertra]

Notes from @paluh

• Remove followed from GET /v1/contracts
• POST /*/:id -> PUT /*/:id
• GET /*/:id after Post /* returns unsigned contract
• Start with /contracts and /transactinos