Cardano DEX Programming Toolkit (OS MM/Arb Building Blocks)

[Proposal setup] Proposal title

Please provide your proposal title

Cardano DEX Programming Toolkit (OS MM/Arb Building Blocks)

[Proposal Summary] Budget Information

Enter the amount of funding you are requesting in ADA

100000

[Proposal Summary] Time

Please specify how many months you expect your project to last

4

[Proposal Summary] Translation Information

Please indicate if your proposal has been auto-translated

No

Original Language

en

[Proposal Summary] Problem Statement

What is the problem you want to solve?

Cardano lacks lightweight, open tools for DEX interaction and on-chain data. Teams rebuild plumbing to prototype MM/arb. We provide simple, tested blocks and examples to speed strategy building.

[Proposal Summary] Project Dependencies

Does your project have any dependencies on other organizations, technical or otherwise?

No

Describe any dependencies or write 'No dependencies'

Libraries are evolving rapidly, we will use the best available libraries and infra available at the time.

[Proposal Summary] Project Open Source

Will your project's outputs be fully open source?

Yes

License and Additional Information

Apache 2.0

[Theme Selection] Theme

Please choose the most relevant theme and tag related to the outcomes of your proposal

Developer Tools

[Campaign Category] Category Questions

Mention your open source license and describe your open source license rationale.

License: Apache 2.0.

Rationale: We want maximum adoption for Cardano DEX/data blocks across teams and stacks. Apache-2.0 is permissive, includes an explicit patent grant, and protects contributors while only requiring NOTICE/attribution. It avoids copyleft friction, enabling both open and commercial use, and keeps the project vendor-neutral. We’ll add SPDX headers, a NOTICE file, and clear CONTRIBUTING to make obligations explicit.

How do you make sure your source code is accessible to the public from project start, and people are informed?

Code is public from day-1 in a GitHub org. We work in the open: issues, roadmap, milestones, and tagged releases. CI on every PR; releases publish packages (e.g., npm/PyPI) and versioned docs. We’ll post bi-weekly updates in the repo and Catalyst channels, announce in Cardano dev communities/Discords, and keep a lightweight homepage. No private mirrors; planning and artifacts remain public.

How will you provide high quality documentation?

Docs-first. A site with a 5-minute Quickstart, copy-paste recipes (DEX read/swap/LP, UTxO & event parsing,..), and minimal CEX↔DEX arb examples. API reference auto-generated (TypeDoc/Haddock) from typed comments. Examples are runnable and covered by CI. We’ll maintain a CHANGELOG, versioned docs, diagrams, and a Contributor Guide to keep docs current with releases.

[Your Project and Solution] Solution

Please describe your proposed solution and how it addresses the problem

In short: An Apache-2.0 open repo of small, runnable Cardano DEX examples (“recipes”) that compose existing libs (e.g., Dexter, protocol SDKs, Koios/Blockfrost/Ogmios/CSL). The focus is on DEX reads, quotes, swaps, simple LP ops, UTxO/datum parsing, and a minimal CEX↔DEX price-check in paper mode. No simulators, no full trading system.

What’s included

• Read pool state and prices from supported DEXs.
• Quote best route across 1–2 pools; show slippage math.
• Swap with safety rails: TTL, min-receive, dry-run.
• LP add/withdraw helpers and position reads.
• Cross-DEX spread watcher with alert hook.
• Minimal CEX↔DEX price-check example (paper mode by default).
• Small, reusable helper functions under /lib (UTxO filters, datum decode, fee/min-UTxO helpers). These are in-repo utilities, not separate packages.

Repo layout (simple)

• /examples – runnable scripts with .env templates.
• /lib – tiny helpers for UTxO, math, parsers.
• /docs – Quickstart and per-recipe guides.
• CI runs lint, typecheck, and executes examples on preview/testnet where possible.

Docs & DX

• 5-minute Quickstart (install, set env, run).
• Copy-paste snippets beside each example.
• Comments in code first; short guides second.
• Clear disclaimers and safety defaults called out.

Non-goals

• No packaged SDKs or a full aggregator.
• No backtesting/simulators, custody, hosting, or profit claims.
• No MEV infra or bridges.

Risks & mitigations

• SDK or protocol changes: thin usage, pinned versions, integration scripts in CI.
• Indexer limits: provider options and backoff; small local cache where allowed.
• Key handling: BYO keys; default dry-run; optional offline signing path.
• Scope creep: ship examples first; defer features that look like products.

Success criteria (modest)

• 2 DEXs demonstrated in examples.
• 5 runnable recipes passing CI.
• At least 3 external teams reference or fork the repo for their prototypes.
• Community PR adds one adapter or recipe.

Summary

We deliver one public repo of practical, chain-first examples that show how to combine Cardano DEX SDKs and on-chain data into safe, minimal building blocks for market-making and arbitrage workflows.

[Your Project and Solution] Impact

Please define the positive impact your project will have on the wider Cardano community

What problem we reduce (in plain terms)

Today, Cardano builders spend days wiring DEX SDKs, indexers, and UTxO parsing just to test a simple idea. Every team reimplements the same glue code, and many stop at read-only prototypes. Our repo gives ready-to-run examples and tiny helpers so teams can try safe swaps/LP ops and simple cross-DEX checks quickly—without inventing plumbing.

Who benefits

• New devs & small teams: faster path from “idea” to a working script.

• DEX/Protocol teams: fewer “how do I…?” tickets; examples they can point to.

• Tooling maintainers: a neutral place to showcase correct integration patterns.

• Educators & hackathons: runnable, copy-pasteable materials for workshops.

• Ecosystem at large: more experiments → more useful tools and docs over time.

How it moves the needle (without hype)

• Lower barrier to entry: clear, runnable recipes (read, quote, swap, LP) + .env config.

• Safer first steps: built-in guard rails (min-receive, TTL, dry-run, notional caps) reduce common mainnet mistakes.

• Composability by example: shows how to chain Dexter/DEX SDKs + on-chain data into small workflows.

• Shared vocabulary: examples + helpers nudge towards consistent patterns across projects.

• Open, permissive reuse: Apache-2.0 enables commercial and open-source use, encouraging wider adoption and maintenance.

Concrete outcomes we aim for (modest, measurable)

• Usability

  • Time-to-first-swap example: hours, not days (measured via community feedback/issues).

  • 5 examples that pass CI and run on preview/testnet by default.

• Adoption

  • ≥ 2 DEXs demonstrated in examples.

  • ≥ 3 external teams referencing or forking the repo for prototypes.

  • ≥ 1 community PR adding an adapter or new recipe.

• Learning

  • Quickstart under 5 minutes; each example includes a “why” and “how to extend.”

  • Talks/threads in Cardano dev channels summarizing lessons learned from the examples.

(These are directional; we’ll track stars/forks, issue mentions, example run logs in CI, and short surveys in the repo.)

Short-term impact (first releases)

• Teams can quote and dry-run swaps on testnet the same day they discover the repo.

• Protocol docs get a neutral, third-party place to point people for cross-tool composition.

• Hackathon participants can ship demos that include basic execution and LP flows safely.

Medium-term impact (as examples accumulate)

• A small “commons” of reliable snippets (UTxO parsers, fee/min-UTxO helpers) reduces duplicated, error-prone code across projects.

• Community PRs expand DEX coverage and niche workflows (e.g., multi-pool quotes, spread watchers).

• Better first-mile experiences may contribute to more sophisticated tooling and, indirectly, healthier liquidity practices—without us promising trading outcomes.

Ecosystem fit

• Complements, not competes with, existing SDKs (e.g., Dexter, protocol libs). We show how to combine them; we don’t replace them.

• Keeps surface area intentionally small (a repo of examples + tiny helpers), making longevity feasible and vendor-neutral.

• Works with common indexer options (Koios/Blockfrost/Ogmios/node-RPC) via simple configuration rather than hard dependencies.

Inclusion & neutrality

• Apache-2.0 + public GitHub from day one: no gatekeeping, no paywalls, no closed mirrors.

• Examples avoid protocol favoritism; adapter interface keeps it easy to add alternatives.

• Clear disclaimers to avoid encouraging risky behavior; defaults bias to dry-run and safety.

Risks if we do nothing

• Teams keep rebuilding the same glue, producing more inconsistent (and sometimes unsafe) scripts.

• New devs bounce due to the initial “how do I connect X + Y?” hurdle.

• Documentation stays fragmented across repos, issues, and chats.

Why Catalyst is the right lever

• This is a public good with broad spillover benefits: one team’s examples save time for many others.

• Small grant → outsized utility: the project is intentionally scoped to stay lightweight and maintainable.

Summary

Impact here is practical: less friction, safer starts, more composable examples. By providing a well-lit path from on-chain reads to guarded execution, we help more Cardano builders cross the prototype gap, reuse patterns, and share improvements—without overpromising outcomes or building heavy infrastructure.

[Your Project and Solution] Capabilities & Feasibility

What is your capability to deliver your project with high levels of trust and accountability? How do you intend to validate if your approach is feasible?

Capabilities & Feasibility

What we can deliver (scope-true)

• One public repo (Apache-2.0) with small, runnable TypeScript examples (“recipes”) focused on:
  • Reading pool state and prices from Cardano DEXs using existing SDKs (e.g., Dexter and protocol-specific libs).
  • Building quotes (exact-in / exact-out) and showing slippage math.
  • Executing guarded swaps (TTL, min-receive, dry-run by default).
  • Basic LP flows (add / withdraw) and position reads where SDKs support it.
  • A minimal CEX↔DEX price-check in paper mode (educational; not production arb).
• Tiny in-repo helpers under /lib (UTxO filters, datum decoding, fee/min-UTxO helpers). No separate packages.
• Docs: 5-minute Quickstart, per-example guides, copy-paste snippets.
• CI: lint, typecheck, unit tests, and preview/testnet integration runs for examples.

Technical approach (simple & boring by design)

• TypeScript + Node.js; scripts runnable via npm run (or pnpm).
• Indexers/providers configurable via .env (Koios, Blockfrost, Ogmios, or node RPC).
• DEX usage: rely on maintained SDKs; we compose rather than re-implement.
• Safety defaults: dry-run, min-receive, notional caps, TTL, and structured logging.
• Key handling: BYO keys, optional offline signing path; repo does not touch custody.
• Versioning: semantic tags on the repo; each example pinned to SDK versions to avoid drift.

Assumptions & prerequisites

• Access to public indexers or a node endpoint.
• Availability of at least two stable DEX SDKs with read/quote/swap support.
• Test wallet and keys for preview/testnet; optional CEX public ticker endpoint for paper mode.
• Node.js 18+ environment on CI and contributor machines.

Why this is feasible for us

• Lean scope: no new protocol, no validators, no packaged SDK, no backtester—just examples and tiny helpers.
• Existing building blocks: we assemble Dexter/DEX SDKs + CSL/indexers that already exist, minimizing unknowns.
• Experienced core: product and full-stack leadership with prior Cardano DeFi delivery (design, off-chain/on-chain integration).
• Trusted engineering partner for code review and best-practice patterns (performance, composability, testing).
• External creatives ensure docs and examples are clear and usable without heavy PM overhead.

Risks & how we contain them

• SDK/API churn → Pin versions; thin usage; CI integration runs to fail fast.
• Indexer rate limits/outages → Provider choice via .env, retry/backoff, small cache where allowed.
• DEX feature gaps → Start with two SDKs known to support needed calls; document any limitations.
• Security/user error → Dry-run by default, notional caps, explicit disclaimers, offline signing option.
• Scope creep → Clear non-goals: no simulators, no hosted services, no profit promises, no MEV/bridges.

What success looks like (capabilities in action)

• You can clone the repo, set .env, and fetch quotes within minutes.
• You can dry-run a guarded swap on preview/testnet the same day.
• You can copy a recipe to extend into your own prototype without touching low-level plumbing.
• Two DEXs shown end-to-end; five examples pass CI on each tag.
• Community adds at least one adapter or example via PR.

Maintenance feasibility

• Small surface area (a few examples + tiny helpers) keeps upkeep low.
• Apache-2.0 and neutral positioning encourage outside contributions.
• Clear folder structure and tests simplify review and regression checks.

Exit conditions & handoff

• If the project stops at v1, the repo remains fully usable: scripts pinned to SDK versions, tested Quickstart, and self-contained helpers.
• If adoption grows, adding a third DEX or extra recipe is incremental and documented.

Summary

We are not inventing new protocols or heavy infra. We are packaging working examples that responsibly compose existing Cardano DEX SDKs and on-chain data. The scope is tight, the risks are known, the team is capable, and the path to a useful v1 is short and realistic.

[Milestones] Project Milestones

Milestone Title

Repo & Baseline Quote Example

Milestone Outputs

• Public GitHub repo (Apache-2.0, NOTICE, CONTRIBUTING, issue templates).

• Basic folder layout: /examples, /lib, /docs.

• CI set up (lint, typecheck, unit tests) and passing.

• .env.example with provider options (Koios/Blockfrost/Ogmios/node RPC).

• Example 1: read pool state & compute quotes on one DEX (exact-in/out).

• Tiny in-repo helpers: asset/amount utils, min-UTxO/fee/TTL helpers.

• Docs: 5-minute Quickstart; how to run Example 1; safety defaults (dry-run).

Acceptance Criteria

• Repo is public; license headers present; CI badge green on main.

• npm install && npm run example:quote produces a quote on preview/testnet using .env.

• Example shows slippage math and best price across pools inside the same DEX.

• Quickstart page covers setup, env variables, and commands end-to-end.

Evidence of Completion

• Git tag v0.1.0 with release notes.

• Link to CI run for v0.1.0 (logs green).

• Screenshot or short screencast of Example 1 running (terminal output).

• Docs page URLs (Quickstart + Example 1).

Delivery Month

1

Cost

20000

Progress

20 %

Milestone Title

Guarded Swap & LP (Testnet) + Second DEX Quotes

Milestone Outputs

• Example 2: guarded swap on testnet (min-receive, TTL, notional caps, dry-run default; optional submit flag).

• Example 3: LP add/withdraw & position read on testnet (where SDK supports).

• /lib additions: datum decode helpers, UTxO filters, structured logging.

• Second DEX added for read/quote flows (execution remains optional).

• Docs updated: per-example guides; risk/safety caveats.

Acceptance Criteria

• npm run example:swap builds a tx; with --submit it submits to testnet and returns tx hash.

• npm run example:lp adds and withdraws a small test position on testnet (or dry-run with clear output if deposit not supported).

• npm run example:quote2 compares quotes across two DEXs and prints the better route.

• CI includes integration jobs that run Examples 2–3 in dry-run on each PR.

Evidence of Completion

• Git tag v0.2.0 + release notes.

• At least two testnet tx hashes (swap + LP) published in the release.

• CI logs showing integration jobs succeeded.

• Short screencast of swap dry-run and (optional) submit flow.

• Docs pages for Examples 2–3.

Delivery Month

2

Cost

25000

Progress

50 %

Milestone Title

Cross-DEX Watcher & CEX↔DEX Paper Check + Docs

Milestone Outputs

• Example 4: cross-DEX spread watcher (streams quotes from two DEXs; threshold alert hook).

• Example 5: minimal CEX↔DEX paper-mode price-check (uses public CEX ticker; notional caps & slippage bounds).

• Rate-limit/backoff and retry helpers where appropriate.

• “How to compose” docs tying Dexter/DEX SDKs + our helpers end-to-end.

• Configurable .env for thresholds, providers, pairs, poll interval.

Acceptance Criteria

• npm run example:watch logs spreads and emits alerts when spread > X%.

• npm run example:cex-dex-paper prints paired CEX/DEX quotes and paper actions (no custodial ops).

• Examples include sample configs and clear safety disclaimers.

• Docs contain diagrams or step lists for composing read → quote → guarded execute.

Evidence of Completion

• Git tag v0.3.0 + release notes with example command lines and sample logs.

• CI artifacts: recorded logs from watcher run (dry-run).

• Short screencast showing watcher triggering and paper check output.

• Published docs pages (“watcher”, “CEX↔DEX paper”).

Delivery Month

3

Cost

30000

Progress

90 %

Milestone Title

Hardening, CI Integration Tests & v1.0 Release

Milestone Outputs

• Integration test suite that runs all examples on preview/testnet in CI (dry-run by default).

• Dependency versions pinned; error handling and messages improved.

• Final docs polish: Quickstart, per-example guides, troubleshooting, CHANGELOG.

• v1.0.0 release with signed tag; simple “one-command run all” script.

• Announcement post in Cardano dev channels; call for adapter/recipe PRs.

Acceptance Criteria

• CI matrix runs npm run ci:examples and passes on main and v1.0.0.

• Docs build without errors; Quickstart verified by a fresh clone workflow.

• Release notes enumerate examples, environments, and known limitations.

• Repo includes SECURITY.md and clear disclaimers.

Evidence of Completion

• Git tag v1.0.0 with release notes and CHANGELOG.

• CI run links (unit + integration jobs green) and artifacts (logs).

• Final docs site link and a PDF/HTML export stored in the release assets.

• Links to two short announcement posts (e.g., Discord/Forum) and a summary thread.

Delivery Month

4

Cost

25000

Progress

100 %

[Final Pitch] Budget & Costs

Please provide a cost breakdown of the proposed work and resources

Total requested: 100,000 ADA (planned at ≈$0.75/ADA → $75,000).

Milestone-based payouts; amounts are fixed in ADA.

Assumptions (for transparency, not billing)

• Scope: one public repo with runnable examples + tiny helpers (no hosted services).

• Blended rates for planning (not invoicing): Engineering ~$100/h, Docs/DevRel ~$65/h, PM/Ops ~$70/h.

• Light infra (CI, small indexer plans) included under “CI/Infra”.

---

Overall allocation by category

| Category | % | ADA | USD est. |

|----------------------------------|-----|----------|----------|

| Engineering (dev + code review) | 72% | 72,000 | $54,000 |

| Documentation & DevRel | 10% | 10,000 | $7,500 |

| CI/Infra & release operations | 6% | 6,000 | $4,500 |

| PM/coordination/comms | 8% | 8,000 | $6,000 |

| Contingency (fees, slippage, misc)| 4% | 4,000 | $3,000 |

| Total | 100%| 100,000 | $75,000 |

Contingency covers indexer overages, test wallets, and unavoidable fees. If unused, it rolls into maintenance/issue fixes.

---

Why this is lean

• Reuses existing SDKs; spend goes to composition, runnable examples, and safety rails.

• No simulators or hosted services to fund.

• Milestones map directly to tangible outputs (tags, CI runs, docs pages).

If ADA/USD moves

• Budgets are denominated in ADA and do not change. USD figures are informative only.

[Final Pitch] Value for Money

How does the cost of the project represent value for the Cardano ecosystem?

Why this is efficient: We deliver a single Apache-2.0 repo of runnable Cardano DEX examples (plus tiny helpers, docs, CI). No hosted services, no simulators, no heavy SDKs to maintain. Spend goes almost entirely to hands-on engineering and documentation, gated by milestones.

Public-good leverage

• Every team currently rebuilds the same plumbing (reads, quotes, guarded swaps, LP). Our repo reduces duplicated effort across the ecosystem.

• Quick math: 5 runnable recipes for 100k ADA → ~20k ADA per recipe (includes docs, CI, helpers).

  If just 20 teams save 20 hours each at ~$100/h, that’s ~$40k saved; 50 teams → ~$100k. These are realistic, conservative scenarios for first-mile setup.

Unit economics & scope discipline

• Fixed ADA budget; USD estimate only for context (planned at ≈$0.75/ADA).

• Tight scope avoids expensive features (no backtester, MEV infra, or hosting).

• We compose existing SDKs (e.g., Dexter, protocol libs) rather than reinventing them.

Milestone-based accountability

• 4 milestones with concrete outputs (tags, CI runs, docs pages, testnet tx hashes).

• Payments only on delivery, reducing execution risk.

Reuse & longevity

• Apache-2.0 licensing enables commercial and open reuse with minimal friction.

• Small surface area (examples + tiny helpers) keeps maintenance cost low.

• Clear structure and CI encourage community PRs; benefits compound as adapters/examples are added.

Alternatives are costlier

• Each team crafting similar examples typically spends 1–2 engineer-weeks per flow (read/quote/swap/LP). Replicated across 10+ teams, that’s easily $150k–$300k+ in aggregate effort. Funding one high-quality, neutral repo is more economical and improves consistency/safety.

Transparent allocation

• Majority to engineering; the rest to docs, CI/infra, coordination, and a small contingency for fees/indexer overages. No marketing or non-essential overhead.

Bottom line: Minimal spend, maximal reuse. The project turns a recurring private cost (everyone rebuilds glue code) into a one-time public asset with clear, auditable outputs and a sustainable maintenance footprint.

[Required Acknowledgements] Consent & Confirmation

Terms and Conditions:

Yes