Specification for CIP-30 Runtime Client

[jhbertra]

Overview

Starting this new discussion thread for the specification for the CIP-30 demo client for Marlowe Runtime.

I'd like to start with a few high-level goals:

• Demonstrate ability to integrate with the CIP-30 light wallet standard
  • Obtain wallet addresses, collateral UTXOs, and change wallet from a CIP-30 light wallet
  • Sign a transaction with a CIP-30 light wallet
  • Present a summary of the Marlowe transaction to the user
• Provide a simple (even simplistic) code-based example of interfacing between the runtime and the CIP-30 JS API.

I'd like to do this in a way that is quick and easy to build, so here are a list of non-goals that this project should not attempt to do:

• Require a complex front-end build process
• Flesh out a client library for general-purpose CIP-30 integration
• Flesh out a general-purpose web API for the runtime.

The goals of this project should be to keep it simple and minimal. Many of the above tasks are planned to be worked on separately. What follows is a specification for the project's components, and how they interact.

Web Server

The web server component serves the front end as HTML content with embedded JavaScript. It has the following routes:

GET /

Serves the wallet selection page which looks in the global cardano object for the listed wallets and allows the user to select them.

Available links:

• GET /:walletName for each wallet found in the cardano object.

GET /:walletName

Serves the app for the wallet with the given name. If the wallet is enabled, it displays the main menu for the wallet. Otherwise, it requests permission for the wallet, then displays the main menu or an error if the user denies permission. All subroutes of this root perform this check upon initializing the page.

Available links:

• GET /:walletName/create
• GET /:walletName/deposit
• GET /:walletName/choose
• GET /:walletName/notify
• GET /:walletName/withdraw

GET /:walletName/create

Serves a form for creating a new contract. It is just a text area where the user can enter a (core) Marlowe contract in JSON and a submit button. The submit button handler has a JavaScript handler which makes a POST request via fetch to /:walletName/create with the contents of the text box, along with the used addresses and the collateral UTXOs queried from the CIP-30 wallet API.

Available links:

• POST /:walletName/create (via JS form handler)
• POST /:walletName/tx (via JS handler)
• GET /:walletName

POST /:walletName/create

Accepts form content from the create page, processes it and builds a create tx. Serves a JSON response containing the unsigned TxBody as a CBOR string as required by CIP-30's signTx API as well as the contractId. The page handles this response by calling signTx and sending the response to POST /:walletName/tx. After confirmation from this call, the contractId is displayed to the user in place of the form.

GET /:walletName/deposit

Serves a form for depositing funds into a contract. The form requires:

• The contractId of the contract to deposit into
• The amount of funds to deposit
• The asset to deposit (either ADA or a custom token consisting of a currency symbol + token name).
• The party making the deposit (either a role or an address the wallet controls).
• The account to deposit into (either a role or an address).

The interaction with the CIP-30 wallet and handling of the transaction here is the same as for create.

POST /:walletName/deposit

Accepts form content from the deposit page, processes it and builds an apply-inputs tx. Reponse is the same for create, except it does not include the contractId.

GET /:walletName/choose

Serves a form for making a choice in a contract. The form requires:

• The contractId of the contract to make a choice for.
• The choiceId of the choice being made.
• The value of the choice.
• The party making the choice (either a role or an address the wallet controls).

The interaction with the CIP-30 wallet and handling of the transaction here is the same as for create.

POST /:walletName/choose

Accepts form content from the choose page, processes it and builds an apply-inputs tx. Reponse is the same for create, except it does not include the contractId.

GET /:walletName/notify

Serves a form for making a choice in a contract. The form requires:

• The contractId of the contract to notify.

The interaction with the CIP-30 wallet and handling of the transaction here is the same as for create.

POST /:walletName/notify

Accepts form content from the notify page, processes it and builds an apply-inputs tx. Reponse is the same for create, except it does not include the contractId.

GET /:walletName/withdraw

Serves a form for making a withdrawal from a contract role. The form requires:

• The contractId of the contract to withdraw from.
• The role to withdraw from.

The interaction with the CIP-30 wallet and handling of the transaction here is the same as for create.

POST /:walletName/withdraw

Accepts form content from the withdraw page, processes it and builds a withdraw tx. Reponse is the same for create, except it does not include the contractId.

Tech stack

For this project, I recommend using Yesod instead of Servant. It has built-in support for HTML and JavaScript templating that Servant lacks. For the JavaScript, I recommend using vanilla JS (i.e. no frameworks) written using the julius DSL that Yesod supports. Styling is not necessary, but could be added via cassius if desired. We really only need the following bits of JS functionality:

• Collecting the list of wallet names and rendering them
• Enabling the CIP-30 API for a wallet
• Showing the main menu by either changing its style or adding a class that reveals it.
• Handling the form input from the tx forms.
• Querying the addresses, change address, and collateral UTXOs from the CIP-30 API.
• Making fetch requests to the POST endpoints
• Handling the responses from the POST endpoints
• Calling signTx for the wallet
• Showing the contractId for new contracts after they are created.

Which should be easy enough to do without a framework that depending on one would just make things unnecessarily complicated.

Questions

• How do we get a light wallet to connect to the preview network? Can this be configured, or do we need to fork/build Nami from source?

[bwbush]

How do we get a light wallet to connect to the preview network? Can this be configured, or do we need to fork/build Nami from source?

Several of the CIP-30 wallets have a network-selection option. Here is Nami wallet:

[jhbertra]

Great. I created a Eternl wallet on preview yesterday.

[bwbush]

Resources:

• CIP-30 specification
• CIP-30 SDK for Lace

[bwbush]

I like keeping this separate from contract discovery and history. However, will the design be compatible/coexist with services for discovery and history?

[jhbertra]

I think that we can potentially use this POC as a model when we want to add CIP-30 integration to those parts of the runtime.

[bwbush]

Is there a difference in security of using REST vs WebSockets? I think the design should be compatible with a highly secure implementation.

The main attack vector is a person-in-the-middle attack that alters the transaction just before it is signed or a similar cross-site or intra-browser attack.

[jhbertra]

No, there is no difference in security. WebSocket and HTTP are both application layer protocols, and their secure versions wss: and https: are simply secured at the transport layer by TLS.

[bwbush]

Which should be easy enough to do without a framework that depending on one would just make things unnecessarily complicated.

I agree that we want this first implementation as minimal as possible.

I do wonder whether the client should have an option to let the user choose whether to submit via Marlowe Runtime versus the CIP -30 wallet. We're probably departing (for good reason) from the standard practice of letting the wallet submit via its node infrastructure.

[jhbertra]

I suppose if they have a signed transaction they can feel free to submit it however they like. However, we can do some extra steps via the runtime, such as automatically following contracts upon creation.

[bwbush]

Perhaps not for the POC, but we might want to experiment with the wallets. I presume that the wallet would discover the transaction's confirmation equally well whether its node submits it or our node does, but this might not actually be the case.

[palas]

Looks great! Just a general suggestion I think it would be useful for readers to add at the beginning some introduction along the lines of:

CIP-30 Runtime Client is a simple demo web application that allows clients to deploy Marlowe contracts and execute simple Marlowe commands using simple HTML forms and light-wallet integration through CIP-30

And other than that just wanted to point out that it may be quite straightforward to add optional continuation fields for Deposit/Choice/Notify, for example, and that would pretty much provide support for low-level merkleization. So maybe it is a low hanging fruit

[jhbertra]

Yes, that sounds like a reasonable addition to the deposit, notify, and choose endpoints

[bwbush]

@bjornkihlberg, the CLI versions of the above POST requests either already exist or will exist later in this sprint: see "Contract transaction commands" below. Implementing the CIP-30 runtime client will probably fall into three areas:

1. Expose the create, deposit, choose, notify, advance, and withdrawal commands of the CLI as REST POSTs.
2. Serve the HTML forms for the various GET commands that feed into the POSTs.
3. Interact with the CIP-30 wallet for . . .
   a. Wallet selection: cardano.{walletName}.enable(): Promise<API> etc.
   b. Discovering wallet address(es): api.getUsedAddresses
   c. Asking the wallet to sign a transaction: api.signTx(tx: cbor<transaction>, partialSign: bool = false): Promise<cbor<transaction_witness_set>>

$ marlowe --help
Usage: marlowe [--history-host HOST_NAME] [--history-command-port PORT_NUMBER] 
               [--history-query-port PORT_NUMBER] 
               [--history-sync-port PORT_NUMBER] [--discovery-host HOST_NAME] 
               [--discovery-query-port PORT_NUMBER] [--tx-host HOST_NAME] 
               [--tx-command-port PORT_NUMBER] (COMMAND | COMMAND | COMMAND)

  Command line interface for managing Marlowe smart contracts on Cardano.

Available options:
  -h,--help                Show this help text
  --history-host HOST_NAME The hostname of the Marlowe Runtime history server.
                           Can be set as the environment variable
                           MARLOWE_RT_HISTORY_HOST (default: "127.0.0.1")
  --history-command-port PORT_NUMBER
                           The port number of the history server's job API. Can
                           be set as the environment variable
                           MARLOWE_RT_HISTORY_COMMAND_PORT (default: 3717)
  --history-query-port PORT_NUMBER
                           The port number of the history server's query API.
                           Can be set as the environment variable
                           MARLOWE_RT_HISTORY_QUERY_PORT (default: 3718)
  --history-sync-port PORT_NUMBER
                           The port number of the history server's
                           synchronization API. Can be set as the environment
                           variable MARLOWE_RT_HISTORY_SYNC_PORT (default: 3719)
  --discovery-host HOST_NAME
                           The hostname of the Marlowe Runtime discovery server.
                           Can be set as the environment variable
                           MARLOWE_RT_DISCOVERY_HOST (default: "127.0.0.1")
  --discovery-query-port PORT_NUMBER
                           The port number of the discovery server's query API.
                           Can be set as the environment variable
                           MARLOWE_RT_DISCOVERY_QUERY_PORT (default: 3721)
  --tx-host HOST_NAME      The hostname of the Marlowe Runtime transaction
                           server. Can be set as the environment variable
                           MARLOWE_RT_TX_HOST (default: "127.0.0.1")
  --tx-command-port PORT_NUMBER
                           The port number of the transaction server's job API.
                           Can be set as the environment variable
                           MARLOWE_RT_TX_COMMAND_PORT (default: 3720)

Contract history commands
  add                      Start managing a new contract
  log                      Display the history of a contract
  ls                       List managed contracts
  rm                       Stop managing a contract

Contract transaction commands
  apply                    Apply inputs to a contract
  advance                  Advance a timed-out contract by applying an empty set
                           of inputs.
  deposit                  Deposit funds into a contract
  choose                   Notify a contract to proceed
  notify                   Notify a contract to proceed
  create                   Create a new Marlowe Contract
  withdraw                 Withdraw funds paid to a role in a contract

Low level commands
  submit                   Submit a signed transaction to the Cardano node.
                           Expects the CBOR bytes of the signed Tx from stdin.