Skip to content

Commit 2602c54

Browse files
danbarukadanbaruka
authored
Merge branch 'IntersectMBO:main' into main
2 parents 9c269d6 + 0b9d676 commit 2602c54

2 files changed

Lines changed: 178 additions & 0 deletions

File tree

‎website/docs/guides/_category_.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
label: Integration Guides
2+
position: 12
3+
link:
4+
type: generated-index

‎website/docs/guides/blaze-yaci-store-integration.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
---
2+
title: Blaze SDK + Yaci DevKit
3+
description: "Technical guide: using Yaci Store’s Blockfrost-compatible API from the Blaze SDK, with Yaci DevKit for local development."
4+
sidebar_position: 1
5+
---
6+
7+
# Blaze SDK + Yaci DevKit
8+
9+
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.
10+
11+
## Architecture and flow
12+
13+
```mermaid
14+
sequenceDiagram
15+
participant App as Your application
16+
participant Blaze as Blaze SDK
17+
participant API as Yaci Store (Blockfrost API)
18+
participant DB as Yaci Store DB (RDBMS)
19+
participant Node as Cardano node
20+
21+
App->>Blaze: e.g. getUtxos(address)
22+
Blaze->>API: GET /addresses/{address}/utxos
23+
API->>DB: Read indexed UTXOs
24+
DB-->>API: Rows
25+
API-->>Blaze: JSON response
26+
Blaze-->>App: Parsed UTXOs
27+
28+
Note over API,Node: Yaci Store syncs blocks from the node (ChainSync) and keeps the DB updated.
29+
30+
App->>Blaze: submitTx(signedTx)
31+
Blaze->>API: POST /tx/submit
32+
API->>Node: Forward tx (Ogmios, submit-api, or N2C — see below)
33+
Node-->>API: TxId / error
34+
API-->>Blaze: Response
35+
Blaze-->>App: Result
36+
```
37+
38+
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.
39+
40+
**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**.
41+
42+
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`).
43+
44+
- **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.
45+
- **Submit API:** You can run the **submit-api** module with the node; submission goes through that server.
46+
- **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.
47+
48+
**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.
49+
50+
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.
51+
52+
- **Your app** uses the Blaze SDK (TypeScript/JavaScript).
53+
- **Blaze SDK** calls a Blockfrost-style HTTP API (base URL + optional API key header).
54+
- **Reads** are served from Yaci Store’s index; **submission** is forwarded to the node according to the active mode.
55+
56+
So: **App → Blaze → Yaci Store (HTTP)** for queries; **submission** is **App → Blaze → Yaci Store → (Ogmios / submit-api / N2C) → node** as configured.
57+
58+
## Prerequisites
59+
60+
| Requirement | Purpose |
61+
|-------------|---------|
62+
| **Cardano node** | Source of chain data via ChainSync; required for syncing (can be remote). Needed for tx submission in all modes. |
63+
| **Yaci Store** | Running and exposing the Blockfrost-compatible REST API. |
64+
| **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`. |
65+
66+
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**.
67+
68+
For deeper Yaci Store behavior (stores, DB, deployment), see [Yaci Store documentation](https://store.yaci.xyz/).
69+
70+
## Configuration
71+
72+
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.
73+
74+
1. **Base URL**
75+
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).
76+
**Note:** Yaci Store uses **`/api/v1/`**; Blockfrost.io uses **`/api/v0/`**.
77+
78+
2. **API key**
79+
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.
80+
81+
3. **Blaze setup**
82+
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).
83+
84+
Example pattern (confirm `network` matches your devnet addresses and magic; DevKit is usually testnet-style):
85+
86+
```typescript
87+
import { Blaze, Blockfrost, ColdWallet, Core } from "@blaze-cardano/sdk";
88+
89+
// Trailing slash: Blaze concatenates base + "epochs/latest/parameters", etc.
90+
const YACI_STORE_BASE =
91+
process.env.BLOCKFROST_URL ?? "http://localhost:8080/api/v1/";
92+
93+
const provider = new Blockfrost({
94+
network: "cardano-preview", // or cardano-preprod / "unknown" — match your devnet
95+
projectId: process.env.BLOCKFROST_API_KEY ?? "",
96+
});
97+
provider.url = YACI_STORE_BASE;
98+
99+
const wallet = new ColdWallet(yourAddress, 0, provider);
100+
const blaze = await Blaze.from(provider, wallet);
101+
102+
// Build and submit as per Blaze docs (e.g. .newTransaction().payLovelace().complete())
103+
const tx = await blaze.newTransaction().payLovelace(recipient, amount).complete();
104+
```
105+
106+
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`).
107+
108+
## Interactions and API usage
109+
110+
Blaze uses Blockfrost-style endpoints for chain data and submission. Yaci Store implements these; your app talks to Blaze only.
111+
112+
| Interaction | Blaze (your code) | HTTP (Blaze → Yaci Store) | Purpose |
113+
|-------------|-------------------|---------------------------|---------|
114+
| Get UTXOs for address | e.g. `getUtxos(address)` | `GET /addresses/{address}/utxos` | Build inputs for a transaction. |
115+
| Get transaction | e.g. `getTransaction(txHash)` | `GET /txs/{hash}` | Inspect a submitted or existing tx. |
116+
| Submit transaction | e.g. `submitTx(signedTx)` | `POST /tx/submit` | Broadcast signed transaction. |
117+
| Protocol parameters | e.g. `getProtocolParameters()` | `GET /epochs/latest/parameters` | Min fee, min ADA, etc. |
118+
119+
Flow in practice:
120+
121+
1. **Read:** Blaze calls Yaci Store (e.g. UTXOs, protocol params). Yaci Store answers from its indexed database (kept in sync with the node).
122+
2. **Build:** Your app uses Blaze to assemble the transaction.
123+
3. **Sign:** You sign with Blaze or your wallet/keys.
124+
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.
125+
126+
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.
127+
128+
## End-to-end flow (summary)
129+
130+
```mermaid
131+
flowchart LR
132+
A[Start] --> B[Run DevKit: node + Yaci Store]
133+
B --> C[Set Blaze base URL to Yaci Store]
134+
C --> D[Read: UTXOs, params]
135+
D --> E[Build & sign tx in Blaze]
136+
E --> F[Submit via Blaze]
137+
F --> G[Yaci Store forwards per submission mode]
138+
G --> H[Done]
139+
```
140+
141+
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.
142+
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`**.
143+
3. Configure Blaze with Yaci Store’s base URL (**with trailing slash**) and API key if required.
144+
4. Use Blaze for reads and submission; monitor DevKit / Yaci Store / node logs if submission fails.
145+
146+
## Advantages of this setup
147+
148+
- **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.
149+
- **Same API surface**: Blockfrost-compatible API lets you reuse patterns from other SDKs; switch environments via base URL and env vars.
150+
- **Fast local dev and CI**: DevKit brings up node + indexer quickly, with configurable block times. Good for tests and iteration.
151+
- **Cost and quotas**: No Blockfrost project limits on local runs.
152+
- **Ecosystem alignment**: One local indexer can serve tools that expect Blockfrost-shaped responses.
153+
154+
## Limitations and drawbacks
155+
156+
- **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.
157+
- **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.
158+
159+
## Compatibility notes
160+
161+
- **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/...`.
162+
- **Network:** Align network id / magic across the node, Yaci Store, Blaze `network`, and your addresses.
163+
- **CORS:** For browser apps, allow your origin on Yaci Store or use the same host / a reverse proxy.
164+
165+
## References
166+
167+
- [Blaze Cardano](https://blaze.butane.dev/): Blaze SDK and providers (Blockfrost, Kupmios, Maestro).
168+
- [Yaci DevKit](https://devkit.yaci.xyz/): Local Cardano devnet with Yaci Store (Blockfrost API on port 8080).
169+
- [Yaci DevKit Docker setup](https://devkit.yaci.xyz/getting-started/docker): `devkit start`, `create-node`, default ports, API base `http://localhost:8080/api/v1/`.
170+
- [Yaci Store](https://store.yaci.xyz/): Indexer architecture, configuration, and APIs.
171+
172+
---
173+
174+
*This guide is part of the [Developer Experience](https://devex.intersectmbo.org/) initiative.*

0 commit comments

Comments
 (0)