lessons/01-runtime-cli/01-runtime-cli.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "caa144a8-d3d7-42de-bfdd-8b27cf4c5cbe",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "source": [
    "# Zero-Coupon Bond Using Marlowe Runtime\\'s Command-Line Interface\n",
    "\n",
    "***Before running this notebook, you might want to use Jupyter's \"clear output\" function to erase the results of the previous execution of this notebook. That will make more apparent what has been executed in the current session.***\n",
    "\n",
    "The zero-coupon bond example is a simple Marlowe contract where a lender provides principal to a borrower who repays it back with interest.\n",
    "\n",
    "In this demonsration we use Marlowe Runtime\\'s command-line interface, `marlowe-runtime-cli`, to run this contract on Cardano\\'s `preprod` public testnet. Marlowe contracts may use either addresses or role tokens for authorization: here we use addresses.\n",
    "\n",
    "[A video works through this Jupyter notebook.](https://youtu.be/pjDtuD5rimI)\n",
    "\n",
    "You can ask questions about Marlowe in [the #ask-marlowe channel on the IOG Discord](https://discord.com/channels/826816523368005654/936295815926927390) or post problems with this lesson to [the issues list for the Marlowe Starter Kit github repository](https://github.com/input-output-hk/marlowe-starter-kit/issues).\n",
    "\n",
    "In [Marlowe Playground](https://play.marlowe.iohk.io//), the contract looks like this in Blockly format.\n",
    "\n",
    "![Zero-coupon bond Marlowe contract](../../images/01-zcb-contract.png)\n",
    "\n",
    "In Marlowe format it appears as\n",
    "```\n",
    "When\n",
    "    [Case\n",
    "        (Deposit\n",
    "            (Address \"$LENDER_ADDR\")\n",
    "            (Address \"$LENDER_ADDR\")\n",
    "            (Token \"\" \"\")\n",
    "            (ConstantParam \"$PRINCIPAL\")\n",
    "        )\n",
    "        (Pay\n",
    "            (Address \"$LENDER_ADDR\")\n",
    "            (Party (Address \"$BORROWER_ADDR\"))\n",
    "            (Token \"\" \"\")\n",
    "            (ConstantParam \"$PRINCIPAL\")\n",
    "            (When\n",
    "                [Case\n",
    "                    (Deposit\n",
    "                        (Address \"$BORROWER_ADDR\")\n",
    "                        (Address \"$BORROWER_ADDR\")\n",
    "                        (Token \"\" \"\")\n",
    "                        (AddValue\n",
    "                            (ConstantParam \"$INTEREST\")\n",
    "                            (ConstantParam \"$PRINCIPAL\")\n",
    "                        )\n",
    "                    )\n",
    "                    (Pay\n",
    "                        (Address \"$BORROWER_ADDR\")\n",
    "                        (Party (Address \"$LENDER_ADDR\"))\n",
    "                        (Token \"\" \"\")\n",
    "                        (AddValue\n",
    "                            (ConstantParam \"$INTEREST\")\n",
    "                            (ConstantParam \"$PRINCIPAL\")\n",
    "                        )\n",
    "                        Close \n",
    "                    )]\n",
    "                (TimeParam \"$BORROWER_DEADLINE\")\n",
    "                Close \n",
    "            )\n",
    "        )]\n",
    "    (TimeParam \"$LENDER_DEADLINE\")\n",
    "    Close \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b94d119b-6a78-4972-83be-bede23021187",
   "metadata": {},
   "source": [
    "## Preliminaries\n",
    "\n",
    "See [Preliminaries](../../docs/preliminaries.md) for information on setting up one's environment for using this tutorial.\n",
    "\n",
    "The first step is to check we have all the required tools and environment variables available to the notebook. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "767c5145",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "export SCRIPTS=../../scripts\n",
    "export KEYS=../../keys\n",
    "source $SCRIPTS/check-tools-and-env.sh"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a8ce1b86",
   "metadata": {},
   "source": [
    "Make sure you've also [setup and funded](../../setup/01-setup-keys.ipynb) the different parties\n",
    "\n",
    "- Lender\n",
    "    - \\$KEYS/lender.address: Cardano address for the lender\n",
    "    - \\$KEYS/lender.skey: location of signing key file for the lender\n",
    "- Borrower\n",
    "    - \\$KEYS/borrower.address: Cardano address for the borrower\n",
    "    - \\$KEYS/borrower.skey: location of signing key file for the borrower"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6699e48f-cdb4-4532-9760-b080724142ef",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "source": [
    "### Lender address and funds\n",
    "\n",
    "Check that an address and key has been created for the lender. If not, see \"Creating Addresses and Signing Keys\" in [setup/01-setup-keys.ipynb](../../setup/01-setup-keys.ipynb)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c7def6b8-c617-4049-872f-4974755d0cb0",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "LENDER_SKEY=$KEYS/lender.skey\n",
    "LENDER_ADDR=$(cat $KEYS/lender.address)\n",
    "echo \"LENDER_ADDR = $LENDER_ADDR\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "31614d3b-10c1-4704-b49a-82aa924cba23",
   "metadata": {},
   "source": [
    "Check that the lender has at least one hundred ada."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "111e60bf-a7c8-41f1-b729-15d1defd27df",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "cardano-cli query utxo --testnet-magic \"$CARDANO_TESTNET_MAGIC\" --address \"$LENDER_ADDR\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1d47a97-8c70-47c8-9c80-90e6619ea37c",
   "metadata": {},
   "source": [
    "One can view the address on a Cardano explorer. It sometimes takes thirty seconds or so for the transaction to be visible in an explorer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d4eb8b9f-84a2-4fce-abec-8725dc67c46a",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "$SCRIPTS/cardano-scan-address.sh $LENDER_ADDR"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7cb22b51-b719-429d-ab8c-ef43973905a7",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "source": [
    "### Borrower address and funds\n",
    "\n",
    "Check that an address and key has been created for the borrower. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b60f9abe-4956-4783-86cf-1827bd076dfe",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "BORROWER_SKEY=$KEYS/borrower.skey\n",
    "BORROWER_ADDR=$(cat $KEYS/borrower.address)\n",
    "echo \"BORROWER_ADDR = $BORROWER_ADDR\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9d9e5126-619f-4f5b-b51b-d4b5c80b952f",
   "metadata": {},
   "source": [
    "Check that the borrower has at least one hundred ada."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a4a8216e-c5d3-4706-8ab9-918252369263",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "cardano-cli query utxo --testnet-magic \"$CARDANO_TESTNET_MAGIC\" --address \"$BORROWER_ADDR\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "038e042c-2638-415c-ad7b-de390a82416b",
   "metadata": {},
   "source": [
    "One can view the address on a Cardano explorer. It sometimes takes thirty seconds or so for the transaction to be visible in an explorer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3455b47d-45f9-4d31-aebe-ab0ea7b36aa9",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "$SCRIPTS/cardano-scan-address.sh $BORROWER_ADDR"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b0f231be-b01f-4b30-a086-a3371eda42a3",
   "metadata": {},
   "source": [
    "## Design the contract\n",
    "\n",
    "The zero-coupon bond contract can be downloaded from the [Marlowe Playground](https://play.marlowe.iohk.io//) as a JSON file, or it can be generated using [Marlowe CLI](https://github.com/input-output-hk/marlowe-cardano/tree/main/marlowe-cli#readme) using the `marlowe-cli template` command.\n",
    "\n",
    "Here we generate the contract using Marlowe CLI.\n",
    "\n",
    "First, set the loan's principal to 80 ada and its interest to 5 ada."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4c959ebc-7c73-49ef-a1f9-a32771cc9ec9",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "ADA=1000000  # 1 ada = 1,000,000 lovelace\n",
    "\n",
    "PRINCIPAL=$((80 * ADA))\n",
    "INTEREST=$((5 * ADA))\n",
    "\n",
    "echo \"PRINCIPAL = $PRINCIPAL lovelace\"\n",
    "echo \"INTEREST = $INTEREST lovelace\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ca6f1da3-5a16-4dc4-a310-90812c4936b6",
   "metadata": {},
   "source": [
    "On the Cardano blockchain, the protocol parameters require that each UTxO contain at least some ada. Here we will start the contract with 2 ada."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "aa229f08-6907-4f7b-b458-5fd18e0b9596",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "MIN_LOVELACE=\"$((2 * ADA))\"\n",
    "echo \"MIN_LOVELACE = $MIN_LOVELACE lovelace\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a65904b-e1eb-4185-a973-dd1ba3a3e93a",
   "metadata": {},
   "source": [
    "Next find the current time, measured in [POSIX milliseconds](https://en.wikipedia.org/wiki/Unix_time)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "30ec2929-27e1-4ae7-8ee0-82e710f15b6c",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "SECOND=1000 # 1 second = 1000 milliseconds\n",
    "MINUTE=$((60 * SECOND)) # 1 minute = 60 seconds\n",
    "HOUR=$((60 * MINUTE)) # 1 hour = 60 minutes\n",
    "\n",
    "NOW=\"$((`date -u +%s` * SECOND))\"\n",
    "echo NOW = \"$NOW\" POSIX milliseconds = \"`date -d @$((NOW / SECOND))`\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4806318e-46e9-4c17-88b7-966098d25771",
   "metadata": {},
   "source": [
    "The contract has a lending deadline and a repayment deadline. For convenience in this example, set the deadlines to the near future."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2ac3ad1d-060f-4ff5-b055-c96011f724a0",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "LENDER_DEADLINE=\"$((NOW + 1 * HOUR))\"\n",
    "BORROWER_DEADLINE=\"$((NOW + 3 * HOUR))\"\n",
    "echo LENDER_DEADLINE = \"$LENDER_DEADLINE\" POSIX milliseconds = \"`date -d @$((LENDER_DEADLINE / SECOND))`\"\n",
    "echo BORROWER_DEADLINE = \"$BORROWER_DEADLINE\" POSIX milliseconds = \"`date -d @$((BORROWER_DEADLINE / SECOND))`\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56db086f-bba1-40ba-94a3-aa9a7f9a3e45",
   "metadata": {},
   "source": [
    "Now create the JSON file for the contract, `zcb-contract.json`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5b4b87af-265c-4d2c-bfe3-281614311fa8",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "# Create the contract and initial state\n",
    "marlowe-cli template zcb \\\n",
    "  --minimum-ada \"$MIN_LOVELACE\" \\\n",
    "  --lender \"$LENDER_ADDR\" \\\n",
    "  --borrower \"$BORROWER_ADDR\" \\\n",
    "  --principal \"$PRINCIPAL\" \\\n",
    "  --interest \"$INTEREST\" \\\n",
    "  --lending-deadline \"$LENDER_DEADLINE\" \\\n",
    "  --repayment-deadline \"$BORROWER_DEADLINE\" \\\n",
    "  --out-contract-file zcb-contract.json \\\n",
    "  --out-state-file zcb-state.json\n",
    "\n",
    "# Show the size of the files\n",
    "du -hs zcb-contract.json zcb-state.json"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "29c63a36-8cd9-4ee4-893c-f77a2ea15a4a",
   "metadata": {},
   "source": [
    "The various command-line options are described by the help system."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "36d8e09d-b426-4889-91f8-3a6842f9727b",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "marlowe-cli template zcb --help"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a1f0813f-86ae-4209-9a78-cd533fca9857",
   "metadata": {},
   "source": [
    "## Examine the contract\n",
    "\n",
    "View the contract file as YAML."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "112824a7-635f-4134-b133-a20e63660b35",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "json2yaml zcb-contract.json"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d3f9edcd-5f91-4739-bdb4-02a14c9acdc0",
   "metadata": {},
   "source": [
    "Also view the initial state of the contract. Note that Marlowe Runtime overrides this with a state that it builds."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "34308675-6e14-4dfc-acb8-247c4add03c9",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "json2yaml zcb-state.json"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "00f357bf-ebf0-4459-adb9-32c5a1140759",
   "metadata": {
    "tags": []
   },
   "source": [
    "### \\[Optional, but recommended\\] Check the safety of the contract\n",
    "\n",
    "If we were running the contract on the Cardano `mainnet`, then we\\'d want to check its safety before creating it, so that there is no chance that we might lose funds.\n",
    "\n",
    "Here are the steps for checking the safety of a contract:\n",
    "\n",
    "1. Understand the [Marlowe Language](https://marlowe.iohk.io/).\n",
    "2. Understand Cardano\\'s [Extended UTxO Model](https://docs.cardano.org/learn/eutxo-explainer).\n",
    "3. Read and understand the [Marlowe Best Practices Guide](https://github.com/input-output-hk/marlowe-cardano/blob/main/marlowe/best-practices.md).\n",
    "4. Read and understand the [Marlowe Security Guide](https://github.com/input-output-hk/marlowe-cardano/blob/main/marlowe/security.md).\n",
    "5. Use [Marlowe Playground](https://play.marlowe.iohk.io//) to flag warnings, perform static analysis, and simulate the contract.\n",
    "6. Use [Marlowe CLI\\'s](https://github.com/input-output-hk/marlowe-cardano/blob/main/marlowe-cli/ReadMe.md) `marlowe-cli run analyze` tool to study whether the contract can run on a Cardano network.\n",
    "7. Run *all execution paths* of the contract on a [Cardano testnet](https://docs.cardano.org/cardano-testnet/overview).\n",
    "\n",
    "Here we\\'ll perform step 6. First we bundle the contract and its initial state into a single file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f2c5f0ad-8c56-486a-9107-8abfa61ab68f",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "# Create the contract and bundle\n",
    "marlowe-cli run initialize \\\n",
    "  --permanently-without-staking \\\n",
    "  --contract-file zcb-contract.json \\\n",
    "  --state-file zcb-state.json \\\n",
    "  --out-file zcb-marlowe.json\n",
    "  \n",
    "# Show its size\n",
    "du -hs zcb-marlowe.json"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f86ee195-d7a0-4e2e-8cc6-0155112f9c56",
   "metadata": {},
   "source": [
    "Now we analyze the contract and its execution paths."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bb0789a1-3e56-4e5a-91aa-33417e957c9f",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "marlowe-cli run analyze \\\n",
    "  --marlowe-file zcb-marlowe.json"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2eae4910-05cf-4eca-ad15-be285ee3c782",
   "metadata": {},
   "source": [
    "In the above report, we see that the contract doesn\\'t have any duplicate or invalid values, and it does not exceed any of the blockchain\\'s protocol parameters. In particular, note that our previously chosen `MIN_LOVELACE` value of 2 ada is greater than the 1.120600 ada that the analysis tool says is needed. Thus, it is safe to execute any path in the contract."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fcbdcc02-7ffe-46a4-8732-10a3e7b93865",
   "metadata": {},
   "source": [
    "## Transaction 1. Create the Contract"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6fad0f1b-a918-4c56-867e-29600be217f4",
   "metadata": {},
   "source": [
    "Marlowe Runtime\\'s command `marlowe-runtime-cli create` will build the creation transaction for a Marlowe contract. We provide it the JSON file containing the contract and tell it the `MIN_LOVELACE` value that we previously chose. Anyone could create the contract, but in this example the lender will be doing so, so we provide their address to fund the transaction and to receive the change from it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "87672246-de07-4356-8cee-3692eeb36572",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "marlowe-runtime-cli create --help"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f8c85b72-afe2-460c-a48a-6e347ace520c",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "CONTRACT_ID=$(\n",
    "marlowe-runtime-cli create \\\n",
    "  --core-file zcb-contract.json \\\n",
    "  --min-utxo \"$MIN_LOVELACE\" \\\n",
    "  --change-address \"$LENDER_ADDR\" \\\n",
    "  --manual-sign tx-1.unsigned \\\n",
    "| jq -r 'fromjson | .contractId' \\\n",
    ")\n",
    "echo \"CONTRACT_ID = $CONTRACT_ID\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fb633e68-7177-44ac-a46b-009539093419",
   "metadata": {},
   "source": [
    "Marlowe Runtime uses the first (creation) UTxO of the contract to identify it throughout its lifecycle.\n",
    "\n",
    "The result of building the transaction is the identifier for the contract and the file `tx-1.unsigned`, which contains the Cardano unsigned transaction for creating the contract, in text-envelope format."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "43ddbc79-cc07-45e6-9266-aac7447b7fe3",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "json2yaml tx-1.unsigned"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1f0d00de-4fd7-41bd-a933-170de9ef2688",
   "metadata": {},
   "source": [
    "There are many ways to sign and submit Cardano transactions:\n",
    "- `cardano-cli` at the command line\n",
    "- `cardano-wallet` at the command line or as a REST service\n",
    "- `cardano-hw-cli` for a hardware wallet at the command line\n",
    "- a Babbage-compatible CIP-30 wallet in a web browser\n",
    "- `marlowe-cli` at the command line\n",
    "- `marlowe-runtime-cli submit` at the command line (requires signing by a separate tool such as `cardano-cli`)\n",
    "\n",
    "For convenience, here we use `marlowe-cli transaction submit`. One may have to wait a minute or so for the transactions to be confirmed on the blockchain."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ae1f6a5f-b4f7-452f-9d1b-f0545135deb5",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "echo \"submiting transaction...\"\n",
    "TX_1=$(\n",
    "marlowe-cli transaction submit \\\n",
    "  --tx-body-file tx-1.unsigned \\\n",
    "  --required-signer \"$LENDER_SKEY\" \\\n",
    "  --timeout 600s \\\n",
    "| sed -e 's/^TxId \"\\(.*\\)\"$/\\1/' \\\n",
    ")\n",
    "echo \"TX_1 = $TX_1\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa349a31-4e44-42c9-8c3d-e910f195325d",
   "metadata": {},
   "source": [
    "One can view the transaction on a Cardano and Marlowe explorer. It sometimes takes thirty seconds or so for the transaction to be visible in an explorer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "72115506-5bfd-480f-b3f0-47520dca84c1",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "echo \"Cardano Scan (low level)\"\n",
    "$SCRIPTS/cardano-scan-tx.sh $TX_1\n",
    "echo\n",
    "echo \"Marlowe Scan (high level)\"\n",
    "$SCRIPTS/marlowe-scan.sh $CONTRACT_ID"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3b3dae70-a556-4621-bab9-fd92b9f165eb",
   "metadata": {},
   "source": [
    "One can also examine the contract's UTxO using `cardano-cli`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c4af1000-9220-4f31-92e8-ee5eb405df0b",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "cardano-cli query utxo --testnet-magic \"$CARDANO_TESTNET_MAGIC\" --tx-in \"$TX_1#1\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c42fef94-fbf9-4208-90c3-3f93a2eb5290",
   "metadata": {},
   "source": [
    "## View the details of the contract on the blockchain\n",
    "\n",
    "Marlowe Runtime\\'s command `marlowe-runtime-cli log` can fetch a contract from the blockchain and print information about it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a753938c-92bb-43aa-bb13-d09a112939c6",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "marlowe-runtime-cli log --show-contract \"$CONTRACT_ID\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d44441bd-5679-498a-a4f0-156b7087a2b9",
   "metadata": {},
   "source": [
    "More detail can be retrieved using `marlowe-pipe`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2ea93a41-ad4a-4040-842a-6c2eec4ba4ae",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "echo '{\"request\" : \"get\", \"contractId\" : \"'\"$CONTRACT_ID\"'\"}' | marlowe-pipe 2> /dev/null | json2yaml"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd4fa3da-0f75-4b96-a911-0ba5bea722f8",
   "metadata": {},
   "source": [
    "## Transaction 2. The lender deposits the principal\n",
    "\n",
    "The lender deposits their 80 ada of principal into the contract using Marlowe Runtime\\'s `marlowe-runtime-cli deposit` command. The lender is providing the funding for and receiving the change from this transaction, so we provide their address. We provide the contract identifier and save the unsigned transaction in the file `tx-2.unsigned`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bf42d7d0-be81-42a1-8da7-5ff07b9611ee",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "marlowe-runtime-cli deposit --help"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "96e0b7b9-4816-46d3-ad2c-580dd7547b07",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "TX_2=$(\n",
    "marlowe-runtime-cli deposit \\\n",
    "  --contract \"$CONTRACT_ID\" \\\n",
    "  --from-party \"$LENDER_ADDR\" \\\n",
    "  --to-party \"$LENDER_ADDR\" \\\n",
    "  --lovelace \"$PRINCIPAL\" \\\n",
    "  --change-address \"$LENDER_ADDR\" \\\n",
    "  --manual-sign tx-2.unsigned \\\n",
    "| jq -r 'fromjson | .txId' \\\n",
    ")\n",
    "echo \"TX_2 = $TX_2\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d888ede9-b756-4ab4-bd8a-f9090870d8ca",
   "metadata": {},
   "source": [
    "Note that if the transaction would violate the logic of the Marlowe contract, one would receive an error message. For example, let\\'s say that we deposit the incorrect amount or deposit it to the wrong party\\'s internal account."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "28c51136-8e5a-483b-891a-e9345f1a6be5",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "marlowe-runtime-cli deposit \\\n",
    "  --contract \"$CONTRACT_ID\" \\\n",
    "  --from-party \"$LENDER_ADDR\" \\\n",
    "  --to-party \"$LENDER_ADDR\" \\\n",
    "  --lovelace 80 \\\n",
    "  --change-address \"$LENDER_ADDR\" \\\n",
    "  --manual-sign /dev/null"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ab45188c-ab07-4918-96f2-79da42ab92f8",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "marlowe-runtime-cli deposit \\\n",
    "  --contract \"$CONTRACT_ID\" \\\n",
    "  --from-party \"$LENDER_ADDR\" \\\n",
    "  --to-party \"$BORROWER_ADDR\" \\\n",
    "  --lovelace \"$PRINCIPAL\"\\\n",
    "  --change-address \"$LENDER_ADDR\" \\\n",
    "  --manual-sign /dev/null"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a75dc0f2-9be5-4f3c-bce4-ec902063967d",
   "metadata": {},
   "source": [
    "The [Marlowe Debugging Cookbook](https://github.com/input-output-hk/marlowe-cardano/blob/main/marlowe/debugging-cookbook.md) guides interpretation of error messages. Also, one can determine the possible actions for the contract at its current stage of execution by studing the contract\\'s current state or by using Marlowe playground to simulate the contract.\n",
    "\n",
    "![Simulation of zero-coupon bond contract in Marlowe Playground](../../images/zcb-simulation.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "877807a1-7e62-4258-8d3c-b82664821dc9",
   "metadata": {},
   "source": [
    "Once again, use `marlowe-cli` to submit the transaction and then wait for confirmation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bb1b0e65-3cf7-42e1-9495-ce45007e331a",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "echo \"submiting transaction...\"\n",
    "marlowe-cli transaction submit \\\n",
    "  --tx-body-file tx-2.unsigned \\\n",
    "  --required-signer \"$LENDER_SKEY\" \\\n",
    "  --timeout 600s"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eed6b35f-7aa9-4266-98d2-ac7320ccaf69",
   "metadata": {},
   "source": [
    "One can view the transaction on a Cardano explorer. It sometimes takes thirty seconds or so for the transaction to be visible in an explorer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bb813544-092a-4831-bff5-5ea7ce8a9259",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "echo \"Cardano Scan (low level)\"\n",
    "$SCRIPTS/cardano-scan-tx.sh $TX_2\n",
    "echo\n",
    "echo \"Marlowe Scan (high level)\"\n",
    "$SCRIPTS/marlowe-scan.sh $CONTRACT_ID"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "44cd316b-d4db-4d2b-87a7-eb38b95f5fb3",
   "metadata": {},
   "source": [
    "One can see that the lender has 82 ada less than originally. Two ada were deposited in the contract when it was created and 80 ada were paid to the borrower in the second transaction."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b45dc15d-f54f-49cb-a36d-0524f47fd70e",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "echo \"Lender:\"\n",
    "$SCRIPTS/cardano-scan-address.sh $LENDER_ADDR\n",
    "echo\n",
    "cardano-cli query utxo --testnet-magic \"$CARDANO_TESTNET_MAGIC\" --address \"$LENDER_ADDR\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8538b320-c3d6-45cb-88f7-aab77f77b78b",
   "metadata": {},
   "source": [
    "The borrower has an additional 80 ada (the loan's principal) now."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "304baf28-2a07-4ca7-8576-c10c8a960fcd",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "echo \"Borrower:\"\n",
    "$SCRIPTS/cardano-scan-address.sh $BORROWER_ADDR\n",
    "echo\n",
    "cardano-cli query utxo --testnet-magic \"$CARDANO_TESTNET_MAGIC\" --address \"$BORROWER_ADDR\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "369f3945-299b-41dd-9cbf-f3864002b6aa",
   "metadata": {},
   "source": [
    "The Marlowe contract still has the 2 ada from its creation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6485d605-dec4-4bab-86f6-81bf002041ed",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "cardano-cli query utxo --testnet-magic \"$CARDANO_TESTNET_MAGIC\" --tx-in \"$TX_2#1\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3eb0d02e-c30c-4845-86b5-602c2279b518",
   "metadata": {},
   "source": [
    "## View the further progress of the contract on the blockchain\n",
    "\n",
    "Marlowe Runtime\\'s command `marlowe-runtime-cli log` can fetch a contract from the blockchain and print information about it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e0461725-7f2b-4256-ac83-8e681ecb3e35",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "marlowe-runtime-cli log --show-contract \"$CONTRACT_ID\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "488eb566-c1d7-49a5-91bd-09922aa8493c",
   "metadata": {},
   "source": [
    "More detail can be retrieved using `marlowe-pipe`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d373efd1-9947-4ce9-837e-ba0796d89146",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "echo '{\"request\" : \"get\", \"contractId\" : \"'\"$CONTRACT_ID\"'\"}' | marlowe-pipe 2> /dev/null | json2yaml"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9f233f15",
   "metadata": {},
   "source": [
    "Or via the Marlowe SCAN"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "075211f6",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "$SCRIPTS/marlowe-scan.sh $CONTRACT_ID"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e7c652f6-02da-4786-a54d-755d59e4aba9",
   "metadata": {},
   "source": [
    "## Transaction 3. The borrower repays the loan\n",
    "\n",
    "After some time passes, the borrower repays principal plus interest. Thus, they fund the transaction and receive the change at their address."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9756dcb3-a357-4b7d-b132-9c85105f0387",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "TX_3=$(\n",
    "marlowe-runtime-cli deposit \\\n",
    "  --contract \"$CONTRACT_ID\" \\\n",
    "  --from-party \"$BORROWER_ADDR\" \\\n",
    "  --to-party \"$BORROWER_ADDR\" \\\n",
    "  --lovelace \"$((PRINCIPAL+INTEREST))\" \\\n",
    "  --change-address \"$BORROWER_ADDR\" \\\n",
    "  --manual-sign tx-3.unsigned \\\n",
    "| jq -r 'fromjson | .txId' \\\n",
    ")\n",
    "echo \"TX_3 = $TX_3\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ccdcc822-ba62-41cb-bde1-55bfc661ce16",
   "metadata": {},
   "source": [
    "Once again, use `marlowe-cli` to submit the transaction and then wait for confirmation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5fa86263-3fde-4995-be45-9625cbb35237",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "echo \"submiting transaction...\"\n",
    "marlowe-cli transaction submit \\\n",
    "  --tx-body-file tx-3.unsigned \\\n",
    "  --required-signer \"$BORROWER_SKEY\" \\\n",
    "  --timeout 600s"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3ef67b53-b30a-4408-a43e-97f1f0715ed0",
   "metadata": {},
   "source": [
    "One can view the transaction on the Cardano or Marlowe explorer. It sometimes takes thirty seconds or so for the transaction to be visible in an explorer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "94e9f529-529b-4777-b829-dcab0a5fc3b8",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "echo \"Cardano Scan (low level)\"\n",
    "$SCRIPTS/cardano-scan-tx.sh $TX_3\n",
    "echo\n",
    "echo \"Marlowe Scan (high level)\"\n",
    "$SCRIPTS/marlowe-scan.sh $CONTRACT_ID"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "af13b1f3-d5e2-4ebc-8023-f0fd5875c0a5",
   "metadata": {},
   "source": [
    "One can see that the lender received back the 80 ada of principal and the 2 ada deposited when the contract was created, along with the additional 5 ada of interest, totallying 87 ada."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "492de5e8-7f07-437c-9f88-80ccdf00636f",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "echo \"Lender:\"\n",
    "$SCRIPTS/cardano-scan-address.sh $LENDER_ADDR\n",
    "echo\n",
    "cardano-cli query utxo --testnet-magic \"$CARDANO_TESTNET_MAGIC\" --address \"$LENDER_ADDR\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1196c641-e92e-4848-a20b-b673d7fcbc71",
   "metadata": {},
   "source": [
    "The borrower now has about 5 ada (the loan's interest) less than originally."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3e8f27e3-e94a-4332-94a2-2f8af8800d56",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "echo \"Borrower:\"\n",
    "$SCRIPTS/cardano-scan-address.sh $BORROWER_ADDR\n",
    "echo\n",
    "cardano-cli query utxo --testnet-magic \"$CARDANO_TESTNET_MAGIC\" --address \"$BORROWER_ADDR\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8b4951f7-58bb-4399-a09a-2029f4e2dfe4",
   "metadata": {},
   "source": [
    "The Marlowe contract has closed, so there is no output to its script address."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Bash with Marlowe Tools",
   "language": "bash",
   "name": "bash-minimal"
  },
  "language_info": {
   "codemirror_mode": "shell",
   "file_extension": ".sh",
   "mimetype": "text/x-sh",
   "name": "bash"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}