# Cardano, Blockfrost, And CIP Reference Notes

Checked on: 2026-09-16

This note records the primary references used to make the Agora Expansion tutorial easier to follow. It is not a protocol specification; it is a reviewer-friendly map of the Cardano concepts that appear in the milestone 5 docs and tutorial website.

## Primary References

- CIP-0030 Cardano dApp-Wallet Web Bridge: https://cips.cardano.org/cip/CIP-0030
- Blockfrost getting started: https://blockfrost.dev/overview/getting-started
- Blockfrost first API call and network examples: https://blockfrost.dev/overview/making-first-call
- Blockfrost Cardano guide: https://blockfrost.dev/start-building/cardano
- Cardano native tokens: https://docs.cardano.org/developer-resources/native-tokens

## CIP-30 Wallet Bridge

CIP-30 defines the browser bridge used by Cardano dApps to communicate with wallet extensions. For this tutorial, the important reviewer-facing point is that the app does not directly control the wallet. The wallet exposes a namespaced object under `window.cardano`, asks the user for consent through `enable()`, and then provides an API for reading wallet state and requesting signatures or transaction submission.

Agora Expansion uses this concept in:

- `docs/03-frontend-blockfrost-wallet-setup.md`
- `docs/04-ui-user-tutorial.md`
- `site/index.html`

Reviewer note:

If a wallet is installed but does not appear in the UI, check that the browser extension is unlocked, available on the current browser profile, and allowed for the current site.

## Blockfrost Project IDs

Blockfrost project IDs are API credentials for a specific network. A project created for one network should be used with that same network in the frontend configuration.

Quick matching guide:

| Review network | Wallet address pattern | Frontend URL | Frontend key |
| --- | --- | --- | --- |
| Preprod | `addr_test...` | `REACT_APP_BLOCKFROST_TESTNET_URL=https://cardano-preprod.blockfrost.io/api/v0` | `REACT_APP_BLOCKFROST_TESTNET_API_KEY` |
| Mainnet | `addr1...` | `REACT_APP_BLOCKFROST_MAINNET_URL=https://cardano-mainnet.blockfrost.io/api/v0` | `REACT_APP_BLOCKFROST_MAINNET_API_KEY` |

Reviewer note:

The UI can connect a wallet before Blockfrost is configured, but asset lookup and transaction-building flows require the matching Blockfrost project ID.

## Native Assets, Policy IDs, And Asset Names

Cardano native tokens are ledger-supported assets. A native asset is identified by a policy ID and asset name. The same asset name under a different policy is a different asset.

Agora Expansion uses this in the voting-power configuration flow:

- FT or NFT selection tells the app how to treat the configured asset.
- Policy information tells the app which wallet assets are eligible.
- The configured weights tell the app how eligible assets contribute to governance voting power.

Reviewer note:

If the selected wallet has assets but the UI does not show the expected token, verify that the policy ID, asset name, and wallet network are the ones intended for the test.

## UTxOs And Asset Lookup

Cardano tracks spendable value through unspent transaction outputs. A wallet can hold ada and native tokens across multiple UTxOs. For this tutorial, the practical point is simple: the frontend must read wallet UTxOs before it can aggregate and list eligible assets.

Agora Expansion uses Blockfrost-backed Lucid calls to:

- Read wallet UTxOs.
- Aggregate visible assets.
- Populate asset-selection controls.
- Build lock/redeem transaction flows.

Reviewer note:

An empty asset dropdown can mean the wallet has no matching UTxOs, the wallet is on a different network than the Blockfrost URL, or the app was built without the needed Blockfrost settings.

## Receipt NFT Flow

In the Agora Expansion user flow, the generate path locks selected assets and mints voting power plus a receipt NFT. The receipt NFT is later selected in the redeem path to recover the locked assets.

Reviewer note:

The Playwright screenshots in this package show this user path with mocked wallet data. They are valid UI/tutorial evidence, but they are not live-chain proof. Live Preprod or Mainnet transaction evidence should be added separately if required by the reviewer.

## Evidence Boundary

Use the local tutorial website, screenshots, and generated walkthrough to explain the interface and review the expected flow. Use public explorer links only for live transaction evidence. Do not present mocked transaction hashes as live-chain proof.