diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..ff4f573 Binary files /dev/null and b/.DS_Store differ diff --git a/DA Milestones/Dan/Q22026/developer-experience-pain-points-and-solutions.md b/DA Milestones/Dan/Q22026/developer-experience-pain-points-and-solutions.md new file mode 100644 index 0000000..04748fc --- /dev/null +++ b/DA Milestones/Dan/Q22026/developer-experience-pain-points-and-solutions.md @@ -0,0 +1,141 @@ +# Developer Experience — Pain Points & Proposed Solutions + +**Milestone:** #105 — Pain Points with Solution (Q2 2026) +**Goal:** Foster Innovation & Technology Advancement — *document 2–3 pain points with proposed solutions in the Developer Experience repo* +**Author:** Dan Baruka, Developer Advocate — Developer Experience Working Group +**Status:** Draft for review + +--- + +## Executive summary + +The three pain points below share one root cause: **a newcomer's path into Cardano is fragmented**. It is fragmented at the *roadmap* level (no single place that says "start here and go there next"), at the *documentation* level (inconsistent, scattered, sometimes stale), and at the *tooling* level (many overlapping SDKs and contract languages with no opinionated guidance). Each compounds the others — and together they are the single biggest drag on developer onboarding. + +This report documents each pain point, the evidence behind it, its impact, and a concrete, low-to-medium-effort proposed solution that the Developer Experience Working Group can act on within Q2–Q3 2026. + +> **Note on scope:** the milestone calls for 2–3 pain points. Fragmented onboarding was selected as the priority; pain points 2 and 3 are treated as the documentation and tooling *facets* of that same fragmentation, so the report stays cohesive rather than covering three unrelated issues. + +--- + +## Evidence base + +This report does not introduce new claims — it consolidates findings the program has already produced: + +| Source | What it provides | Location | +|--------|------------------|----------| +| Shared DevEx Report to the OSC (Q4-2025) | "Current DevEx Status" assessment with priority ratings | [`../../DevEx-WG-Overview/Q1-2025.md`](../../DevEx-WG-Overview/Q1-2025.md) | +| Intersect Developer Experience Survey — 2025 | Developer-reported challenges, tooling usage, language needs | [`../Q42025/intersect-developer-experience-survey-2025.md`](../Q42025/intersect-developer-experience-survey-2025.md) | +| DevEx getting-started guide | Current onboarding entry point | [`../../../website/docs/getting-started.md`](../../../website/docs/getting-started.md) | + +--- + +## Pain Point 1 — Fragmented onboarding: no unified roadmap + +**Priority:** High + +### Description + +New developers do not have a single, structured roadmap that tells them where to start and how to progress. Onboarding content exists, but it is spread across multiple repositories, the DevEx website, the Cardano Developer Portal, and community channels — with no canonical "front door" and no clear sequencing. + +### Evidence + +- The Q4-2025 DevEx status assessment rates **Developer Onboarding as "Needs Improvement", priority High**, and states plainly that documentation "remains fragmented and scattered across multiple repositories and platforms" and that "new developers often lack a clear, structured roadmap." +- The 2025 survey isolates **"Getting Started: the initial setup and knowing where to begin was confusing"** as one of the headline challenges (Q14), and asks developers to rate how hard it is to *find* resources at all (Q15) and to *start contributing* (Q16). + +### Impact + +Capable developers stall — or quit — before writing any code, not for lack of skill but for lack of a path. This directly undercuts every onboarding-related milestone in the program, because each Developer Advocate is effectively rebuilding the same map by hand for every newcomer they meet. + +### Proposed solution + +Establish **one canonical onboarding roadmap** with profile-based entry points: + +1. Designate [`website/docs/getting-started.md`](../../../website/docs/getting-started.md) as the single authoritative "start here" page, and ensure every other onboarding surface links back to it rather than duplicating it. +2. Add **profile-based tracks** — e.g. *smart-contract developer*, *dApp / front-end developer (Web2 → Web3)*, *documentation / non-code contributor*, *infrastructure* — each a short ordered checklist of "do this, then this." +3. Cross-link the existing assets (Developer Portal, working-group sessions, the #76 D&I onboarding path) *into* the roadmap instead of leaving them as parallel islands. + +**Effort:** Low–Medium · **Suggested owner:** DevEx WG (Developer Advocates, rotating) · **Success measure:** survey Q15/Q16 scores improve quarter-over-quarter; advocates can answer "where do I start?" with one link. + +--- + +## Pain Point 2 — Documentation inconsistency & staleness + +**Priority:** Medium + +### Description + +Documentation quality across Cardano repositories is uneven. Some core repos are well-maintained; others are outdated or lack practical, step-by-step guidance. Structure differs from repo to repo, and related resources are weakly cross-linked. + +### Evidence + +- The Q4-2025 status assessment rates **Documentation Quality as "Mixed"** and lists two observed issues directly: *"inconsistent structure across repositories"* (reduces discoverability) and *"limited cross-linking between related resources"* (hinders navigation and learning flow). +- In the 2025 survey, **Tooling & Documentation** is an explicit answer option for "biggest challenge" (Q14), phrased as "guides were unclear/outdated," and Documentation is rated directly in Q19. + +### Impact + +A developer who *does* find the right page often can't trust it — an outdated guide costs more time than no guide, because it fails silently. Inconsistent structure also means the skill of "knowing how to read these docs" doesn't transfer from one repo to the next. + +### Proposed solution + +1. Adopt a **lightweight documentation template/standard** for DevEx-maintained docs (objective → prerequisites → steps → troubleshooting → next steps) — the structure already recommended in [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) — and apply it consistently. +2. Add a **"last reviewed" date** convention to maintained pages so staleness is visible at a glance. +3. Run a **cross-linking pass** on the DevEx docs so related pages point to each other, turning isolated pages into a navigable web. +4. Use `CODEOWNERS` to assign **clear ownership** for key doc areas, so review responsibility is unambiguous. + +**Effort:** Medium · **Suggested owner:** DevEx WG + repo maintainers · **Success measure:** survey Q19 "Documentation" rating improves; reduction in broken-link / outdated-content issues reported. + +--- + +## Pain Point 3 — Tooling & SDK choice paralysis + +**Priority:** Medium + +### Description + +A newcomer choosing how to build on Cardano immediately faces a long menu of overlapping options with no opinionated guidance on what to pick for their situation. + +### Evidence + +The 2025 survey's own answer lists make the scale of the choice concrete: + +- **Smart-contract languages (Q9):** Aiken, Haskell/Plutus-Tx, OpShin, Helios, Marlowe, Plu-ts, Scalus, Plinth, Tx3, Plutarch — *ten* options. +- **Off-chain / SDK tooling (Q11):** cardano-cli, Mesh, Lucid / Lucid Evolution, Blaze, PyCardano, Pallas, plus several services (Blockfrost, Koios, Maestro, Ogmios, Kupo) — *six-plus* SDKs alone. + +For someone still on "Getting Started," this is not freedom of choice — it is a decision they are not yet equipped to make, and getting it wrong means re-learning later. + +### Impact + +Choice paralysis at the very first technical step. Developers either stall, or commit to a tool semi-randomly and lose time when it turns out not to fit their use case. It also makes advocate support harder, because there's no shared default to teach against. + +### Proposed solution + +Publish a short, **opinionated "Which tool should I use?" decision guide** in the DevEx docs: + +1. A simple decision tree keyed to developer profile and use case (e.g. *"New to blockchain + want smart contracts → start with Aiken on testnet"*; *"Coming from Web2 front-end → start with a JS/TS SDK"*). +2. One **recommended default per profile**, with a one-line "choose something else if…" note — not a comprehensive comparison, deliberately opinionated. +3. Keep it explicitly *non-exhaustive*: the goal is to get a newcomer moving, not to catalogue the ecosystem. + +This pairs naturally with the profile-based tracks in Pain Point 1's roadmap. + +**Effort:** Low–Medium · **Suggested owner:** DevEx WG (Developer Advocates) · **Success measure:** survey Q14 "Tooling & Documentation" and Q11 patterns; advocates report fewer "which tool do I use?" support requests. + +--- + +## Summary + +| # | Pain point | Priority | Proposed solution | Effort | Suggested owner | +|---|------------|----------|-------------------|--------|-----------------| +| 1 | Fragmented onboarding — no unified roadmap | High | Canonical roadmap with profile-based tracks; consolidate entry points | Low–Med | DevEx WG | +| 2 | Documentation inconsistency & staleness | Medium | Doc template + "last reviewed" dates + cross-linking pass + `CODEOWNERS` | Medium | DevEx WG + maintainers | +| 3 | Tooling & SDK choice paralysis | Medium | Opinionated "which tool should I use?" decision guide | Low–Med | DevEx WG | + +## Next steps + +1. Review this report with the DevEx Working Group and confirm priority order. +2. Open a tracking issue in `IntersectMBO/developer-experience` for each accepted pain point so solutions are actionable and assignable. +3. Fold the outcomes into the next Shared DevEx Report to the OSC, aligned with the Open Source Strategy. +4. Re-measure against the 2025 survey questions cited above to track whether the solutions move the numbers. + +--- + +*Deliverable: Milestone #105 — Pain Points with Solution. Draft for review — Q2 2026. Evidence consolidated from the Q4-2025 Shared DevEx Report and the Intersect Developer Experience Survey 2025.* diff --git a/DA Milestones/Dan/Q22026/language-inclusive-onboarding-guide.md b/DA Milestones/Dan/Q22026/language-inclusive-onboarding-guide.md new file mode 100644 index 0000000..b7efbc7 --- /dev/null +++ b/DA Milestones/Dan/Q22026/language-inclusive-onboarding-guide.md @@ -0,0 +1,176 @@ +# Language-Inclusive Onboarding Guide — Cardano Developer Ecosystem + +**Milestone:** #76 — D&I Onboarding Guide (Q2 2026) +**Goal:** Implement diversity and inclusion programs — *draft an onboarding guide tailored for underrepresented groups* +**Underrepresented group addressed:** developers for whom English is not a first or comfortable working language +**Author:** Dan Baruka, Developer Advocate — Developer Experience Working Group +**Status:** Draft for review + +--- + +## Executive summary + +A significant share of capable developers never complete their first contribution to Cardano — not for lack of technical ability, but because the standard onboarding path is in English and silently assumes English-language fluency at every step: docs, tooling output, issue threads, community channels, and live sessions. Developers whose first language is not English routinely report that the *first* friction they hit is linguistic, not technical. + +This guide proposes a **language-inclusive onboarding framework** that the Developer Experience Working Group (DevEx WG) can adopt across its documentation, sessions, and advocacy program. It does not replace the general getting-started guide; it removes the implicit fluency requirement, lowers the cost of asking the first question, and treats non-English contributions (translation, glossaries, localized guides) as first-class work. + +The framework is language-agnostic. The Francophone outreach the program already runs (notably West/Central Africa) is used as a worked example, but the same pattern applies to Spanish, Portuguese, Arabic, Mandarin, Hindi, Swahili, and any other language where Cardano onboarding material is thin. + +> **Note on scope:** the milestone calls for an onboarding guide for an "underrepresented group". Several dimensions of underrepresentation exist (gender, geography, background, career stage, accessibility). This deliverable focuses exclusively on the **language dimension**, because it is the most universal first-step barrier and the one where the program already has active outreach to learn from. Other dimensions should be addressed in separate, focused guides rather than diluted into a single document. + +--- + +## Evidence base + +This guide consolidates findings the program has already produced and the standards the repo already enforces: + +| Source | What it provides | Location | +|--------|------------------|----------| +| Intersect Developer Experience Survey — 2025 | Self-reported language needs, regional distribution of respondents | [`../Q42025/intersect-developer-experience-survey-2025.md`](../Q42025/intersect-developer-experience-survey-2025.md) | +| Shared DevEx Report to the OSC (Q4-2025) | "Current DevEx Status" — onboarding rated High priority / Needs Improvement | [`../../DevEx-WG-Overview/Q1-2025.md`](../../DevEx-WG-Overview/Q1-2025.md) | +| DevEx getting-started guide | Current canonical onboarding entry point (English) | [`../../../website/docs/getting-started.md`](../../../website/docs/getting-started.md) | +| Contribution & conduct standards | Required reading for any contributor path proposed here | [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) · [`CODE-OF-CONDUCT.md`](../../../CODE-OF-CONDUCT.md) | + +--- + +## Where the language barrier actually bites + +The "language barrier" is not a single problem. It shows up as four distinct frictions, each with a different remedy. + +| Friction | What it looks like | Why it blocks contribution | +|----------|--------------------|----------------------------| +| **Reading technical English** | Newcomer can follow code samples but struggles with prose-heavy docs and long issue threads. | Slows progress; usually surmountable with translation tools. | +| **Writing public English** | Newcomer can read a doc but is reluctant to open an issue or PR description in English. | Highest-impact blocker — it stops the *first* visible contribution. | +| **Technical jargon and ecosystem-specific terms** | Generic translators mishandle terms like *epoch*, *UTxO*, *delegation*, *native asset*. | Even strong English readers misread or mistranslate Cardano-specific content. | +| **Live spoken English** | Working-group calls and recorded sessions run in English, often without transcripts or captions. | Excludes contributors who read English comfortably but cannot follow spoken English in real time. | + +Each section of the framework below targets one of these frictions. + +--- + +## Language-inclusive onboarding framework + +### 1. Reading — make the existing docs usable in any language + +**Principle:** A non-English-first developer should be able to read every canonical onboarding page in their language with one click and have confidence the translation is correct on the technical terms. + +**For the newcomer:** +- Use browser translation for prose; cross-check code samples against the original page (code is the source of truth). +- When a translation looks wrong, that is itself a documentation bug — open an issue. + +**For the program:** +- Publish a short, maintained glossary of Cardano terms in the DevEx repo, with entries in the languages the program actively supports. This single artifact disproportionately improves the quality of every machine-translated page. +- Mark pages that are translation-safe (no ambiguous idioms, no untranslated jargon) so contributors translating them know they will not need to rewrite English first. + +### 2. Writing — lower the cost of the first public message + +**Principle:** Imperfect English is welcome, normal, and explicitly accommodated. The community absorbs it without issue. + +**For the newcomer:** +- Draft issues and PR descriptions in your first language, then translate. State plainly that English is not your first language — this is well-received and routine. +- Keep PR descriptions short and structured (what / why / how tested); short English is easier to write correctly than long English. +- Treat translation, terminology fixes, and clarifying documentation as first-class contributions; they are explicitly welcomed in [`CONTRIBUTING.md`](../../../CONTRIBUTING.md). + +**For the program:** +- Provide ready-to-use issue and PR templates with neutral, simple English phrasing. +- Maintain a public norm that reviewers will not nitpick grammar on PRs flagged as written by a non-English-first contributor — feedback on language goes in a separate, optional thread. + +### 3. Jargon — handle Cardano-specific terms explicitly + +**Principle:** Ecosystem-specific vocabulary is the part machine translation gets wrong most often. Owning it locally is cheap. + +**For the newcomer:** +- When reading a translated page, treat protocol terms (epoch, slot, UTxO, native asset, delegation, governance action) as English keywords — do not rely on a translator's guess. +- If you cannot find a glossary entry for a term, open an issue requesting one. This *is* a contribution. + +**For the program:** +- Curate a single canonical glossary of ~50–100 core terms with short, plain-language explanations, then translate that glossary first (rather than translating every page). +- Link the glossary from `getting-started.md` and from every page that uses domain terms heavily. + +### 4. Spoken English — make live sessions usable asynchronously + +**Principle:** Sessions are an onboarding asset only if they are usable by contributors who cannot follow spoken English in real time. + +**For the newcomer:** +- Prefer the recording over the live call — pause, rewind, run through a translator. Live attendance is optional. +- Ask questions on [GitHub Discussions](https://github.com/IntersectMBO/developer-experience/discussions) or in the DevEx Discord channel afterward, in writing. + +**For the program:** +- Continue publishing session recordings; add at least auto-generated captions and, where possible, a short written summary of each session in the DevEx site. +- Encourage Developer Advocates fluent in additional languages to host periodic sessions in those languages and publish recordings with transcripts. + +--- + +## Standard contribution path (unchanged by language) + +Once the language friction is removed, the technical path is the same as for any contributor. Newcomers should pick **one** and ship a small contribution before sampling the others. + +| Path | Best for | Starting point | +|------|----------|----------------| +| **A — Smart contracts** | Developers comfortable with typed/functional languages | Aiken on testnet — [aiken-lang.org](https://aiken-lang.org) | +| **B — dApp / front-end** | JavaScript/TypeScript developers | Mesh, Lucid/Evolution, or Blaze SDKs | +| **C — Documentation / translation** | Anyone — the most direct on-ramp for non-English-first contributors | Issues labeled `documentation`, `translation`, or `good first issue` | +| **D — Infrastructure / tooling** | Experienced systems engineers | Ecosystem repos under [github.com/IntersectMBO](https://github.com/IntersectMBO) | + +Canonical reference for all four: the [Cardano Developer Portal](https://developers.cardano.org). Standard flow: fork → clone → branch → commit → push → pull request, with scope discussed in an issue first — see [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) and the [Code of Conduct](../../../CODE-OF-CONDUCT.md). + +--- + +## Onboarding checklist + +- [ ] Read the DevEx [getting-started guide](../../../website/docs/getting-started.md) using your preferred translation tool; bookmark the original page. +- [ ] Install Git, a recent Node.js (LTS), and an editor; confirm you can run a fork → PR cycle on a throwaway repo. +- [ ] Pick **one** technical path (A / B / C / D) and one first step inside it. +- [ ] Join the DevEx WG Discord channel and introduce yourself in your preferred language — note that English is not your first language if helpful. +- [ ] Find or open an issue, agree on scope in the issue thread, then submit a small first PR. +- [ ] Book a 1:1 with a Developer Advocate — ideally one who speaks your language — if you are blocked for more than a day. + +--- + +## Community and mentorship + +| Channel | Purpose | Link | +|---------|---------|------| +| DevEx WG Discord | Day-to-day help, async questions | [Dev-Ex WG channel](https://discord.com/channels/1136727663583698984/1250047836339306526) | +| GitHub Discussions | Long-form questions, decisions | [developer-experience discussions](https://github.com/IntersectMBO/developer-experience/discussions) | +| Sessions calendar | Live working-group sessions (recorded) | [Intersect events calendar](https://calendar.google.com/calendar/u/1?cid=Y19iMGMyODE3NWE2NTBkOGUwNzIwNTM2ZGU4OWE0NDMxMjFiYTcxYTVkMDgxYmRiOWU1NGRiZTU2NjI1NGY5ZGUwQGdyb3VwLmNhbGVuZGFyLmdvb2dsZS5jb20) | +| Cardano Forum | Ecosystem-wide discussion | [forum.cardano.org](https://forum.cardano.org) | +| Cardano Stack Exchange | Technical Q&A | [cardano.stackexchange.com](https://cardano.stackexchange.com) | + +Developer Advocates are the program's primary mentorship channel. The advocates roster, working languages, and booking links are published on the DevEx site so this document remains independent of personnel changes. Intersect membership (~USD 10 / year) unlocks Discord and governance participation but is **not** required to contribute code or documentation — [members.intersectmbo.org/registration](https://members.intersectmbo.org/registration) · [membership guide](../../../website/docs/intersect-membership-guide.md). + +--- + +## Implementation roadmap (Q2–Q3 2026) + +| Phase | Deliverable | Owner | +|-------|-------------|-------| +| Q2 2026 | Publish this guide on the DevEx site; cross-link from `getting-started.md` and `CONTRIBUTING.md`. | DevEx WG | +| Q2 2026 | Ship a first-pass Cardano glossary (~50 terms) in English; structure it for translation. | DevEx WG + advocates | +| Q3 2026 | Translate the glossary into the first non-English language with active outreach (French as the pilot). | Volunteer translators | +| Q3 2026 | Establish a public advocates list showing working languages and time zones. | Developer Advocate team | +| Q3 2026 | Pilot a localized session in at least one non-English language; publish recording, captions, and short written summary. | Volunteer advocates | +| Q3 2026 | Add captions or written summaries to all DevEx WG session recordings. | Session hosts | + +--- + +## Success indicators + +The guide should be evaluated, not assumed effective. Suggested indicators, all measurable from existing signals: + +- Time from first contact to merged first PR for contributors whose first language is not English. +- Share of first-time contributors who report (in the annual survey) that language friction was a blocker. +- Number of translation, glossary, or documentation-clarification contributions merged per quarter. +- Retention: share of first-time non-English-first contributors who submit a second PR within 90 days. + +A baseline should be captured before the guide is promoted, so changes are attributable. + +--- + +## Localization of this guide + +This document is published in English as the working language of the DevEx WG and OSC review. Localized versions should be produced as separate pages in the same repo under `website/docs/i18n/`, kept in sync via a lightweight diff process rather than maintained as forks. French is the natural pilot translation given existing Francophone outreach; Spanish and Portuguese are reasonable next candidates. Translation contributions are explicitly welcomed. + +--- + +*Deliverable: Milestone #76 — D&I onboarding guide for developers facing a language barrier in the Cardano ecosystem. Draft — Q2 2026.* diff --git a/website/docs/how-to-guide/advanced/README.md b/website/docs/how-to-guide/advanced/README.md index 3dbe0db..00f6b6d 100644 --- a/website/docs/how-to-guide/advanced/README.md +++ b/website/docs/how-to-guide/advanced/README.md @@ -5,6 +5,7 @@ Welcome to the Advanced Guides section! These guides are for experienced develop ### Ecosystem Projects - **Cardano DB Sync**: Check out this awesome guide to Cardano DB Sync [here](./cardano-db-sync.md) - **Cardano API**: Check out this awesome guide to Cardano API [here](./cardano-api.md) +- **Yaci DevKit**: Setup a local Cardano devnet step by step [here](./yaci-devkit.md) ## Getting Involved diff --git a/website/docs/how-to-guide/advanced/yaci-devkit.mdx b/website/docs/how-to-guide/advanced/yaci-devkit.mdx new file mode 100644 index 0000000..a6bb6a0 --- /dev/null +++ b/website/docs/how-to-guide/advanced/yaci-devkit.mdx @@ -0,0 +1,554 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Setup a Local Cardano Devnet with Yaci DevKit + +A complete, copy-paste setup for a local Cardano devnet using [Yaci DevKit](https://github.com/bloxbean/yaci-devkit). You get a single-node Cardano network, a Blockfrost-compatible indexer (Yaci Store), and a browser-based explorer (Yaci Viewer) running in seconds. + +## Overview + +| Component | URL | Purpose | +|---|---|---| +| Cardano Node | `localhost:3001` (n2n), `localhost:3333` (n2c via socat) | Local blockchain | +| Yaci Store API | http://localhost:8080/api/v1/ | Blockfrost-compatible indexer | +| Yaci Store Swagger | http://localhost:8080/swagger-ui/index.html | REST docs | +| Yaci Viewer | http://localhost:5173 | Block/tx explorer | +| Ogmios (optional) | ws://localhost:1337 | WebSocket node API | +| Kupo (optional) | http://localhost:1442 | UTXO indexer | +| Submit API | http://localhost:8090 | Tx submission | + +Default `testnet-magic` is `42`. + +--- + +## 1. Install Docker + + + + +```bash +brew install --cask docker +open -a Docker +``` + +Wait for the whale icon in the menu bar to settle, then verify: + +```bash +docker info +docker compose version +``` + + + + +```bash +sudo apt-get update +sudo apt-get install -y ca-certificates curl gnupg +sudo install -m 0755 -d /etc/apt/keyrings +curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg +sudo chmod a+r /etc/apt/keyrings/docker.gpg +echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \ + https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \ + | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null +sudo apt-get update +sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin +sudo usermod -aG docker $USER +newgrp docker +docker info +``` + + + + +1. Install [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/) and enable the **WSL2 backend** during setup. +2. Install Ubuntu via the Microsoft Store, then open it. +3. From your Ubuntu shell, verify: + +```bash +docker info +docker compose version +``` + +> All subsequent commands on Windows must be run from the **Ubuntu (WSL2)** shell, not PowerShell or cmd. The DevKit scripts are bash and the n2c Unix socket only works through WSL2. + + + + +--- + +## 2. Install Yaci DevKit + +Pick **one** of the three distributions. Docker zip is the most common. + +### Option A — Docker zip (recommended) + + + + +```bash +cd ~ +curl -L -o yaci-devkit.zip \ + https://github.com/bloxbean/yaci-devkit/releases/latest/download/yaci-devkit-docker.zip +unzip yaci-devkit.zip -d yaci-devkit +cd yaci-devkit +chmod +x bin/devkit.sh +``` + + + + +```bash +cd ~ +sudo apt-get install -y unzip curl +curl -L -o yaci-devkit.zip \ + https://github.com/bloxbean/yaci-devkit/releases/latest/download/yaci-devkit-docker.zip +unzip yaci-devkit.zip -d yaci-devkit +cd yaci-devkit +chmod +x bin/devkit.sh +``` + + + + +In the Ubuntu shell: + +```bash +cd ~ +sudo apt-get install -y unzip curl +curl -L -o yaci-devkit.zip \ + https://github.com/bloxbean/yaci-devkit/releases/latest/download/yaci-devkit-docker.zip +unzip yaci-devkit.zip -d yaci-devkit +cd yaci-devkit +chmod +x bin/devkit.sh +``` + +> Keep the install path inside the WSL2 filesystem (`~`, not `/mnt/c/...`) — Windows-mounted paths break the socket bind-mounts. + + + + +### Option B — NPM (CI/CD-friendly) + +Identical on all three OSes (use the Ubuntu/WSL shell on Windows): + +```bash +npm install -g @bloxbean/yaci-devkit +yaci-devkit --help +``` + +### Option C — Clone the source repo + +Identical on all three OSes: + +```bash +git clone https://github.com/bloxbean/yaci-devkit.git +cd yaci-devkit +chmod +x bin/devkit.sh +``` + +--- + +## 3. Start the DevKit + +From the `yaci-devkit` directory: + + + + +```bash +./bin/devkit.sh start +``` + + + + +```bash +./bin/devkit.sh start +``` + + + + +```bash +# Inside the Ubuntu (WSL2) shell +./bin/devkit.sh start +``` + +> Docker Desktop must be running on Windows before this works. + + + + +You'll see the URLs banner, then drop into the interactive `yaci-cli`: + +``` +yaci-cli> +``` + +In a fresh DevKit there is **no devnet yet** — you create one with `create-node`. + +--- + +## 4. Create and Start a Devnet + +At the `yaci-cli>` prompt (same on every OS): + +```bash +# Single-node, default 1s blocks +yaci-cli> create-node -o --start + +# Fast 200ms blocks (v0.11+) +yaci-cli> create-node --block-time 0.2 --slot-length 0.2 -o --start + +# Multi-node cluster (rollback testing only) +yaci-cli> create-node --enable-multi-node --block-time 2 -o --start +``` + +After `--start`, the prompt switches to: + +``` +devnet:default> +``` + +Verify: + +```bash +devnet:default> tip +devnet:default> info +devnet:default> default-addresses +``` + +Open http://localhost:5173 — the viewer should show live blocks. + +--- + +## 5. Fund Test Addresses + +Same on every OS: + +```bash +# Top up a single address with 1000 ADA +devnet:default> topup addr_test1qzlwg5c3mpr0cz5td0rvr5rvcgf02al05cqgd2wzv7pud6chpzk4elx4jh2f7xtftjrdxddr88wg6sfszu8r3gktpjtqrr00q9 1000 + +# Inspect UTXOs +devnet:default> utxos addr_test1qzlwg5c3mpr0cz5td0rvr5rvcgf02al05cqgd2wzv7pud6chpzk4elx4jh2f7xtftjrdxddr88wg6sfszu8r3gktpjtqrr00q9 +``` + +To auto-fund on every fresh start, edit `config/env`: + +```properties +topup_addresses=addr_test1...:20000,addr_test1...:10000 +``` + +--- + +## 6. Environment Variables (one-time setup) + +Set these once per shell — every subsequent host-side command uses them. + + + + +```bash +# Adjust HOME_YACI_DEVKIT to wherever you installed the zip / cloned the repo +export HOME_YACI_DEVKIT=$HOME/yaci-devkit +export NETWORK_MAGIC=42 + +# Make them permanent in your shell rc file +cat >> ~/.bashrc <<'EOF' +export HOME_YACI_DEVKIT=$HOME/yaci-devkit +export NETWORK_MAGIC=42 +EOF +``` + +> The `cardano-node` Unix socket lives **inside** the `yaci-cli` container at `/clusters/nodes/default/node/node.sock`. From the host, use the `./bin/devkit.sh cli ...` wrapper (it auto-injects `--testnet-magic 42` and the socket path), or `./bin/devkit.sh ssh` to drop into the container. + + + + +```bash +# In the Ubuntu (WSL2) shell +export HOME_YACI_DEVKIT=$HOME/yaci-devkit +export NETWORK_MAGIC=42 + +cat >> ~/.bashrc <<'EOF' +export HOME_YACI_DEVKIT=$HOME/yaci-devkit +export NETWORK_MAGIC=42 +EOF +``` + + + + +--- + +## 7. Use `cardano-cli` Against the Devnet + +The wrapper auto-appends `--testnet-magic 42` and the socket path — so **don't pass `--testnet-magic` yourself** when using `./bin/devkit.sh cli ...`. It runs `cardano-cli` inside the container, so any `--out-file` path is **container-side**, not host-side. + +```bash +cd $HOME_YACI_DEVKIT + +# Tip +./bin/devkit.sh cli query tip + +# Protocol parameters (file written inside the container at /clusters/...) +./bin/devkit.sh cli query protocol-parameters \ + --out-file /clusters/nodes/default/pparams.json +``` + +The genesis-funded test keys live at `/clusters/nodes/default/utxo-keys/` inside the container (`utxo1`, `utxo2`, `utxo3`). They have ~3,000,000,000 ADA each and are the cleanest way to demo a transaction. + +```bash +# Inspect them +./bin/devkit.sh ssh +# inside the container: +ls /clusters/nodes/default/utxo-keys +# utxo1.skey utxo1.vkey utxo2.skey utxo2.vkey utxo3.skey utxo3.vkey +exit +``` + +--- + +## 8. Full Demo Transaction (copy-paste, end-to-end) + +Sends **10 ADA from `utxo1` to `utxo2`** using the DevKit's genesis-funded keys, then verifies it landed via Yaci Store. Because all file paths and the socket are inside the container, the cleanest pattern is to run the whole block via `devkit.sh ssh` with a heredoc — tested verbatim against `v0.11.0-beta1`. + +```bash +cd $HOME_YACI_DEVKIT +./bin/devkit.sh ssh <<'INNER' +set -e +export CARDANO_NODE_SOCKET_PATH=/clusters/nodes/default/node/node.sock +mkdir -p /tmp/demo && cd /tmp/demo + +# 1. Derive sender + receiver addresses from the bundled genesis keys +SENDER_ADDR=$(cardano-cli address build \ + --payment-verification-key-file /clusters/nodes/default/utxo-keys/utxo1.vkey \ + --testnet-magic 42) +RECEIVER_ADDR=$(cardano-cli address build \ + --payment-verification-key-file /clusters/nodes/default/utxo-keys/utxo2.vkey \ + --testnet-magic 42) +echo "From : $SENDER_ADDR" +echo "To : $RECEIVER_ADDR" + +# 2. Grab the first UTXO at the sender (no jq in container — use grep) +cardano-cli query utxo --address "$SENDER_ADDR" --testnet-magic 42 --out-file utxos.json +TX_IN=$(grep -oE '"[0-9a-f]{64}#[0-9]+"' utxos.json | head -1 | tr -d '"') +echo "Input UTXO: $TX_IN" + +# 3. Build the transaction (10 ADA = 10,000,000 lovelace) +cardano-cli conway transaction build \ + --tx-in "$TX_IN" \ + --tx-out "$RECEIVER_ADDR+10000000" \ + --change-address "$SENDER_ADDR" \ + --testnet-magic 42 \ + --out-file tx.raw + +# 4. Sign with utxo1's signing key +cardano-cli conway transaction sign \ + --tx-body-file tx.raw \ + --signing-key-file /clusters/nodes/default/utxo-keys/utxo1.skey \ + --testnet-magic 42 \ + --out-file tx.signed + +# 5. Submit + extract the tx hash +cardano-cli conway transaction submit --tx-file tx.signed --testnet-magic 42 +TX_HASH=$(cardano-cli conway transaction txid --tx-file tx.signed | grep -oE '[0-9a-f]{64}') +echo "TX_HASH=$TX_HASH" +INNER +``` + +You'll see the tx hash printed. Now verify it landed in a block via the Yaci Store API on the **host**: + +```bash +# Replace with the TX_HASH printed above +TX_HASH= + +# Wait a block, then look it up +sleep 3 +curl -s "http://localhost:8080/api/v1/txs/$TX_HASH" | jq + +# Recompute receiver address on host and check its balance grew +RECEIVER_ADDR=$($HOME_YACI_DEVKIT/bin/devkit.sh cli address build \ + --payment-verification-key-file /clusters/nodes/default/utxo-keys/utxo2.vkey | tail -1) +curl -s "http://localhost:8080/api/v1/addresses/$RECEIVER_ADDR" | jq +``` + +Expected: `txs/$TX_HASH` shows the tx in a block, and the receiver's `amount` includes the new 10 ADA UTXO. + +> If `txs/$TX_HASH` returns 404, the tx is still in the mempool — the node hasn't forged a block including it yet. On a stalled devnet (long-offline single producer) it can stay 404 forever; run `devnet:default> reset` to get fresh genesis. + +--- + +## 9. Talk to Yaci Store (Blockfrost-compatible API) + +The indexer is on `http://localhost:8080`. The endpoints mirror Blockfrost where it makes sense. + +`curl` is available natively on macOS, Linux, and modern Windows — these commands work as-is in any shell. The PowerShell variants are shown only where the syntax actually differs. + + + + +```bash +# Latest block +curl -s http://localhost:8080/api/v1/blocks/latest | jq + +# Block by number +curl -s http://localhost:8080/api/v1/blocks/100 | jq + +# Latest transactions (paginated) +curl -s "http://localhost:8080/api/v1/txs?page=1&count=10" | jq + +# UTXOs at an address +curl -s "http://localhost:8080/api/v1/addresses/addr_test1.../utxos" | jq + +# Submit a signed CBOR transaction +curl -s -X POST \ + -H "Content-Type: application/cbor" \ + --data-binary @tx.cbor \ + http://localhost:8090/api/submit/tx +``` + + + + +```powershell +# Latest block +Invoke-RestMethod http://localhost:8080/api/v1/blocks/latest + +# Block by number +Invoke-RestMethod http://localhost:8080/api/v1/blocks/100 + +# Latest transactions (paginated) +Invoke-RestMethod "http://localhost:8080/api/v1/txs?page=1&count=10" + +# Submit a signed CBOR transaction +Invoke-RestMethod -Method Post ` + -Uri http://localhost:8090/api/submit/tx ` + -ContentType "application/cbor" ` + -InFile tx.cbor +``` + + + + +Full Swagger docs: http://localhost:8080/swagger-ui/index.html. + +### Use it from your DApp + +It exposes the minimum Blockfrost-compatible endpoints for tx building, so it drops in to: + +- **Cardano Client Lib (Java)** — Blockfrost backend pointed at `http://localhost:8080/api/v1/` +- **MeshJS (JS/TS)** — [example](https://github.com/MeshJS/examples/blob/main/mesh/yaci-send-lovelace.ts) +- **Lucid Evolution** — Blockfrost provider with the same base URL + +--- + +## 10. Optional: Ogmios & Kupo + +Enable in `config/env` before starting (same file on every OS — edit with your usual editor): + +```properties +ogmios_enabled=true +kupo_enabled=true +``` + +Then restart: + +```bash +./bin/devkit.sh stop +./bin/devkit.sh start +``` + +- Ogmios: `ws://localhost:1337` +- Kupo: `curl http://localhost:1442/matches/*` etc. + +--- + +## 11. Reset, Stop, Restart + +Same on every OS: + +```bash +# Inside yaci-cli — wipe devnet data and start over +devnet:default> reset + +# From the host — stop all DevKit containers +./bin/devkit.sh stop + +# Restart (containers + interactive yaci-cli) +./bin/devkit.sh start +``` + +If the node was offline for hours and `query tip` shows `syncProgress` stuck below 100, run `reset` — a single-producer devnet doesn't catch up across large wall-clock gaps. Fresh genesis is faster. + +--- + +## 12. Rollback Testing (Multi-node Only) + +```bash +# Start a 3-node cluster +yaci-cli> create-node --enable-multi-node --block-time 2 -o --start + +# Partition the network +devnet:default> create-forks + +# Submit txs on the partitioned side +devnet:default> topup addr_test1... 1000 + +# Heal the partition — the shorter chain rolls back +devnet:default> join-forks +``` + +Useful for testing how your indexer or DApp handles reorgs. + +--- + +## Troubleshooting + + + + +| Symptom | Fix | +|---|---| +| `Cannot connect to the Docker daemon` | `open -a Docker` and wait for the whale to settle | +| Port already in use (8080, 5173, 3001…) | Edit `config/env` `HOST_*_PORT` values | +| Viewer shows 500 / "Waiting for live data" | `docker logs node1-yaci-cli-1` — the in-container `cardano-node` must be running. After a Docker restart, re-run `./bin/devkit.sh start` then `create-node -o --start` (or `reset`) | +| `query tip` returns the same slot forever | Devnet stalled after long offline gap → `reset` | +| Apple Silicon image issues | DevKit ships `arm64` images — check `config/version` matches your release | + + + + +| Symptom | Fix | +|---|---| +| `Cannot connect to the Docker daemon` | `sudo systemctl start docker`; verify `docker info` works without sudo (re-login after `usermod -aG docker`) | +| Port already in use (8080, 5173, 3001…) | Edit `config/env` `HOST_*_PORT` values | +| Permission denied on `bin/devkit.sh` | `chmod +x bin/devkit.sh` | +| Viewer shows 500 / "Waiting for live data" | `docker logs node1-yaci-cli-1` — the in-container `cardano-node` must be running. After a Docker restart, re-run `./bin/devkit.sh start` then `create-node -o --start` (or `reset`) | +| `query tip` returns the same slot forever | Devnet stalled after long offline gap → `reset` | + + + + +| Symptom | Fix | +|---|---| +| `Cannot connect to the Docker daemon` | Start Docker Desktop; ensure WSL2 integration is enabled for your Ubuntu distro (Settings → Resources → WSL Integration) | +| `./bin/devkit.sh: /bin/bash^M: bad interpreter` | Repo was cloned with CRLF — `sed -i 's/\r$//' bin/devkit.sh scripts/*.sh` | +| Port already in use (8080, 5173, 3001…) | Edit `config/env` `HOST_*_PORT` values | +| Viewer shows 500 / "Waiting for live data" | In Ubuntu WSL2: `docker logs node1-yaci-cli-1`. After a Docker Desktop restart, re-run `./bin/devkit.sh start` then `create-node -o --start` (or `reset`) | +| `query tip` returns the same slot forever | Devnet stalled after long offline gap → `reset` | +| File-permission errors on the zip | Don't install under `/mnt/c/...` — install inside the WSL2 filesystem (`~`) | + + + + +--- + +## References + +- DevKit repo: https://github.com/bloxbean/yaci-devkit +- DevKit docs: https://devkit.yaci.xyz +- Yaci Store: https://github.com/bloxbean/yaci-store +- CI integration guide: https://devkit.yaci.xyz/ci-integration +- Sample CI project: https://github.com/bloxbean/devkit-npm-ci-test