Save a message on the Cardano blockchain example using Python.

hello-world.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "15a501e9",
   "metadata": {},
   "source": [
    "# Store \"Hello World\" on Cardano (Testnet)\n",
    "\n",
    "This notebook shows how to create a wallet and send a transaction that embeds the message \"Hello World\" in transaction metadata using the `cardanomsg` library (example). Replace placeholders like the Blockfrost project ID before running."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d48bbae8",
   "metadata": {},
   "source": [
    "## Get test ADA (faucet)\n",
    "\n",
    "- You need ADA on the Cardano testnet to submit transactions. Obtain test ADA from a Cardano testnet faucet. Typical steps:\n",
    "  1. Copy a receiving address from this notebook after creating the wallet.\n",
    "  2. Visit a Cardano testnet [faucet](https://docs.cardano.org/cardano-testnets/tools/faucet).\n",
    "  3. Paste the address and request test ADA; wait for confirmations before sending transactions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "3ea1b6f6",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Note: you may need to restart the kernel to use updated packages.\n"
     ]
    }
   ],
   "source": [
    "# Install libraries (run once)\n",
    "%pip install --quiet cardanomsg blockfrost-python"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2befdd04",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Blockfrost project ID placeholder set. Replace it before submitting transactions.\n"
     ]
    }
   ],
   "source": [
    "# Example imports and provider setup (replace placeholders)\n",
    "from cardanomsg.transaction import send_message, get_message, find_message\n",
    "from cardanomsg.wallet import create\n",
    "from blockfrost import BlockFrostApi, ApiUrls\n",
    "\n",
    "# Replace with your Blockfrost testnet/preview project ID\n",
    "BLOCKFROST_PROJECT_ID = \"REPLACE_WITH_YOUR_BLOCKFROST_PROJECT_ID\"\n",
    "\n",
    "# Initialize Blockfrost API (not required by send_message directly, but useful for queries)\n",
    "api = BlockFrostApi(project_id=BLOCKFROST_PROJECT_ID, base_url=ApiUrls.preview.value)\n",
    "\n",
    "print('Blockfrost project ID placeholder set. Replace it before submitting transactions.')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d5ad08c4",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "wallet.skey and wallet.addr created in current directory\n",
      "Receive address (use this for faucet): addr_test1_your_address_here\n"
     ]
    }
   ],
   "source": [
    "# Create a new wallet using cardanomsg. This writes 'wallet.skey' and 'wallet.addr' to disk.\n",
    "result = create()\n",
    "\n",
    "# Read the generated receive address from wallet.addr\n",
    "with open('wallet.addr', 'r') as f:\n",
    "    receive_address = f.read().strip()\n",
    "\n",
    "print('wallet.skey and wallet.addr created in current directory')\n",
    "print('Receive address (use this for faucet):', receive_address)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "id": "65f2b3c6",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transaction submitted. TX hash: 0dff5f343bd78dc8670f70a88993a50478371df2565ffcf95e573ead5f0d56da\n"
     ]
    }
   ],
   "source": [
    "# Send a transaction embedding 'Hello World' using cardanomsg.transaction.send_message\n",
    "# send_message(project_id, skey_path, recipient_address, lovelace_amount, payload, label=None)\n",
    "amount_lovelace = 1000000  # 1 ADA\n",
    "to_address = receive_address\n",
    "\n",
    "try:\n",
    "    tx_hash = send_message(BLOCKFROST_PROJECT_ID, 'wallet.skey', to_address, amount_lovelace, 'Hello World')\n",
    "    print('Transaction submitted. TX hash:', tx_hash)\n",
    "except Exception as e:\n",
    "    print('Send failed:', e)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "id": "db938594",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello World\n"
     ]
    }
   ],
   "source": [
    "# Fetch metadata back using get_message once tx_hash is known (may take a few minutes to index)\n",
    "msg = get_message(BLOCKFROST_PROJECT_ID, tx_hash)[0].json_metadata\n",
    "print(msg)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c8cf8242",
   "metadata": {},
   "source": [
    "## Notes and next steps\n",
    "- Replace `REPLACE_WITH_YOUR_BLOCKFROST_PROJECT_ID` with a valid Blockfrost project ID for testnet/preview and ensure `ApiUrls` value matches that environment.\n",
    "- Adjust `cardanomsg` calls to match the actual library's API names (methods like `generate_mnemonic`, `from_mnemonic`, `build_transaction`, `sign_transaction`, and `submit_transaction` were used as illustrative examples).\n",
    "- After submission, verify the metadata is present using a block explorer that supports transaction metadata (or query via Blockfrost)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}