From ae9a68176e0b036af33e87833174e3a72098974a Mon Sep 17 00:00:00 2001 From: danbaruka <46156791+danbaruka@users.noreply.github.com> Date: Mon, 16 Mar 2026 10:43:17 +0400 Subject: [PATCH 1/3] chore(deps): update package-lock and yarn.lock for dependency version bumps --- website/docs/guides/_category_.yml | 4 + .../guides/blaze-yaci-store-integration.md | 136 ++++++++++++++++++ 2 files changed, 140 insertions(+) create mode 100644 website/docs/guides/_category_.yml create mode 100644 website/docs/guides/blaze-yaci-store-integration.md 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..f056af9 --- /dev/null +++ b/website/docs/guides/blaze-yaci-store-integration.md @@ -0,0 +1,136 @@ +--- +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–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. + +## 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.* From a6082ed0795930307429f75af751b7d2b4a48e81 Mon Sep 17 00:00:00 2001 From: danbaruka <46156791+danbaruka@users.noreply.github.com> Date: Mon, 16 Mar 2026 10:49:36 +0400 Subject: [PATCH 2/3] docs: update Blaze SDK with Yaci Store integration guide - Revised description for clarity and consistency. - Improved explanation of the integration flow between Blaze SDK, Yaci Store, and Cardano node. - Added sections on advantages and limitations of using Yaci Store as a local Blockfrost-compatible indexer. - Updated references formatting for better readability. --- .../guides/blaze-yaci-store-integration.md | 23 +++++++++++++++---- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/website/docs/guides/blaze-yaci-store-integration.md b/website/docs/guides/blaze-yaci-store-integration.md index f056af9..cff9d74 100644 --- a/website/docs/guides/blaze-yaci-store-integration.md +++ b/website/docs/guides/blaze-yaci-store-integration.md @@ -1,6 +1,6 @@ --- title: Blaze SDK with Yaci Store -description: Technical guide — using Yaci Store as a local Blockfrost-compatible indexer with Blaze SDK on Cardano. +description: "Technical guide: using Yaci Store as a local Blockfrost-compatible indexer with Blaze SDK on Cardano." sidebar_position: 1 --- @@ -36,7 +36,7 @@ sequenceDiagram - **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–node connection; all chain access goes through Yaci Store. +So: **App → Blaze → Yaci Store (HTTP) → Cardano node.** No direct Blaze-to-node connection; all chain access goes through Yaci Store. ## Prerequisites @@ -119,6 +119,19 @@ flowchart LR 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. @@ -127,9 +140,9 @@ flowchart LR ## 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`). +- [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`). --- From e1db998eb854813de858d52774178a5eb2a1a776 Mon Sep 17 00:00:00 2001 From: danbaruka <46156791+danbaruka@users.noreply.github.com> Date: Thu, 2 Apr 2026 19:14:39 +0400 Subject: [PATCH 3/3] docs: enhance Blaze SDK + Yaci DevKit integration guide - Updated title and description for clarity and accuracy. - Revised integration flow explanation to emphasize the use of Yaci DevKit. - Added details on Yaci Store's operational modes for transaction submission. - Clarified prerequisites and configuration instructions for better user guidance. --- .claude/worktrees/amazing-mendel | 1 + .../guides/blaze-yaci-store-integration.md | 121 +++++++++++------- 2 files changed, 74 insertions(+), 48 deletions(-) create mode 160000 .claude/worktrees/amazing-mendel diff --git a/.claude/worktrees/amazing-mendel b/.claude/worktrees/amazing-mendel new file mode 160000 index 0000000..b6bac04 --- /dev/null +++ b/.claude/worktrees/amazing-mendel @@ -0,0 +1 @@ +Subproject commit b6bac040c4ede6b797ec03de1e43244c8e10f4dd diff --git a/website/docs/guides/blaze-yaci-store-integration.md b/website/docs/guides/blaze-yaci-store-integration.md index cff9d74..8cf8e2e 100644 --- a/website/docs/guides/blaze-yaci-store-integration.md +++ b/website/docs/guides/blaze-yaci-store-integration.md @@ -1,12 +1,12 @@ --- -title: Blaze SDK with Yaci Store -description: "Technical guide: using Yaci Store as a local Blockfrost-compatible indexer with Blaze SDK on Cardano." +title: Blaze SDK + Yaci DevKit +description: "Technical guide: using Yaci Store’s Blockfrost-compatible API from the Blaze SDK, with Yaci DevKit for local development." sidebar_position: 1 --- -# Blaze SDK with Yaci Store +# Blaze SDK + Yaci DevKit -Use **Yaci Store** as a local Blockfrost-compatible indexer with **Blaze SDK**. This document describes the architecture, data flow, configuration, and typical interactions. +Use **Yaci DevKit** to run **Yaci Store** locally and point the **Blaze SDK** at its **Blockfrost-compatible REST API**. This guide covers architecture, how reads and transaction submission work, configuration, and a typical end-to-end flow. ## Architecture and flow @@ -15,63 +15,87 @@ sequenceDiagram participant App as Your application participant Blaze as Blaze SDK participant API as Yaci Store (Blockfrost API) + participant DB as Yaci Store DB (RDBMS) 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->>DB: Read indexed UTXOs + DB-->>API: Rows API-->>Blaze: JSON response Blaze-->>App: Parsed UTXOs + Note over API,Node: Yaci Store syncs blocks from the node (ChainSync) and keeps the DB updated. + App->>Blaze: submitTx(signedTx) Blaze->>API: POST /tx/submit - API->>Node: Submit transaction + API->>Node: Forward tx (Ogmios, submit-api, or N2C — see below) Node-->>API: TxId / error API-->>Blaze: Response Blaze-->>App: Result ``` +For API requests that fetch UTXOs for an address, **Yaci Store serves the data from its database** rather than querying the Cardano node on every request. + +**Yaci Store** continuously syncs blocks from the Cardano node using the **ChainSync** mini-protocol and stores the processed data in its database. API endpoints then read that data directly from the **RDBMS**. + +For **transaction submission**, Yaci Store operates in **one of three modes** depending on configuration. The HTTP URL for your app stays the same (for example `POST .../tx/submit`). + +- **Ogmios:** If Ogmios is deployed with the Cardano node, Yaci Store submits transactions through Ogmios. In this mode, Yaci Store also enables the **evaluate** endpoint for script cost evaluation. +- **Submit API:** You can run the **submit-api** module with the node; submission goes through that server. +- **Direct to Cardano node:** This uses **N2C** configuration and normally requires a local node. If the node’s N2C socket is reachable remotely (for example via a TCP proxy such as **socat**), Yaci Store can connect that way. + +**FYI:** **Yaci DevKit** (typical for local development) bundles **Ogmios** and **Submit API**, so you do not need to install them separately for DevKit flows. A **standalone Yaci Store** deployment does **not** include Ogmios or Submit API by default. + +Yaci Store can sync blocks from a **remote** Cardano node or public endpoints, so a **local** node is not strictly required for every standalone deployment—but submission still needs one of the modes above configured to reach a node that accepts transactions. + - **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**. +- **Blaze SDK** calls a Blockfrost-style HTTP API (base URL + optional API key header). +- **Reads** are served from Yaci Store’s index; **submission** is forwarded to the node according to the active mode. -So: **App → Blaze → Yaci Store (HTTP) → Cardano node.** No direct Blaze-to-node connection; all chain access goes through Yaci Store. +So: **App → Blaze → Yaci Store (HTTP)** for queries; **submission** is **App → Blaze → Yaci Store → (Ogmios / submit-api / N2C) → node** as configured. ## Prerequisites | Requirement | Purpose | |-------------|---------| -| **Cardano node** | Synced (mainnet/preview/preprod). Yaci Store connects to the node. | +| **Cardano node** | Source of chain data via ChainSync; required for syncing (can be remote). Needed for tx submission in all modes. | | **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`). | +| **Base URL** | Yaci Store’s Blockfrost API base URL. With Yaci DevKit defaults: **`http://localhost:8080/api/v1/`** (trailing slash recommended; see [Configuration](#configuration)). 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**. +Install and run Yaci DevKit 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**. + +For deeper Yaci Store behavior (stores, DB, deployment), see [Yaci Store documentation](https://store.yaci.xyz/). ## Configuration -Point Blaze at Yaci Store by using Blaze’s **built-in Blockfrost provider** with Yaci Store’s base URL. +Point Blaze at Yaci Store using Blaze’s **Blockfrost provider**. The provider builds request URLs as **`${baseUrl}${path}`** where `path` values look like `epochs/latest/parameters` (no leading slash). Hosted Blockfrost therefore uses a base URL ending in **`/api/v0/`**. For Yaci Store, use the same pattern with **`/api/v1/`** and a **trailing slash** so paths concatenate correctly. 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`). + With [Yaci DevKit Docker](https://devkit.yaci.xyz/getting-started/docker), the Blockfrost-compatible API is at **`http://localhost:8080/api/v1/`**. Use that as the provider base (or your deployed URL + `/api/v1/` **with** a trailing slash). + **Note:** Yaci Store uses **`/api/v1/`**; Blockfrost.io uses **`/api/v0/`**. 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. + Local Yaci Store often does not require an API key. Pass an empty `projectId` if unused. For locked-down deployments, use the key your instance expects in the `project_id` header. 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). + Install: `npm i @blaze-cardano/sdk`. Blaze uses **`Blaze.from(provider, wallet)`** with the **Blockfrost** provider type. The published `Blockfrost` constructor takes **`{ network, projectId }`** and defaults to hosted Blockfrost URLs; for Yaci Store, set the public **`url`** field after construction so requests go to your indexer. See [Blaze](https://blaze.butane.dev/) and the [Blockfrost provider source](https://github.com/butaneprotocol/blaze-cardano/blob/main/packages/blaze-query/src/blockfrost.ts). -Example pattern (verify import names against [Blaze docs](https://blaze.butane.dev/) and `@blaze-cardano/sdk` exports): +Example pattern (confirm `network` matches your devnet addresses and magic; DevKit is usually testnet-style): ```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 ?? ""; +// Trailing slash: Blaze concatenates base + "epochs/latest/parameters", etc. +const YACI_STORE_BASE = + process.env.BLOCKFROST_URL ?? "http://localhost:8080/api/v1/"; + +const provider = new Blockfrost({ + network: "cardano-preview", // or cardano-preprod / "unknown" — match your devnet + projectId: process.env.BLOCKFROST_API_KEY ?? "", +}); +provider.url = YACI_STORE_BASE; -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); @@ -79,11 +103,11 @@ const blaze = await Blaze.from(provider, wallet); 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. +Use environment variables so you can switch between local Yaci Store and hosted Blockfrost without code changes (hosted: you can omit `provider.url` override and rely on the default Blockfrost host for your `network`). ## Interactions and API usage -Blaze uses Blockfrost-style endpoints for chain data and submission. Yaci Store implements these; your app only talks to Blaze. +Blaze uses Blockfrost-style endpoints for chain data and submission. Yaci Store implements these; your app talks to Blaze only. | Interaction | Blaze (your code) | HTTP (Blaze → Yaci Store) | Purpose | |-------------|-------------------|---------------------------|---------| @@ -94,55 +118,56 @@ Blaze uses Blockfrost-style endpoints for chain data and submission. Yaci Store 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. +1. **Read:** Blaze calls Yaci Store (e.g. UTXOs, protocol params). Yaci Store answers from its indexed database (kept in sync with the node). +2. **Build:** Your app uses Blaze to assemble the transaction. +3. **Sign:** You sign with Blaze or your wallet/keys. +4. **Submit:** Blaze sends the signed CBOR to Yaci Store via `POST /tx/submit`; Yaci Store forwards to the node using the configured submission mode. -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. +If an endpoint or response shape differs from Blockfrost for your Yaci Store version, check Blaze and [Yaci Store](https://store.yaci.xyz/) docs for compatibility. ## End-to-end flow (summary) ```mermaid flowchart LR - A[Start] --> B[Run node + Yaci Store] + A[Start] --> B[Run DevKit: 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] + F --> G[Yaci Store forwards per submission mode] 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. +1. **Yaci DevKit:** Start containers and CLI: `devkit start` (curl install) or `./devkit.sh start` (zip install). In the Yaci CLI, create and start a devnet, for example: `create-node -o --start` (default ~1s block time). See [Docker setup](https://devkit.yaci.xyz/getting-started/docker) for options and ports. +2. Confirm the Blockfrost API is up: try **`GET http://localhost:8080/api/v1/health`** (Blockfrost-style health, if enabled in your build), **`GET`** a simple resource such as **`/addresses/{addr}/utxos`**, or open **`http://localhost:8080/swagger-ui/index.html`**. +3. Configure Blaze with Yaci Store’s base URL (**with trailing slash**) and API key if required. +4. Use Blaze for reads and submission; monitor DevKit / Yaci Store / node logs if submission fails. ## 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. +- **Local control and privacy**: No third-party API key or quota for local DevKit. Data flows between your app, Yaci Store, and your devnet node. +- **Same API surface**: Blockfrost-compatible API lets you reuse patterns from other SDKs; switch environments via base URL and env vars. +- **Fast local dev and CI**: DevKit brings up node + indexer quickly, with configurable block times. Good for tests and iteration. +- **Cost and quotas**: No Blockfrost project limits on local runs. +- **Ecosystem alignment**: One local indexer can serve tools that expect Blockfrost-shaped responses. ## 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. +- **Operations**: You run and update the node and Yaci Store (disk, monitoring). If either is down, Blaze loses chain access. Heavier than a hosted API alone. +- **API version path**: Yaci Store uses `/api/v1/`; Blockfrost.io uses `/api/v0/`. Confirm compatibility with your Blaze release. Browser apps may need CORS or a proxy for 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). +- **Base URL and trailing slash:** Blaze’s Blockfrost client concatenates the base URL with relative paths. Use a trailing slash on the base (e.g. `http://localhost:8080/api/v1/`) so requests resolve to `.../api/v1/epochs/...` and not `.../api/v1epochs/...`. +- **Network:** Align network id / magic across the node, Yaci Store, Blaze `network`, and your addresses. +- **CORS:** For browser apps, allow your origin on Yaci Store or use the same host / a reverse proxy. ## References -- [Blaze Cardano](https://blaze.butane.dev/): Blaze SDK documentation and providers (Blockfrost, Kupmios, Maestro). +- [Blaze Cardano](https://blaze.butane.dev/): Blaze SDK 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`). +- [Yaci DevKit Docker setup](https://devkit.yaci.xyz/getting-started/docker): `devkit start`, `create-node`, default ports, API base `http://localhost:8080/api/v1/`. +- [Yaci Store](https://store.yaci.xyz/): Indexer architecture, configuration, and APIs. ---