Onboarding: Intermediate lectures (+ runnable Aiken and Mesh examples)

docs/developers/onboarding/lectures/beginner/2-utxos-and-transactions.md

@@ -8,7 +8,7 @@ import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 import CodeBlock from "@theme/CodeBlock";
 import extractRegion from "@site/src/utils/extractRegion";
-import SendAda from "!!raw-loader!@site/examples/onboarding/lectures/mesh/src/send-ada.ts";
+import SendAda from "!!raw-loader!@site/examples/onboarding/lectures/beginner/mesh/src/send-ada.ts";
 
 # UTxOs & Transactions
 

docs/developers/onboarding/lectures/beginner/3-time-on-cardano.md

@@ -8,7 +8,7 @@ import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 import CodeBlock from "@theme/CodeBlock";
 import extractRegion from "@site/src/utils/extractRegion";
-import SendWithDeadline from "!!raw-loader!@site/examples/onboarding/lectures/mesh/src/send-with-deadline.ts";
+import SendWithDeadline from "!!raw-loader!@site/examples/onboarding/lectures/beginner/mesh/src/send-with-deadline.ts";
 
 # Time on Cardano
 

docs/developers/onboarding/lectures/beginner/4-native-scripts-and-metadata.md

@@ -8,8 +8,8 @@ import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 import CodeBlock from "@theme/CodeBlock";
 import extractRegion from "@site/src/utils/extractRegion";
-import NativeScript from "!!raw-loader!@site/examples/onboarding/lectures/mesh/src/native-script.ts";
-import SendWithMetadata from "!!raw-loader!@site/examples/onboarding/lectures/mesh/src/send-with-metadata.ts";
+import NativeScript from "!!raw-loader!@site/examples/onboarding/lectures/beginner/mesh/src/native-script.ts";
+import SendWithMetadata from "!!raw-loader!@site/examples/onboarding/lectures/beginner/mesh/src/send-with-metadata.ts";
 
 # Native scripts & metadata
 

docs/developers/onboarding/lectures/beginner/5-tokens-fungible-and-nfts.md

@@ -8,7 +8,7 @@ import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 import CodeBlock from "@theme/CodeBlock";
 import extractRegion from "@site/src/utils/extractRegion";
-import MintToken from "!!raw-loader!@site/examples/onboarding/lectures/mesh/src/mint-token.ts";
+import MintToken from "!!raw-loader!@site/examples/onboarding/lectures/beginner/mesh/src/mint-token.ts";
 
 # Tokens: fungible & NFTs
 

docs/developers/onboarding/lectures/beginner/introduction.md

@@ -42,8 +42,8 @@ From lecture 2 onwards you run real transactions on Cardano's free test network.
 You'll need **[Lace](https://www.lace.io/)** on the **Preview** network with a little test ADA, which is what [lecture 1](/docs/developers/onboarding/lectures/beginner/wallets-keys-addresses) sets up. Then grab the app (no need to clone the whole repo) and start it:
 
 ```bash
-npx giget@latest gh:cardano-foundation/developer-portal/examples/onboarding/lectures/mesh lectures-mesh
-cd lectures-mesh
+npx giget@latest gh:cardano-foundation/developer-portal/examples/onboarding/lectures/beginner/mesh beginner-mesh
+cd beginner-mesh
 npm install
 npm run dev
 ```

docs/developers/onboarding/lectures/intermediate/1-on-chain-vs-off-chain.md

@@ -0,0 +1,127 @@
+---
+title: "On-chain vs off-chain"
+sidebar_label: "On-chain vs off-chain"
+description: "What a dApp is made of, and the line between off-chain code that builds transactions and an on-chain contract that enforces the rules."
+---
+
+# On-chain vs off-chain
+
+Welcome to the Intermediate track. In Beginner you moved value around. Now you will make the chain **enforce rules** about how that value moves. That is a **smart contract**.
+
+## What a dApp is
+
+An app built on a blockchain is called a **dApp**, short for decentralized application. A few separate pieces make one up:
+
+- **A frontend**: the page people see and click.
+- **Off-chain code**: normally part of that same page. It reads the chain and builds the transactions.
+- **A [provider](/docs/developers/onboarding/lectures/beginner/providers-and-explorers)**: how the dApp reads the chain, and how it gets a finished transaction out to the network.
+- **A wallet**: holds the keys and signs. On the web it is usually a browser extension, like the Lace you installed in Beginner.
+- **A smart contract**: the rule the network enforces.
+
+You built the first four in Beginner, and **[a transaction, step by step](/docs/developers/onboarding/lectures/beginner/providers-and-explorers#a-transaction-step-by-step)** shows them working together. The smart contract is what this track adds.
+
+Two of those pieces do completely different jobs:
+
+- **Off-chain** is the code that runs **in your browser or on a server** (your app, plus an off-chain SDK). It reads the chain, **builds transactions**, and asks the wallet to sign them. This is the same work you did for the [send](/docs/developers/onboarding/lectures/beginner/utxos-and-transactions) and [mint](/docs/developers/onboarding/lectures/beginner/tokens-fungible-and-nfts) transactions in Beginner. It **prepares**.
+- **On-chain** is the **smart contract (logic) and data that lives on the blockchain**. A Cardano smart contract is code that runs on the blockchain and checks whether the transaction is allowed. It either **approves or rejects** the transaction. It **enforces**.
+
+The apps you built [in Beginner](/docs/developers/onboarding/lectures/beginner/introduction) had only off-chain code.
+
+Think of applying for a permit to build something. Your app is the person applying: it decides what it wants to build, fills in every field, and hands the form in. The contract is the officer who reads the form and either approves it or rejects it. The person can ask for anything, and the officer decides what is allowed.
+
+```mermaid
+flowchart LR
+    subgraph OFF["Off-chain: runs on your machine"]
+        App["your app + SDK<br/>builds the transaction"] --> Wallet["wallet<br/>signs it"]
+    end
+
+    subgraph ON["On-chain: runs on the network"]
+        Chain[("Cardano<br/>network")] -->|runs the contract| Validator{"validator<br/>yes / no"}
+        Validator -->|yes| Done["recorded on the chain"]
+        Validator -->|no| Rejected["rejected, nothing changes"]
+    end
+
+    Wallet -->|submits| Chain
+```
+
+As soon as the transaction is sent, control passes to the chain, and the validator makes the final decision. The contract cannot ask your app for more information, and your app cannot change the answer.
+
+## Who does what
+
+Split any Cardano app along that line and it becomes much easier to understand:
+
+| Off-chain (your server/browser) | On-chain (the network) |
+|---|---|
+| Read the chain: which UTxOs exist, what's locked where | - |
+| Decide what _should_ happen | Check whether it's **allowed** |
+| Pick the inputs, build the outputs, balance the fee | - |
+| Attach the datum and the redeemer | Read the datum and the redeemer |
+| Collect the wallet's signature | See which signatures are on the transaction |
+| Submit | Answer **yes** or **no** |
+
+Almost every line is on the left.
+
+## Why the split exists
+
+The chain has to reach the **same answer for everyone, forever**. A node checking your transaction today and a node checking that same block ten years from now must both decide the same way. If they did not, they would disagree about who owns what. So a contract may only look at things that are **written down**: the transaction itself, the outputs it spends, and the validity window it declares.
+
+That single requirement explains most of what feels strange at first:
+
+- **A contract cannot call an API**, read a price feed, or fetch anything. Two nodes asking the same server could get two different answers.
+- **A contract cannot read a clock.** This is why time became a **slot window** that you declare in advance, back in [Time on Cardano](/docs/developers/onboarding/lectures/beginner/time-on-cardano).
+- **A contract keeps no variables of its own between runs.** This does not mean nothing is saved. On Cardano, state lives **on the UTxOs** rather than inside the contract, and everything the validator needs to know must reach it through the transaction context. The next two lectures show how.
+- **A contract cannot start anything.** Nothing on Cardano happens because a contract decided to act. Someone has to build a transaction first.
+
+You get something valuable in return: your transactions are **deterministic**. A validator only ever looks at information that is local to the transaction and cannot change once it is written, so running it twice gives the same answer twice, on your machine and on every node. That is why your app can run the contract before sending anything, and know whether the contract approves the transaction and what running it will cost.
+
+That is a promise about the **contract's answer**, not about the transaction getting in. Somebody else may spend the same UTxO first, and then the ledger refuses yours before the contract is even consulted. So the guarantee is: **if** your transaction is accepted, it does exactly what you predicted. Not that it is certain to be accepted.
+
+There is a practical reason for the split as well. Everything on-chain is stored by every node and re-checked forever, so moving the transaction building there too would grow the chain faster than most people could afford to keep up with, and a chain only a few can verify is not decentralized.
+
+## Where the contract runs, and what it can do
+
+**The contract does not run on your computer.** You write it, compile it, and read it in your editor, so it is easy to think of it as part of your app. Your app carries the compiled contract **inside the transaction**, and the **network** runs it when that transaction is checked. The answer is the same for everyone, forever.
+
+**The contract cannot _do_ anything.** Every movement of value in this track is done by a **transaction your off-chain code built**. All the contract ever adds is a yes or a no.
+
+## Try it
+
+**Make the folder you will work in for the rest of the track:**
+
+```bash
+mkdir cardano-vault
+cd cardano-vault
+mkdir on-chain
+mkdir off-chain
+```
+
+:::note Which terminal, and where you are
+These commands work as written on macOS and Linux, and in **PowerShell** on Windows. If you use the older Windows `cmd` prompt, one command later in the track differs: `rm` is `del`.
+
+If a command ever answers **"no such file or directory"**, run `pwd` and check which folder you are standing in.
+:::
+
+```
+cardano-vault/
+├── on-chain/      <- the rules. Compiled, hashed, enforced by every node.
+└── off-chain/     <- the app. Runs on your machine and builds transactions. Enforces nothing.
+```
+
+The next lecture puts a contract project in `on-chain/` and leaves you working inside it. `off-chain/` stays empty until **[frontend integration](/docs/developers/onboarding/lectures/intermediate/frontend-integration)**, which is the one place in the track you change folder again.
+
+Keep the name or pick your own, and read `cardano-vault/` as "wherever you put it".
+
+Code in `off-chain/` can be wrong, or replaced. The network does not care, because it checks every transaction against what is in `on-chain/`.
+
+For the vault you are about to build, the split runs like this. Off-chain builds a transaction that sends ADA to the contract's address, which locks it. Later, off-chain builds a second transaction that tries to spend it back, so on-chain, the validator runs and answers yes or no, and only a "yes" allows the spend.
+
+Stuck? The finished code is in the playground. See the **[introduction](/docs/developers/onboarding/lectures/intermediate/introduction#the-playground)**.
+
+## Go deeper
+
+- [Smart Contracts (overview)](/docs/developers/curriculum/smart-contracts/overview): the on-chain/off-chain split in full.
+- [Lock and Spend](/docs/developers/curriculum/smart-contracts/lock-and-spend): the lock-then-spend flow end to end.
+- [Cardano for Ethereum developers](/docs/developers/cardano-for-ethereum-developers): the account-model habits that don't carry over: no `msg.sender`, no contract storage, no execution order.
+- [The Extended UTXO Model](/docs/developers/curriculum/fundamentals/core-concepts/eutxo): the ledger model that makes this split possible.
+
+Next: **[Set up your tools](/docs/developers/onboarding/lectures/intermediate/tools)**.

docs/developers/onboarding/lectures/intermediate/2-tools.md

@@ -0,0 +1,106 @@
+---
+title: "Set up your tools"
+sidebar_label: "Set up your tools"
+description: "The compiler for the on-chain half, and the contract project everything else in this track fills."
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Set up your tools
+
+The on-chain half needs a **compiler and supporting tooling**, because a contract has to become a program the network can run. The off-chain half needs a **library, a provider, and a way to interact with a wallet**, because your app has to read the chain, build transactions, get them signed, and submit them.
+
+**You only need the first set now.** The next six lectures are the contract and nothing else: you write it, compile it and test it. The off-chain half then arrives all at once in **[frontend integration](/docs/developers/onboarding/lectures/intermediate/frontend-integration)**.
+
+## The on-chain toolchain
+
+You write the contract in a high-level language and **compile** it into the code the network runs. Several languages do this for Cardano:
+
+- **[Aiken](https://aiken-lang.org/)** is a language made from scratch to write Cardano contracts. It is a small language with a fast compiler and built-in tests, and it is the easiest place to start.
+- **[Scalus](https://scalus.org/)** lets teams who already use Scala write contracts in the language they know.
+- Others exist for Haskell, Python and TypeScript teams. The [handbook compares them](/docs/developers/curriculum/smart-contracts/choose-a-language), and **[Builder Tools](/tools)** lists them all.
+
+They all compile to the same low-level program, and they all describe it in the same file format, the **CIP-57 blueprint**. Your off-chain code reads that file and never needs to know which language made it.
+
+## The off-chain toolchain
+
+**The SDK** builds Cardano transactions for you. Without one, every transaction would cost you a lot of time and a lot of code. There are SDKs for JavaScript, Python, Haskell, Java, Go and more, and **[Builder Tools](/tools)** lists them all.
+
+Nothing in these lectures depends on the one you pick: the contract is the same, the transaction is the same, only the function names change. Every code block that needs an SDK sits in a tab, so you can read the track in whichever one you use, and more will be added over time.
+
+**The provider** reads the chain for you and submits your transactions because your app cannot reach the network on its own unless you run your own Cardano node. Beginner used one already. This track leans on it harder, for two reasons:
+
+- **You read UTxOs that are not yours.** Locked funds sit at a contract's address. Your wallet knows nothing about them, so the provider is the only way to find them.
+- **A script transaction has to declare its cost.** Running a validator uses CPU and memory, and the transaction carries the budget it expects to use, written next to the redeemer. You also pay for that budget in the fee. So something has to run the contract first, against your unsigned transaction, to find the real number. Your SDK can do that on your machine, or hand the job to a provider that offers it. Either way the answer arrives before you send anything, which is why a contract that says no usually fails in your app rather than on the chain.
+
+You made a free **[Blockfrost](https://blockfrost.io/)** Preview key during setup. Others are listed in **[Builder Tools](/tools)**, and some of them you can run yourself.
+
+**The wallet** holds the keys and signs. Your app never sees a private key: it hands the finished transaction to the wallet, the wallet asks the user, and the user approves. Here that is **[Lace](https://www.lace.io/)** on Preview.
+
+Keep your Blockfrost key and your Lace wallet where they are. Neither is touched again until **[frontend integration](/docs/developers/onboarding/lectures/intermediate/frontend-integration)**, which sets all three of these up in one go.
+
+## Try it
+
+**Set up the contract project.** No contract in it yet, **[the next lecture](/docs/developers/onboarding/lectures/intermediate/what-is-a-validator)** writes that.
+
+<Tabs groupId="onchain">
+<TabItem value="aiken" label="Aiken" default>
+
+Install Aiken from the **[installation guide](https://aiken-lang.org/installation-instructions)**. It takes about a minute. Then build the contract project **inside the on-chain half**, so it lands where it belongs instead of being moved there afterwards:
+
+```bash
+cd on-chain
+aiken new my-name/vault
+cd vault
+```
+
+`aiken new` creates the folder in whichever folder you run it from, and fills it with a working project: `aiken.toml` for the settings and dependencies, and `validators/` for your contracts. "Smart contract" is the general word, and the thing you actually write is a **validator**, which is why that folder has the name it does. **[The next lecture](/docs/developers/onboarding/lectures/intermediate/what-is-a-validator)** writes your first one. The name is `{organisation}/{repository}`, the same form as the dependencies you will add later, so `my-name/` is a label you can set to anything and `vault` is what the project is called.
+
+Aiken's commands run in the project you're in, so the next six lectures all run from inside `on-chain/vault/`.
+
+`aiken new` leaves a sample validator behind. You do not need it, and it would end up in your compiled output, so delete it:
+
+```bash
+rm validators/placeholder.ak
+```
+
+Check that the project works:
+
+```bash
+aiken check
+```
+
+It compiles and reports `0` tests, because the project is empty.
+
+</TabItem>
+<TabItem value="scalus" label="Scalus">
+
+A [Scalus](https://scalus.org/) version is coming soon. The idea is identical, only the tooling differs.
+
+</TabItem>
+</Tabs>
+
+Your workspace:
+
+```
+cardano-vault/
+├── on-chain/
+│   └── vault/            <- you are here, and stay here until lecture 9
+│       ├── aiken.toml
+│       └── validators/   <- your contracts
+└── off-chain/            <- still empty, filled in lecture 9
+```
+
+Stuck? The finished code is in the playground. See the **[introduction](/docs/developers/onboarding/lectures/intermediate/introduction#the-playground)**.
+
+## Go deeper
+
+- [Choose a Smart Contract Language](/docs/developers/curriculum/smart-contracts/choose-a-language): Aiken, Scalus and the rest, and why they all compile to the same core.
+- [Choose your tools](/docs/developers/curriculum/start-building/choose-your-tools): how to pick an off-chain library.
+- [Builder Tools](/tools): every SDK, library and API on the portal.
+- [Use a provider](/docs/developers/curriculum/production/use-a-provider): hosted, self-hosted, and local options.
+- [Query the chain](/docs/developers/curriculum/start-building/query-the-chain): reading addresses, UTxOs and datums.
+- [Testing](/docs/developers/curriculum/smart-contracts/testing): unit tests, property tests, and how far you can get before touching a chain.
+
+Next: **[What a validator is](/docs/developers/onboarding/lectures/intermediate/what-is-a-validator)**.