A hands-on onboarding flow for the Cardano Developer Portal

[paulobressan]

Discussed in #1885

^{Originally posted by paulobressan July 10, 2026}

A hands-on onboarding flow for the Cardano Developer Portal

This is a discussion proposal. It covers the what and the why, not the how. The
implementation is left open on purpose so contributors can shape it. Feedback welcome.

Context & problem

The portal was recently restructured into a 7-module curriculum (Fundamentals, Start Building,
Tokens/NFTs, Staking & Governance, Smart Contracts, Build a dApp, Ship to Production). The docs are
good and thorough.

That thoroughness is also the friction. If you show up with a concrete goal ("I just want to mint an
NFT", "how do I accept ADA payments?"), the curriculum reads like a textbook you're expected to work
through in order. The homepage cards (Smart Contracts, Native Tokens, Integrate Payments, Transaction
Metadata…) all send you to a module overview page, which is more reading before you get to do
anything. There's no fast, guided, do-it-now path.

Goal

An onboarding flow that keeps new developers moving from one section to the next instead of giving up
partway through. In each section, you don't just read the theory, you run it and
get a real result back. When you learn a new programming language/framework/tool, the thing that keeps you going is
watching your own code actually work. We want that same feeling here. Every step ends in something
concrete, and each small win is what makes you want to start the next one.

The idea

Add an onboarding section, separate from the deep curriculum, organized into tiers (Beginner,
Intermediate, Advanced, Expert). Each tier is a handful of use-cases that teach Cardano by explaining
and running real code. Beginners get momentum right away, and the curriculum/deep-dives stay as the reference
you graduate into once you want the full detail.

---

The onboarding flow

The flow orients the developer, gets their environment up and running, and then guides them through the tiers.
Each part below is a section we'd build. The specifics of how each lesson is written are for later.

Introduction

A short "what is Cardano and how should I think about it", enough to set the mental model without
turning into a wall of text. It would introduce the eUTxO model (value and state live in UTxOs, not
account balances) and native tokens as first-class assets, and set the expectation for what the
developer will have built by the end of the tiers.

Ecosystem

A quick map of what's out there before the developer picks tools, so they aren't choosing blind:

• Tools. The portal already catalogs the ecosystem by category (SDKs & Libraries, APIs &
  Providers, Indexers & Data, Nodes & Clients, Wallets, Dev Environments, and so on). Onboarding
  points at that rather than re-explaining it.
• Indexers & data. How you read the chain, from hosted providers (Blockfrost, Koios, Maestro)
  that need no infrastructure to self-hosted options (Kupo, Dolos, Oura, cardano-db-sync, Ogmios)
  for full control.

Environment

Getting to a working setup quickly, so the developer can actually run the lessons. This would cover
cardano-init, connecting to a public test network and getting test ADA from the faucet,
and connecting a CIP-30 browser wallet. The goal is that by the end of this section, they have
everything installed to complete the first tier.

Quick Start

An e2e example that makes the developer feel they can accomplish a lot with very little effort. E.g, creating a fully functional Escrow DApp, but instead of explaining everything and going step by step, we provide the steps mechanically in an easy-to-perform way. The developer won't understand the why behind what they just did, but they'll have a fully functional DApp in an hour or two and get a rough feel for the parts involved and how they connect. The main objective of the e2e project is to entice the student to learn more. To make them feel that "building on Cardano is easy".

Tiers

The heart of the proposal. Each tier is a set of use-cases, and each use-case is one short lesson that
ends in a result the developer can see and verify. They can be worked in order or picked individually.

Beginner

• Connect a wallet (CIP-30)
• Send your first transaction
• Mint a fungible token (FT)
• Mint a non-fungible token (NFT)
• Attach metadata on-chain

Intermediate

• Multisig transactions (shared control, multiple signers)
• Native scripts (time locks and key combinations, without Plutus)
• Watch blockchain events (react when a payment arrives)
• ...

Advanced

• Write your first smart contract (validate on-chain, then lock and spend funds from it)
• Follow-ons such as vesting, parameterized and reference scripts, and generating typed off-chain
  clients from a contract's blueprint
• ...

Expert (use-cases projects)

At this point, the developer can write a validator and spend from it. Expert is about building a whole
dApp and running into the problems production teams actually deal with: UTxO concurrency, off-chain
infrastructure, oracles, scaling, and privacy. Each capstone maps to a real open project they can
study, run, and extend.

• Build an NFT marketplace — listings, buys, and cancels encoded in datums, an off-chain indexer to serve the frontend.
  Covers the full on-chain and off-chain loop.
• ...

---

What one lesson looks like

The value of the onboarding is in keeping every lesson to the same simple shape:

1. Goal — one sentence on what you'll have when you're done.
2. Try it — a short piece of code to run against a test network or a local devnet.
3. See the result — a tx hash to open in an explorer, a token in your wallet, an event your app
   reacted to. Always something concrete you can verify.
4. Go deeper — a link to the matching curriculum page for the full theory, plus a next step.

The result step is what makes this work. Reading about a transaction is easy to forget, submitting one
and watching it confirm is not. Over time, the "Try it" step could become fully interactive, running
against a bundled devnet and eventually an in-browser playground, so there's no setup between a
beginner and their first success.

---

Homepage

The homepage should invite a newcomer to do something rather than to start reading.

1. Hero
   • Add a Docs button that goes to the 7-module curriculum, for people who want the reference.
   • Repoint Start Here to the new onboarding flow, for people who want to build now.
2. Use-cases instead of topic cards
   • Replace the generic cards ("Transaction Metadata", "Native Tokens") with projects a newcomer
     actually wants to build, each of which pulls them through the relevant onboarding steps. For
     example: Build an NFT marketplace, Build a DEX, Build an auction, Build a crowdfunding app,
     Build an escrow, Build a wallet dApp.
   • The current topic cards can move below this section or into the menu. They stay available, just
     not as the front door.

---

Build on the curriculum, don't replace it

The onboarding is a fast lane on top of the existing docs, not a rewrite. The curriculum stays the
source of truth, and every onboarding step links back into it for depth. New developers get momentum,
and the full material is one click away when they want it.

---

[rober-m]

Mostly agree. Here are some thoughts:

I think we should split the homepage/landingpage section into another issue or make it a sub-issue cause it's slightly tangential. As long as the main hero points to this onboarding, the rest pertains to a parallel discussion. But agree on the overall idea that it needs to point to more relevant places.

A quick map of what's out there before the developer picks tools

Yes. But with strong guidance. Newcomers still lack context, so even if we explain what each tool does, they'll struggle with choosing. So, we should mention that X and Y tools are the most widely used for the Z category, which is why they are among the first options in the code snippets table (see #1738, point 3: Make content tool-agnostic where possible).

Each tier is a set of use-cases, and each use-case is one short lesson that ends in a result the developer can see and verify. They can be worked in order or picked individually.

Yes! 100%!

Beginner
...
Intermediate
...
Advanced
...
Expert (use-cases projects)
...

Agree, we need some way to manage the complexity by adding clear difficulty levels to the onboarding process. I'm not sure about the chosen lessons/content. I think we can do better. However, by past experience, I'm aware that defining a full outline and then sticking to it is virtually impossible. While working on the content, we'll realize that our original outline needs to be modified, which in turn will affect other lectures. I think we should draft a rough outline and then iterate on it as we create the content.

For example:

Quick start (First e2e DApp)

• Introduction to the tools + quick overview (What is a DApp, smart contract, Aiken, MeshJS, etc. Very high-level.)
• Set up the development environment (e.g., run cardano-init --on-chain aiken --off-chain meshjs and install a browser wallet)
• Modify on-chain to have Escrow
• Modify off-chain to have Escrow
• Integrate with Frontend/Backend

Beginner

Lecture 1 (Intro to blockchain. EVM devs can skip):

• Intro to Blockchains, Txs, Blocks, Nodes, and Wallets

Lecture 2 (setup env + UTxO + First Txs)

• UTxO Model overview
• Create a Tx with a wallet and inspect it with a chain explorer
• On-chain vs Off-chain

Lecture 3 (First off-chain transactions + Native Scripts. NS could be separate or optional)

• Intro to X off-chain library and creating your first Tx
• (E)UTxO Model
• Create a Tx with a Datum and inspect it with a chain explorer

Lectrue 4 (Native Scripts + Native Tokens)

• Native Scripts
• Create and run a Multisig script
• Create and run a Vesting script
• Native Tokens
• Mint/Burn Tokens

Lecture 5 (First on-chain validators)

• Create a new on-chain library Y project (e.g., cardano-init --on-chain Y)
• Go over project structure and use the docs
• Introduction to Plutus Validators
• "Always true/false" validator + off-chain
• "redeemer == 42" validator + off-chain
• "redeemer == datum" validator

Lecture 6 (Accessing the script context and time in Plutus)

• ScriptContext
• "Consume if signed by" validator (solve the exercise after 15 min)
• Time in Plutus validators
• "Vesting" validator

Lecture 7 (Parameterized validators + NFTs)

• Parameterized Validators
• Parameterized "Vesting" validator
• Minting Policies
• MP: "Mint if signed by"
• MP: "Mint if signed by & Token Name"
• MP: NFT

Lecture 8 (Reference Scripts + Reference inputs + Oracle (combining mint and spend in a protocol))

• Multi Scripts + Ref Inputs + Ref scripts
• Building a centralized Oracle

Lecture 9 (Testing)

• Testing on-chain functions
• Testing state transitions
• Common vulnerabilities
• Fixing a vulnerable protocol

Intermediate

Lecture 1

• Common patterns (beacon token, validate transaction, etc.)
  ...

Advanced

Lecture 1

• Benchmarking

Lecture 2

• Optimizing your contracts (encodings, don't calculate; validate, etc.)

Lecture 3

• L2s and sidechains

Lecture 4

• ZK

Lecture 5

• Next steps

This is just one possible alternative. We can change it. However, if we do it this way, I'd argue we shouldn't go much beyond what the "Advanced" lectures cover. After that, a developer should be able to figure things out on their own.

The value of the onboarding is in keeping every lesson to the same simple shape:

Looks good. I think we can roughly keep this structure, but we shouldn't constrain ourselves to the format when it doesn't fit. I think the "Try it" part in particular may vary a lot.

Build on the curriculum, don't replace it

I'd replace the curriculum. At least, by name. The "curriculum" will compete conceptually with the "course". I think we should take the information there and transform it into stand-alone "source of truth" pages (if needed) and either remove the /curriculum path or replace it with our onboarding.

@paulobressan @0xBora wdyt?

[rober-m]

We also have to add interactions with:

• Existing Oracle networks (Pyth)
• Stablecoins
• Other Pentad integrations

[paulobressan]

Yes, it is better to open a new issue for the landing page.

The content in the curriculum is good, so I agree with changing and improving it to be the source of truth and using it for deep learning.

I liked the format of the lectures 🤩. New users will have a nice journey through the Cardano ecosystem, using the available libs and tools like indexers, event pipelines, etc.

[paulobressan]

Some of the lessons will include code snippets, and those can break over time as the libraries and the chain get updated. So I've been thinking about how to keep them working, not just at the moment they're written. The idea is to keep the snippets as a real project inside the docs repo, so we can write tests for it and set up CI to run them on a schedule, and then import the code into the docs instead of pasting it. I've checked the current docs framework and we can use Docusaurus built-in code-import support for this https://docusaurus.io/docs/markdown-features/react#importing-code-snippets

[rober-m]

Based on a meeting with @paulobressan, we'll switch the E2E example from Escrow to Atomic Swap

[paulobressan]

This is the proposal for the lecture modules. The idea is not to dive too deeply into technical details, but rather to show how Cardano works. Newcomers will be able to complete the modules quickly and start building projects on Cardano. Whenever in-depth information is needed, users can refer to the handbook (the current curriculum) @rober-m

Beginner, the base of Cardano

Goal: the concepts you need before building anything, each with an analogy and a hands-on step. After this you understand Cardano infrastructure (wallets, UTxOs, transactions, tokens) and how to read the chain.

• Wallets, keys & addresses
  Wallet = account + identity (it holds your keys, not your coins), a key signs, an address is like an "email" for money(tokens).
  Try it: create a Preview wallet, fund it from the faucet, see it on the explorer.

• UTxOs & transactions
  UTxOs are the individual bills and coins in your wallet, a transaction spends whole bills and gives change (the eUTxO model).
  Try it: make a transaction using the wallet and open it on the explorer and read its inputs/outputs. Also, open the funding transaction on the explorer.

• Tokens: fungible & NFTs
  Native tokens (policy id + name), no smart contract needed, fungible = interchangeable (like dollar bills), NFT(non fungible token) = a unique token (can be a numbered ticket, an art)
  Try it: view a token on the explorer, or mint one via the Tutorial.

• Metadata & native scripts
  Metadata = a data(text, anything) attached to a transaction that can explain this transaction, native scripts = simple rules (multisig, time-locks) with no smart contract.
  Try it: read a transaction's metadata, reason about a native-script JSON.

• Providers & explorers
  A provider is a hosted API your app calls (Blockfrost) that is required to build an dapp and read the chain… an explorer is a search engine for people (Cardanoscan). Also mention the off-chain SDKs you'll build with, Mesh and Evolution (TypeScript)
  Try it: look up the same address two ways, a Blockfrost curl and the explorer.

---

Intermediate, smart contracts

Goal: teach smart contracts from scratch, building on the Beginner base (transactions, UTxOs, tokens). After this you can write and understand a smart contract. Keep it simple, reuse the Beginner analogies.

• On-chain vs off-chain
  Every Cardano app has two halves: on-chain = the smart contract that lives on the blockchain and enforces the rules; off-chain = the code on your computer or server that builds transactions and asks the wallet to sign. Explain both and the difference (the app prepares, the chain enforces).
  Try it: trace one transaction through both halves.

• What a smart contract is (the validator)
  A smart contract is a validator (a small yes/no function the network runs when someone tries to spend a locked UTxO. It never moves funds itself; it only approves or rejects) or a set of validators that work together.
  Try it: write a tiny validator (always true, always false) and predict its answer.

• Datum & redeemer
  The datum is information/notes attached to a locked UTxO (the terms). The redeemer is the choice the spender makes (which action). Together with the transaction context, that's everything the validator gets to see.
  Try it: Build a smart contract that checks if Datum > Redeemer.

• Validator purposes: spend, mint, withdraw…
  One validator can guard different things: spend (unlock a UTxO), mint (create/burn tokens), withdraw (stake rewards), and more (publish/vote). Same idea, different trigger.
  Try it: match each purpose to a real action.

• On-chain tools: Aiken & Scalus
  The languages you write validators in, Aiken (purpose-built and friendly) and Scalus (Scala). Both compile to the same on-chain format (plutus.json).
  Try it: compile a validator with aiken check / aiken build.

• Off-chain SDKs: Mesh, Evolution and Tx3
  The TypeScript libraries that build the transactions your contract needs (lock, spend, mint) and hand them to the wallet. Mesh, Evolution, Tx3.
  Try it: build a lock/spend transaction with an SDK (or follow the Tutorial)

• Handling time in Cardano (Vesting)
  How we think about time in Cardano is different from real life time. To explain time on cardano, we will teach the user through a real example vesting.

• Multi validators (Giftcard)
  Explain how to use multiple validators together

• Modifying state (Oracle)
  Explain how to make state transitions to change data on a utxo

• Reference Input & Ref. Script (Deploy and consume from Oracle)
  Explain ref script and deploy oracle. After that, consume information from another validator using ref input.

• Testing
  Tracing, unit tests, property-based tests, and offline/headless scenario tests, so "what you read is what is tested."
  Try it: run and extend a test suite.

---

Advanced, high-quality smart contracts

Goal: go from "it works" to "it's safe and production-ready." After this you can write secure, high-quality smart contracts. Keep explanations simple even for the hard topics.

• Common vulnerabilities
  The classic ways contracts get exploited, double satisfaction, unauthenticated UTxOs, unbounded value/inputs, and how to defend against each.
  Try it: spot the bug in a vulnerable validator.

• Design patterns
  Reusable structures that keep contracts correct and efficient, UTxO indexers, state machines, tx-level minting, reference inputs.
  Try it: apply one pattern to a small contract.

• Optimization
  Keep scripts small and cheap, execution units, script size, min-ADA, verify, don't compute.
  Try it: measure a validator's cost and shrink it.

• Higher assurance: audits & formal verification
  When and how to get external review and mathematical guarantees on a contract before it holds real value.

• Going to production
  Providers and infrastructure, deployment, and monitoring a live contract.

[rober-m]

Lgtm. To put in writing what we talked about: The tools referenced will be the first implementations of the explained lecture, but all lectures will be tool agnostic and explanations/code for specific tooling with be guarded by Tabs to select them.

[0xBora]

Aligned with the general direction here.

I think what this ends up pointing to, and you both already touched on it, is that the current curriculum would need to become more of a general knowledge layer than a sequential course as it was trying to be both the knowledge layer and the onboarding flow at the same time.

Everything relevant to application layer development on Cardano still needs to find a home under the knowledge layer there under a taxonomy that is scoped well and tries to be comprehensive, and then the opinionated things (this onboarding flow) sit on top of it. This onboarding flow first, and later cookbooks, tutorials, or guides written for a specific audience. For example the onboarding flow can refer to the deeper dives in the knowledge layer as further reading. The knowledge layer can't really do both jobs, it can't house everything an application developer might need and at the same time optimize itself down to only what a newcomer needs to get going, so I don't think we are forcing a split here, it kind of falls out on its own.

I don't think we need to write that down as a rule anywhere. It's more that if the flow keeps that differentiation in mind and makes it visible in how it presents itself, whoever picks up work in this area later has an easier time knowing which side they are on. And overlap between the two is fine, the flow is supposed to simplify and then link down for depth, which is what the "Go deeper" step is already doing.

I think the same thing answers the snippet question. The runnable code with tests and CI, like Paulo describes, would live with the onboarding flow, and the knowledge layer stays concept first with potentially illustrative code behind the tool Tabs. That way we only maintain end to end projects in one place.

On the tiers, the modular shape works for me and is easy to digest. One thing I'd add for the lessons themselves, where it fits naturally, is showing where the surrounding suggested Cardano tooling sits in the journey. cardano-init in the environment section, the contract library when a use case lines up with one, the AI tooling for agent assisted workflows, how to use certain fundamental tools like a data node/indexeer etc..

If lessons shows how those come together, people reach for them while building instead of finding them much later and the devex improvement proposals outputs will be more clearly visible as people get onboarded into Cardano with these tools as a default kit they can always rely on.

Looking forward to the next sections, happy to review as they land.

[neonflux-io]

Hi @paulobressan, I’d be interested in contributing to the new Cardano onboarding flow. I have experience with TypeScript, Web3, smart contracts, wallets, testing, and developer tooling.

I’d be happy to take a focused lesson or runnable example—such as CIP-30 wallet connection, transactions/UTxOs, native tokens/NFTs, or off-chain integration—and include tested code that can stay validated through CI.

Let me know which section currently needs another contributor.