Skip to content
This repository has been archived by the owner on Feb 7, 2023. It is now read-only.
/ marlowe-lambda Public archive

A Marlowe Runtime client for AWS Lambda. This package has been deprecated and is no longer maintained. Please use https://github.com/input-output-hk/marlowe-cardano/tree/main/marlowe-runtime/web-server-app instead.

License

Apache-2.0 license
4 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

input-output-hk/marlowe-lambda

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

61 Commits
app
app
 
 
deploy
deploy
 
 
examples
examples
 
 
pipe
pipe
 
 
web
web
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
ReadMe.md
ReadMe.md
 
 
cabal.project
cabal.project
 
 
flake.lock
flake.lock
 
 
flake.nix
flake.nix
 
 
marlowe-lambda.cabal
marlowe-lambda.cabal
 
 
package.sh
package.sh
 
 

Repository files navigation

This package has been deprecated and is no longer maintained. Please use the Marlowe web server instead.

A Marlowe Runtime client for AWS Lambda

This Marlowe Runtime client for the AWS Lambda service enables users to create, apply inputs to, and withdraw funds from Marlowe contract instances; it also lets them list all of the Marlowe contracts on the blockchain and to examine their on-chain status and contents. Users do not need to install any Marlowe software and the only Cardano software they need is a wallet for signing the transactions. (The example here uses several command-line tools for convenience, but any toolset for calling AWS Lambda, manipulating JSON, and signing/submitting transactions could be used.) The service may be used with any Marlowe contract. In addition to providing the convenience of zero-installation use of Marlowe, AWS Lambda also supports the orchestration of complex workflows involving multiple Marlowe contracts or a mixture of Marlowe and non-Marlowe lambdas."

See this Jupyter notebook or this video for a demonstration of this client's use from the command line.

See web/ for a web Dapp that shows how to use Marowe Lambda from within a browser: this video shows the DApp in action, and this video shows it being used with a laptop for the Party and an android tablet for the Counterparty.

Deployment

Here is an outline of the steps required to deploy Marlowe Lambda:

  1. Edit deploy/bootstrap to use either mainnet, the preprod testnet, or the preview testnet.
  2. Edit the corresponding deploy/mainnet.env, deploy/preprod.env, or deploy/preview.env so that the hostnames and ports match your deployment of Marlowe Runtime. See the help for information on the environment variables for hosts and port numbers.
  3. Run ./package.sh to build the AWS Lambda ZIP file marlowe-lambda.zip.
  4. In the AWS Console or at the AWS Command Line, create a new lambda function and select the runtime Provide your own bootstrap on Amazon Linux 2 and the architecture x86_64.
  5. The this ZIP file marlowe-lambda.zip.
  6. Set the handler name to marlowe.
  7. Set the timeout in the execution role to 45 seconds.
  8. Make sure that the execution role has AWSLambdaBasicExecutionRole.
  9. If you want to use the lambda in a web application, create a Cognito Identity Pool for it and make sure that it includes a policy with the actions lambda:InvokeFunctionUrl, lambda:InvokeFunction, lambda:GetFunction, and lambda:InvokeAsync.

API

The JSON API for Marlowe Lambda contains the following requests and responses.

Request Response
list contracts
followed contacts
follow result
unfollow result
get info
create body
apply body
withdraw body
sign tx
submit txId
wait txInfo

Requests

List

List all Marlowe contract IDs on the blockchain.

{
  "request" : "list"
}

The response is Contracts.

Followed

List all Marlowe contract IDs that the Marlowe Runtime backend is following.

{
  "request" : "followed"
}

The response is Contracts.

Follow

Add a contract to the list of Marlowe contracts that the Marlowe Runtime backend is following.

{
  "request" : "follow"
, "contractId" : "66e4af5ec99f09c28c6378e1d9d9508d95544e258fd8c8e7f3ff168a73e7b656#1"
}

The response is Result. A true result indicates that the contract ID was added to the list of followed contracts, whereas a false result indicates that the contract was already being followed.

Unfollow

Remove a contract to the list of Marlowe contracts that the Marlowe Runtime backend is following.

{
  "request" : "unfollow"
, "contractId" : "66e4af5ec99f09c28c6378e1d9d9508d95544e258fd8c8e7f3ff168a73e7b656#1"
}

The response is Result. A true result indicates that the contract ID was removed from the list of followed contracts, whereas a false result indicates that the contract was not being followed.

Get

Fetch the history of a Marlowe contract.

{
  "request" : "get"
, "contractId" : "66e4af5ec99f09c28c6378e1d9d9508d95544e258fd8c8e7f3ff168a73e7b656#1"
}

The response is Info.

Create

Build a transaction that creates a new Marlowe contract.

{
  "request" : "create"
, "contract" : "/* the serialized Marlowe contract to be created */"
, "minUtxo" : "/* the number of lovelace to send to store in the contract when it is created */"
, "roles" : "/* an object that maps role names to the addresses to which the corresponding role tokens should be sent after it is minted */"
, "metadata" : "/* the transaction metadata in JSON format */"
, "addresses" : "/* the list of addresses, in addition to the change address, where UTxOs can be used as input to the transaction */"
, "change" : "/* the address to which change from the transaction will be sent */"
, "collateral" : "/* the list of UTxOs that may be used for collateral, or an empty list if any UTxO may be used for collateral */"
}

See Contract in https://github.com/input-output-hk/marlowe/blob/master/isabelle/haskell/MarloweCoreJson.lhs for definition of the JSON format of a Marlowe contract.

The response is Body.

Apply

Build a transaction that applies input to a Marlowe contract.

{
  "request" : "apply"
, "contractId" : "/* the contract ID to which inputs will be applied */"
, "inputs" : "/* the inputs that will be applied to the contract */"
, "validityLowerBound" : "/* the POSIX time in integer milliseconds before which the transaction is not valid */"
, "validityUpperBound" : "/* the POSIX time in integer milliseconds after which the transaction is not valid */"
, "metadata" : "/* the transaction metadata in JSON format */"
, "addresses" : "/* the list of addresses, in addition to the change address, where UTxOs can be used as input to the transaction */"
, "change" : "/* the address to which change from the transaction will be sent */"
, "collateral" : "/* the list of UTxOs that may be used for collateral, or an empty list if any UTxO may be used for collateral */"
}

See Input in https://github.com/input-output-hk/marlowe/blob/master/isabelle/haskell/MarloweCoreJson.lhs for definition of the JSON format of inputs to a Marlowe contract.

The response is Body.

Withdraw

Build a transaction that withdraws funds paid by a Marlowe contract.

{
  "request" : "withdraw"
, "contractId" : "/* the contract ID from which funds will be withdrawn */"
, "role" : "/* the name of the role making the withdrawal */"
, "addresses" : "/* the list of addresses, in addition to the change address, where UTxOs can be used as input to the transaction */"
, "change" : "/* the address to which change from the transaction will be sent */"
, "collateral" : "/* the list of UTxOs that may be used for collateral, or an empty list if any UTxO may be used for collateral */"
}

The response is Body.

Sign

Sign a transaction body with payment keys.

DO NOT USE THIS FUNCTION TO SIGN TRANSACTIONS BECAUSE IT TRANSMITS PRIVATE (SIGNING) KEYS.

{
  "request" : "sign"
, "body" : "/* the transaction body in Cardano text-envelope format */"
, "paymentKeys" : "/* list of payment keys, in Cardano text-envelope format, that should sign the transaction */"
, "paymentExtendedKeys" : "/* a list of payment extended keys, in Cardano text-envelope format, that should sign the transaction */"
}

The response is Tx.

Submit

Submit a signed transaction to the Cardano node.

{
  "request" : "submit"
, "tx" : "/* the transaction in Cardano text-envelope format */"
}

The response is TxId.

Wait

Wait for the first confirmation of a transaction on the Cardano node.

{
  "request" : "wait"
, "txId" : "/* the identifier of the transaction */"
, "pollingSeconds" : "/* the number of seconds to wait between pollings of the Cardano node for confirmation */"
}

The response is TxInfo.

Responses

Contracts

This response is a list of contract IDs.

{
  "response" : "contracts"
, "contractIds": [
    "f06e4b760f2d9578c8088ea5289ba6276e68ae3cbaf5ad27bcfc77dc413890db#1"
   , ...
   ]
}

Result

This response is a simple true/false indication.

{
  "response" : "result"
, "result" : true
}

Info

This response details the history of a Marlowe contract.

{
  "response" : "info"
, "creation" : "/* information about the transaction that created the contract */"
, "steps" : [
    "/* information about each subsequent transaction involving the contract */"
  , ...
  ]
}

See CreateStep and ContractStep in https://github.com/input-output-hk/marlowe-cardano/blob/main/marlowe-runtime/history-api/Language/Marlowe/Runtime/History/Api.hs for details on the contents of the creation and steps fields.

Body

This response contains a serialized transaction body.

{
  "response" : "body"
, "txId" : "66e4af5ec99f09c28c6378e1d9d9508d95544e258fd8c8e7f3ff168a73e7b656"
, "contractId" : "66e4af5ec99f09c28c6378e1d9d9508d95544e258fd8c8e7f3ff168a73e7b656#1"
, "body" : "/* the JSON-serialized transaction body in Cardano text-envelope format */"
}

Tx

This response contains a serialized transaction.

{
  "response" : "tx"
, "txId" : "66e4af5ec99f09c28c6378e1d9d9508d95544e258fd8c8e7f3ff168a73e7b656"
, "tx" : "/* the JSON-serialized transaction in Cardano text-envelope format */"
}

TxId

This response contains a transaction ID.

{
  "response" : "txId"
, "txId" : "66e4af5ec99f09c28c6378e1d9d9508d95544e258fd8c8e7f3ff168a73e7b656"
}

TxInfo

This response contains full information about a transaction.

{
  "response" : "txInfo"
, "transaction" : "/* information about the transaction */"
}

See Transaction in https://github.com/input-output-hk/marlowe-cardano/blob/main/marlowe-runtime/src/Language/Marlowe/Runtime/Core/Api.hs for details on the contents of the transaction field.

Help

Marlowe Lambda

$ marlowe-lambda --help

marlowe-lambda: run a marlowe application AWS Lambda service

Usage: marlowe-lambda [--chain-seek-host HOST_NAME]
                      [--chain-seek-command-port PORT_NUMBER]
                      [--chain-seek-query-port PORT_NUMBER]
                      [--chain-seek-sync-port PORT_NUMBER]
                      [--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]
                      [--discovery-sync-port PORT_NUMBER] [--tx-host HOST_NAME]
                      [--tx-command-port PORT_NUMBER]
                      [--timeout-seconds INTEGER]

  This executable implements an AWS Lambda service for Marlowe Runtime.

Available options:
  -h,--help                Show this help text
  --chain-seek-host HOST_NAME
                           The hostname of the Marlowe Runtime chain-seek
                           server. Can be set as the environment variable
                           MARLOWE_RT_CHAINSEEK_HOST (default: "127.0.0.1")
  --chain-seek-command-port PORT_NUMBER
                           The port number of the chain-seek server's job API.
                           Can be set as the environment variable
                           MARLOWE_RT_CHAINSEEK_COMMAND_PORT (default: 3720)
  --chain-seek-query-port PORT_NUMBER
                           The port number of the chain-seek server's query API.
                           Can be set as the environment variable
                           MARLOWE_RT_CHAINSEEK_QUERY_PORT (default: 3716)
  --chain-seek-sync-port PORT_NUMBER
                           The port number of the chain-seek server's
                           synchronization API. Can be set as the environment
                           variable MARLOWE_RT_CHAINSEEK_SYNC_PORT
                           (default: 3715)
  --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)
  --discovery-sync-port PORT_NUMBER
                           The port number of the discovery server's
                           synchronization API. Can be set as the environment
                           variable MARLOWE_RT_DISCOVERY_SYNC_PORT
                           (default: 3722)
  --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: 3723)
  --timeout-seconds INTEGER
                           Time timeout in seconds for transaction confirmation.

Marlowe Pipe

The command-line tool marlowe-pipe reads JSON requests for Marlowe Runtime from standard input, services the request, and writes the JSON response to standard output.

$ marlowe-pipe --help

marlowe-pipe: run marlowe application requests

Usage: marlowe-pipe [--chain-seek-host HOST_NAME]
                    [--chain-seek-command-port PORT_NUMBER]
                    [--chain-seek-query-port PORT_NUMBER]
                    [--chain-seek-sync-port PORT_NUMBER]
                    [--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]
                    [--discovery-sync-port PORT_NUMBER] [--tx-host HOST_NAME]
                    [--tx-command-port PORT_NUMBER] [--timeout-seconds INTEGER]

  This command-line tool reads lines of JSON from standard input, interpets them
  as Marlowe App requests, executes them, and prints the response JSON on
  standard output.

Available options:
  -h,--help                Show this help text
  --chain-seek-host HOST_NAME
                           The hostname of the Marlowe Runtime chain-seek
                           server. Can be set as the environment variable
                           MARLOWE_RT_CHAINSEEK_HOST (default: "127.0.0.1")
  --chain-seek-command-port PORT_NUMBER
                           The port number of the chain-seek server's job API.
                           Can be set as the environment variable
                           MARLOWE_RT_CHAINSEEK_COMMAND_PORT (default: 3720)
  --chain-seek-query-port PORT_NUMBER
                           The port number of the chain-seek server's query API.
                           Can be set as the environment variable
                           MARLOWE_RT_CHAINSEEK_QUERY_PORT (default: 3716)
  --chain-seek-sync-port PORT_NUMBER
                           The port number of the chain-seek server's
                           synchronization API. Can be set as the environment
                           variable MARLOWE_RT_CHAINSEEK_SYNC_PORT
                           (default: 3715)
  --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)
  --discovery-sync-port PORT_NUMBER
                           The port number of the discovery server's
                           synchronization API. Can be set as the environment
                           variable MARLOWE_RT_DISCOVERY_SYNC_PORT
                           (default: 3722)
  --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: 3723)
  --timeout-seconds INTEGER
                           Time timeout in seconds for transaction confirmation.

About

A Marlowe Runtime client for AWS Lambda. This package has been deprecated and is no longer maintained. Please use https://github.com/input-output-hk/marlowe-cardano/tree/main/marlowe-runtime/web-server-app instead.

Topics

lambda runtime cardano marlowe

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

4 stars

Watchers

16 watching

Forks

0 forks
Report repository

Languages