diff --git a/website/docs/guides/_category_.yml b/website/docs/guides/_category_.yml new file mode 100644 index 0000000..1774111 --- /dev/null +++ b/website/docs/guides/_category_.yml @@ -0,0 +1,4 @@ +label: Integration Guides +position: 12 +link: + type: generated-index diff --git a/website/docs/guides/blaze-yaci-store-integration.md b/website/docs/guides/blaze-yaci-store-integration.md new file mode 100644 index 0000000..cff9d74 --- /dev/null +++ b/website/docs/guides/blaze-yaci-store-integration.md @@ -0,0 +1,149 @@ +--- +title: Blaze SDK with Yaci Store +description: "Technical guide: using Yaci Store as a local Blockfrost-compatible indexer with Blaze SDK on Cardano." +sidebar_position: 1 +--- + +# Blaze SDK with Yaci Store + +Use **Yaci Store** as a local Blockfrost-compatible indexer with **Blaze SDK**. This document describes the architecture, data flow, configuration, and typical interactions. + +## Architecture and flow + +```mermaid +sequenceDiagram + participant App as Your application + participant Blaze as Blaze SDK + participant API as Yaci Store (Blockfrost API) + participant Node as Cardano node + + App->>Blaze: e.g. getUtxos(address) + Blaze->>API: GET /addresses/{address}/utxos + API->>Node: Chain/ledger query + Node-->>API: UTXO set + API-->>Blaze: JSON response + Blaze-->>App: Parsed UTXOs + + App->>Blaze: submitTx(signedTx) + Blaze->>API: POST /tx/submit + API->>Node: Submit transaction + Node-->>API: TxId / error + API-->>Blaze: Response + Blaze-->>App: Result +``` + +- **Your app** uses the Blaze SDK (TypeScript/JavaScript). +- **Blaze SDK** talks to a Blockfrost-compatible HTTP API (base URL + optional API key). +- **Yaci Store** implements that API and reads/writes via a local **Cardano node**. + +So: **App → Blaze → Yaci Store (HTTP) → Cardano node.** No direct Blaze-to-node connection; all chain access goes through Yaci Store. + +## Prerequisites + +| Requirement | Purpose | +|-------------|---------| +| **Cardano node** | Synced (mainnet/preview/preprod). Yaci Store connects to the node. | +| **Yaci Store** | Running and exposing the Blockfrost-compatible REST API. | +| **Base URL** | Yaci Store’s Blockfrost API base URL. When run via Yaci DevKit it is **`http://localhost:8080/api/v1`** (Swagger UI: `http://localhost:8080/swagger-ui/index.html`). | + +Install and run Yaci Store (and its dependencies) per the [Yaci DevKit](https://devkit.yaci.xyz/) documentation so the Blockfrost API is enabled and reachable. Default ports: Cardano node **3001**, Yaci Store **8080**, Yaci Viewer **5173**. + +## Configuration + +Point Blaze at Yaci Store by using Blaze’s **built-in Blockfrost provider** with Yaci Store’s base URL. + +1. **Base URL** + Yaci Store exposes the Blockfrost-compatible API at **`http://localhost:8080/api/v1`** when run via [Yaci DevKit](https://devkit.yaci.xyz/getting-started/docker). Use this as the provider base URL (or your deployed Yaci Store URL + `/api/v1`). + **Note:** Yaci Store uses **`/api/v1`**; Blockfrost.io uses **`/api/v0`**. If Blaze’s Blockfrost provider assumes a path, ensure the base URL you pass results in the correct path (e.g. `http://localhost:8080/api/v1`). + +2. **API key** + Local Yaci Store typically does not require an API key. Pass an empty string or omit if the SDK allows. For deployed Yaci Store, use the key your instance expects. + +3. **Blaze setup** + Install the SDK: `npm i @blaze-cardano/sdk`. Blaze uses **`Blaze.from(provider, wallet)`** and supports Blockfrost as a built-in provider. See [Blaze docs](https://blaze.butane.dev/) and the [Blockfrost provider source](https://github.com/butaneprotocol/blaze-cardano/blob/main/packages/blaze-query/src/blockfrost.ts) for the exact constructor (e.g. base URL and API key). + +Example pattern (verify import names against [Blaze docs](https://blaze.butane.dev/) and `@blaze-cardano/sdk` exports): + +```typescript +import { Blaze, Blockfrost, ColdWallet, Core } from "@blaze-cardano/sdk"; + +// Yaci Store Blockfrost API (Yaci DevKit default) +const YACI_STORE_URL = process.env.BLOCKFROST_URL ?? "http://localhost:8080/api/v1"; +const YACI_STORE_API_KEY = process.env.BLOCKFROST_API_KEY ?? ""; + +const provider = new Blockfrost(YACI_STORE_URL, YACI_STORE_API_KEY); +const wallet = new ColdWallet(yourAddress, 0, provider); +const blaze = await Blaze.from(provider, wallet); + +// Build and submit as per Blaze docs (e.g. .newTransaction().payLovelace().complete()) +const tx = await blaze.newTransaction().payLovelace(recipient, amount).complete(); +``` + +Use environment variables so you can switch between local Yaci Store and hosted Blockfrost without code changes. + +## Interactions and API usage + +Blaze uses Blockfrost-style endpoints for chain data and submission. Yaci Store implements these; your app only talks to Blaze. + +| Interaction | Blaze (your code) | HTTP (Blaze → Yaci Store) | Purpose | +|-------------|-------------------|---------------------------|---------| +| Get UTXOs for address | e.g. `getUtxos(address)` | `GET /addresses/{address}/utxos` | Build inputs for a transaction. | +| Get transaction | e.g. `getTransaction(txHash)` | `GET /txs/{hash}` | Inspect a submitted or existing tx. | +| Submit transaction | e.g. `submitTx(signedTx)` | `POST /tx/submit` | Broadcast signed transaction. | +| Protocol parameters | e.g. `getProtocolParameters()` | `GET /epochs/latest/parameters` | Min fee, min ADA, etc. | + +Flow in practice: + +1. **Read**: Blaze calls Yaci Store (e.g. UTXOs, protocol params). Yaci Store queries the node and returns Blockfrost-shaped JSON. +2. **Build**: Your app uses Blaze to build the transaction (inputs, outputs, minting, etc.) using that data. +3. **Sign**: You sign with Blaze (or your own keys/wallet). +4. **Submit**: Blaze sends the signed CBOR to Yaci Store via `POST /tx/submit`; Yaci Store forwards to the node. + +If an endpoint or response shape differs from Blockfrost (e.g. older Blaze or custom Yaci Store version), check Blaze SDK and Yaci Store docs for compatibility. + +## End-to-end flow (summary) + +```mermaid +flowchart LR + A[Start] --> B[Run node + Yaci Store] + B --> C[Set Blaze base URL to Yaci Store] + C --> D[Read: UTXOs, params] + D --> E[Build & sign tx in Blaze] + E --> F[Submit via Blaze] + F --> G[Yaci Store forwards to node] + G --> H[Done] +``` + +1. Run Cardano node and Yaci Store; confirm the Blockfrost API is up (e.g. `GET /health` or a simple `GET /addresses/...` if available). +2. Configure Blaze with Yaci Store’s base URL (and API key if required). +3. Use Blaze for all chain reads and submission; Blaze will use Yaci Store as the Blockfrost backend. +4. Monitor node and Yaci Store logs for errors; for submission issues, confirm the node accepts the tx and that Yaci Store is not rate-limiting or returning non-standard errors. + +## Advantages of this setup + +- **Local control and privacy**: No dependency on a third-party API key or rate limits. All chain data stays between your app, Yaci Store, and your node. Useful for sensitive or high-volume workflows. +- **Same API surface**: Yaci Store is Blockfrost-compatible, so you keep the same Blaze code and can switch between local (Yaci Store) and hosted (Blockfrost) by changing the provider base URL (e.g. via env vars). No SDK rewrite. +- **Fast local dev and CI**: With Yaci DevKit you get a full devnet (node + Yaci Store) in seconds, sub-second block times, and no network latency. Ideal for automated tests and rapid iteration. +- **Cost and quotas**: No Blockfrost project limits or usage-based cost for local runs. Suits development, staging, and self-hosted production where you operate the node and indexer. +- **Ecosystem alignment**: Reuses the same Blockfrost-style APIs that other Cardano SDKs (Mesh, Lucid, PyCardano, CCL) expect, so one local indexer can serve multiple tools and docs. + +## Limitations and drawbacks + +- **Operational overhead**: You must run and maintain a Cardano node and Yaci Store (updates, disk, monitoring). If either is down, Blaze has no chain access. Heavier on CPU, RAM, and storage than using a hosted API. +- **API and CORS**: Yaci Store uses `/api/v1` while Blockfrost.io uses `/api/v0`; verify compatibility with your Blaze version. For browser apps, CORS or a proxy is required when calling self-hosted Yaci Store. + +## Compatibility notes + +- **API path**: Yaci Store serves the Blockfrost-compatible API at **`/api/v1`**; Blockfrost.io uses **`/api/v0`**. Pass the full base URL including path (e.g. `http://localhost:8080/api/v1`) so the SDK hits the correct endpoints. If Blaze’s Blockfrost provider appends a path, you may need to set the base URL to `http://localhost:8080` and confirm path compatibility with Yaci Store. +- **Network**: Use the same network (mainnet, preview, preprod) in the node, Yaci Store, and Blaze (network id / magic). +- **CORS**: For browser apps, ensure Yaci Store allows requests from your app’s origin, or run the app and Yaci Store in a way that avoids cross-origin calls (e.g. same host or proxy). + +## References + +- [Blaze Cardano](https://blaze.butane.dev/): Blaze SDK documentation and providers (Blockfrost, Kupmios, Maestro). +- [Yaci DevKit](https://devkit.yaci.xyz/): Local Cardano devnet with Yaci Store (Blockfrost API on port 8080). +- [Yaci DevKit Docker setup](https://devkit.yaci.xyz/getting-started/docker): Default ports and Yaci Store API URL (`http://localhost:8080/api/v1`). + +--- + +*This guide is part of the [Developer Experience](https://devex.intersectmbo.org/) initiative.*