From e4cc58e8c35517e9c864ccd16a7ab781fbde5634 Mon Sep 17 00:00:00 2001 From: TheNewAutonomy Date: Wed, 4 Mar 2026 08:56:47 +0000 Subject: [PATCH] docs: add user-first use cases and quickstart entrypoint - Add new Use cases section (send money, games/assets, social, plain-English overview) - Add quickstart for using apps - Reframe homepage/entry points toward everyday users - Add no-build path for node operators (release binaries) - Add builder-facing notes to keep non-builders out of RPC internals Made-with: Cursor --- site/docs/index.md | 3 +- .../node-operators/install-build-binaries.md | 22 ++++- site/docs/node-operators/run-a-node.md | 32 +++++-- site/docs/quickstarts/i-want-to-use-apps.md | 46 ++++++++++ .../quickstarts/i-want-to-use-the-wallet.md | 12 ++- .../rpc-reference/transaction-lifecycle.md | 6 ++ site/docs/sdk/get-started.md | 10 +++ site/docs/use-cases/_category_.json | 10 +++ site/docs/use-cases/games-assets.md | 58 +++++++++++++ .../use-cases/how-it-works-plain-english.md | 66 ++++++++++++++ site/docs/use-cases/send-money.md | 86 +++++++++++++++++++ site/docs/use-cases/social-you-control.md | 47 ++++++++++ .../src/components/HomepageFeatures/index.tsx | 30 +++++-- site/src/pages/index.tsx | 6 +- 14 files changed, 411 insertions(+), 23 deletions(-) create mode 100644 site/docs/quickstarts/i-want-to-use-apps.md create mode 100644 site/docs/use-cases/_category_.json create mode 100644 site/docs/use-cases/games-assets.md create mode 100644 site/docs/use-cases/how-it-works-plain-english.md create mode 100644 site/docs/use-cases/send-money.md create mode 100644 site/docs/use-cases/social-you-control.md diff --git a/site/docs/index.md b/site/docs/index.md index d5640c9..df758c2 100644 --- a/site/docs/index.md +++ b/site/docs/index.md @@ -4,10 +4,11 @@ sidebar_position: 1 # Catalyst documentation hub -This site is the single docs home for the Catalyst ecosystem. +This is the public documentation hub for the Catalyst ecosystem. ## Choose your path +- **Everyday users**: start with **[Use cases (for everyone)](/docs/use-cases/send-money)** or **[Quickstart: use Catalyst apps](/docs/quickstarts/i-want-to-use-apps)**. - **Node operators**: start with **[Run a node](/docs/node-operators/run-a-node)**. - **Wallet users**: start with **[Use the wallet](/docs/quickstarts/i-want-to-use-the-wallet)**. - **dApp builders**: start with **[Deploy a contract](/docs/quickstarts/i-want-to-deploy-a-contract)**, then **[RPC: transaction lifecycle](/docs/rpc-reference/transaction-lifecycle)**. diff --git a/site/docs/node-operators/install-build-binaries.md b/site/docs/node-operators/install-build-binaries.md index 7bdaf28..b07375e 100644 --- a/site/docs/node-operators/install-build-binaries.md +++ b/site/docs/node-operators/install-build-binaries.md @@ -5,12 +5,28 @@ title: Install / build binaries ## You will need -- Rust toolchain (for source builds) -- Linux build dependencies (RocksDB, OpenSSL, toolchain) +- Linux host +- Either: + - a **release binary** (no build), or + - a Rust toolchain + build dependencies (source build) ## Steps -### Build from source (recommended) +### Option A (recommended): download a release binary (no build) + +If you want to run a node without compiling anything, use a published release. + +1) Go to the releases page and download the latest `catalyst-cli` for Linux. + +- Node repo releases: `https://github.com/catalyst-network/catalyst-node-rust/releases` + +2) Verify the checksum (recommended) and install the binary somewhere stable, for example: + +```bash +sudo install -m 0755 catalyst-cli /usr/local/bin/catalyst-cli +``` + +### Option B: build from source ```bash git clone https://github.com/catalyst-network/catalyst-node-rust diff --git a/site/docs/node-operators/run-a-node.md b/site/docs/node-operators/run-a-node.md index ee9f6a4..cbd9499 100644 --- a/site/docs/node-operators/run-a-node.md +++ b/site/docs/node-operators/run-a-node.md @@ -19,18 +19,34 @@ Running a public node is operationally risky. Treat the host as production infra - Linux host (Ubuntu/Debian examples below) - Open TCP **30333** (P2P). Open **8545** (RPC) only if you know what you’re doing (prefer IP allowlist / SSH tunnel). -- Build deps (for source builds): `build-essential`, `clang`, `cmake`, `libssl-dev` +- Either: + - a **release binary** (no build), or + - build deps (for source builds): `build-essential`, `clang`, `cmake`, `libssl-dev` ## Steps -### 1) Install build dependencies (Ubuntu/Debian) +### 1) Get the binary (no-build or source-build) + +Choose one: + +- **No build (recommended)**: download a `catalyst-cli` release binary + - `https://github.com/catalyst-network/catalyst-node-rust/releases` +- **Build from source**: continue with the steps below + +If you downloaded a binary, install it to a stable path used by systemd, for example: + +```bash +sudo install -m 0755 catalyst-cli /var/lib/catalyst/node/catalyst-cli +``` + +### 2) Install build dependencies (Ubuntu/Debian) (source builds only) ```bash sudo apt update sudo apt install -y build-essential pkg-config libssl-dev clang libclang-dev cmake ``` -### 2) Build the node +### 3) Build the node (source builds only) ```bash git clone https://github.com/catalyst-network/catalyst-node-rust @@ -52,7 +68,7 @@ The binary is: ./target/release/catalyst-cli --help ``` -### 3) Create a dedicated user + directories +### 4) Create a dedicated user + directories ```bash sudo useradd --system --create-home --home-dir /var/lib/catalyst --shell /usr/sbin/nologin catalyst || true @@ -61,7 +77,7 @@ sudo chown -R catalyst:catalyst /var/lib/catalyst sudo chmod 700 /var/lib/catalyst ``` -### 4) Generate a config (safe defaults) +### 5) Generate a config (safe defaults) Catalyst can generate a default config file if the path doesn’t exist. @@ -81,7 +97,7 @@ Stop it (Ctrl+C) after it starts once—this creates sibling directories near th Do **not** delete `node.key` during resets/upgrades unless you intend to change the node’s network identity. ::: -### 5) Run under systemd +### 6) Run under systemd Create a unit file: @@ -122,6 +138,8 @@ sudo install -o catalyst -g catalyst -m 0755 \ /var/lib/catalyst/node/catalyst-cli ``` +If you used a release binary and already installed it to `/var/lib/catalyst/node/catalyst-cli`, you can skip this step. + Start: ```bash @@ -130,7 +148,7 @@ sudo systemctl enable --now catalyst sudo systemctl status catalyst --no-pager ``` -### 6) Firewall (minimum) +### 7) Firewall (minimum) If using `ufw`: diff --git a/site/docs/quickstarts/i-want-to-use-apps.md b/site/docs/quickstarts/i-want-to-use-apps.md new file mode 100644 index 0000000..357b6d0 --- /dev/null +++ b/site/docs/quickstarts/i-want-to-use-apps.md @@ -0,0 +1,46 @@ +--- +sidebar_position: 0 +title: "Quickstart: I want to use Catalyst apps" +--- + +This quickstart is for everyday users. The goal is to **use apps**—Catalyst should fade into the background. + +## You will need + +- A wallet app +- (Testnet) Access to the faucet + +## Steps + +### 1) Start with a use case + +Pick what you want to do: + +- **[Send money](/docs/use-cases/send-money)** +- **[Games and digital items](/docs/use-cases/games-assets)** +- **[Social apps you control](/docs/use-cases/social-you-control)** + +### 2) Create an account in your wallet + +- Create a new account. +- Back it up using the wallet’s instructions (offline is best). + +If you’re new, see: + +- **[Wallet → user guide](/docs/wallets/wallet-user-guide)** + +### 3) Get testnet funds (testnet only) + +- **[Faucet → user guide](/docs/faucet/user-guide)** + +### 4) Verify activity (optional but recommended) + +If something looks “stuck” in an app UI, the explorer can show the source of truth. + +- **[Explorer → user guide](/docs/explorer/user-guide)** + +## Verify + +- You can see your balance in the wallet. +- The explorer shows your account activity. + diff --git a/site/docs/quickstarts/i-want-to-use-the-wallet.md b/site/docs/quickstarts/i-want-to-use-the-wallet.md index aef7d7b..1d2420f 100644 --- a/site/docs/quickstarts/i-want-to-use-the-wallet.md +++ b/site/docs/quickstarts/i-want-to-use-the-wallet.md @@ -3,6 +3,8 @@ sidebar_position: 2 title: "Quickstart: I want to use the wallet" --- +This quickstart is for everyday users. You don’t need to know how Catalyst works to use it. + ## You will need - A supported wallet app (web wallet for testnet) @@ -12,7 +14,12 @@ title: "Quickstart: I want to use the wallet" 1) Open the wallet and create/import an account. -2) Confirm the wallet shows the expected network identity before signing anything: +2) Confirm you’re on the **right network** (testnet vs mainnet) before signing anything. + +If you’re on testnet, your wallet should say “testnet” and show the expected network name. + +
+Advanced: exact testnet network identifiers - `network_id`: `catalyst-testnet` - `chain_id`: `0xbf8457c` (hex) / `200820092` (decimal) @@ -20,6 +27,7 @@ title: "Quickstart: I want to use the wallet" Canonical defaults (for the current testnet wallet implementation): - `WebWallet/README.md` +
3) Request testnet funds from the faucet (testnet only): @@ -31,6 +39,6 @@ Canonical defaults (for the current testnet wallet implementation): ## Troubleshooting -- If the wallet refuses to sign, it’s often because **chain identity mismatched** (wrong RPC URL / wrong network). +- If the wallet refuses to sign, it’s often because you’re connected to the **wrong network**. - Never paste your private key into websites or support chats. See **[Wallets → User guide](/docs/wallets/wallet-user-guide)**. diff --git a/site/docs/rpc-reference/transaction-lifecycle.md b/site/docs/rpc-reference/transaction-lifecycle.md index e484c2b..d4e4695 100644 --- a/site/docs/rpc-reference/transaction-lifecycle.md +++ b/site/docs/rpc-reference/transaction-lifecycle.md @@ -3,6 +3,12 @@ sidebar_position: 1 title: "RPC: transaction lifecycle" --- +:::note Not for everyday users +If you’re just using a wallet or an app, you don’t need this page. + +This page is for people building wallets, SDKs, dApps, and tooling that submit transactions directly to Catalyst RPC. +::: + This page is the canonical “how a tx moves through Catalyst” reference: 1) fetch domain diff --git a/site/docs/sdk/get-started.md b/site/docs/sdk/get-started.md index 1313cf7..8e4c269 100644 --- a/site/docs/sdk/get-started.md +++ b/site/docs/sdk/get-started.md @@ -3,6 +3,11 @@ sidebar_position: 1 title: Get started --- +This section is for builders (dApps, tooling, wallets). If you’re just using apps, start with: + +- **[Use cases (for everyone)](/docs/use-cases/send-money)** +- **[Quickstart: use Catalyst apps](/docs/quickstarts/i-want-to-use-apps)** + ## You will need - Node.js >= 20 @@ -35,6 +40,11 @@ console.log({ Your domain fetch should succeed and `genesisHashLen` should be `32`. +## Next steps + +- **[Deploy a contract](/docs/sdk/deploy-contract)** +- **[Common pitfalls](/docs/sdk/common-pitfalls)** + ## Troubleshooting - **Intermittent signature failures behind a load balancer**: ensure you use `getTxDomain` (single-call domain) rather than fetching chain identity via multiple RPC calls. diff --git a/site/docs/use-cases/_category_.json b/site/docs/use-cases/_category_.json new file mode 100644 index 0000000..3e57a64 --- /dev/null +++ b/site/docs/use-cases/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Use cases (for everyone)", + "position": 5, + "link": { + "type": "generated-index", + "title": "What can I do with Catalyst?", + "description": "Real-world use cases, explained without jargon. Start here if you just want to use apps." + } +} + diff --git a/site/docs/use-cases/games-assets.md b/site/docs/use-cases/games-assets.md new file mode 100644 index 0000000..ed84bee --- /dev/null +++ b/site/docs/use-cases/games-assets.md @@ -0,0 +1,58 @@ +--- +title: Games and digital items you actually own +sidebar_position: 2 +--- + +This page is for everyday users. + +## The problem + +In many games today: + +- your items are trapped inside one game or one company +- you can lose access if an account is banned or a game shuts down +- you can’t easily prove an item is “really yours” + +## What Catalyst enables + +Catalyst can support games where: + +- items can be **owned by you**, not just by a game server +- items can **move between apps** (when the apps choose to support it) +- ownership can be **verified publicly** (like checking a serial number) + +You don’t need to learn the underlying technology to benefit from it—your wallet and game UI can make it feel normal. + +## What you do (as a player) + +### 1) Get a wallet + +- Create an account and back it up. +- **[Wallet → user guide](/docs/wallets/wallet-user-guide)** + +### 2) Play a Catalyst-enabled game + +When a game supports Catalyst, it can show: + +- your items (in-game) +- your ownership (in-wallet) +- transfers (send/trade) + +### 3) Verify ownership (optional) + +If you ever want to double-check, the explorer can show activity tied to your account. + +- **[Explorer → user guide](/docs/explorer/user-guide)** + +## What to look for in good apps + +- Clear “backup” guidance for your wallet +- Human-friendly names/contacts (so you don’t paste long strings all day) +- A simple “activity / receipts” page + +## Troubleshooting + +### “I can’t see my item in the wallet” + +Not all wallets show every kind of in-game item yet. The game might still work fine even if the wallet UI is still catching up. + diff --git a/site/docs/use-cases/how-it-works-plain-english.md b/site/docs/use-cases/how-it-works-plain-english.md new file mode 100644 index 0000000..aee702e --- /dev/null +++ b/site/docs/use-cases/how-it-works-plain-english.md @@ -0,0 +1,66 @@ +--- +title: How it works (plain English) +sidebar_position: 10 +--- + +You don’t need to read this to use Catalyst apps, but it can help you feel confident. + +## The three things you’ll see + +### 1) A wallet + +A wallet is an app that: + +- creates your account +- lets you send/receive money +- keeps your “keys” (the secret needed to approve actions) + +**Important:** if you lose your wallet backup, you can lose access. + +### 2) Apps + +Apps are what you actually use: + +- games +- social apps +- marketplaces +- tools + +Good apps will make Catalyst “disappear” and just feel like normal software. + +### 3) An explorer + +An explorer is like a public receipt viewer. You can use it to: + +- verify a payment happened +- verify an app action was recorded +- troubleshoot when an app UI is slow to update + +## What a “transaction” is + +A transaction is just a signed request from your wallet, like: + +- “send 5 tokens to Alex” +- “deploy this app feature” +- “call this contract” + +Your wallet signs it so the network can verify it’s really you approving it. + +## Testnet vs mainnet + +Testnet is for testing: + +- funds are free (via a faucet) +- things can reset or change + +Mainnet is real: + +- funds are not free +- you should be more careful with backups and security + +## Where to go next + +- **[Quickstarts](/docs/quickstarts/i-want-to-use-the-wallet)** +- **[Faucet → user guide](/docs/faucet/user-guide)** +- **[Explorer → user guide](/docs/explorer/user-guide)** + diff --git a/site/docs/use-cases/send-money.md b/site/docs/use-cases/send-money.md new file mode 100644 index 0000000..ecc2de9 --- /dev/null +++ b/site/docs/use-cases/send-money.md @@ -0,0 +1,86 @@ +--- +title: Send money (without scary addresses) +sidebar_position: 1 +--- + +This page is for everyday users. You do **not** need to understand blockchains to use Catalyst. + +## What you can do + +- **Send money to a person** and verify it arrived +- **Check activity** in a public explorer (like a receipt) +- **Avoid common mistakes** (wrong network, copying the wrong text) + +## How it feels (high level) + +Using Catalyst is like using: + +- a **wallet app** (to hold money and sign payments) +- an **explorer** (to verify what happened) +- an **app** (the thing you actually care about) + +Catalyst is the underlying network that makes those apps work. + +## Steps + +### 1) Install a wallet and create an account + +- Open the wallet. +- Create a new account. +- **Back it up** in whatever way the wallet recommends (offline is best). + +If you’re using the testnet web wallet, start here: + +- **[Wallet → user guide](/docs/wallets/wallet-user-guide)** + +### 2) Get some funds (testnet) + +If you’re on testnet, you can request free test funds: + +- **[Faucet → user guide](/docs/faucet/user-guide)** + +### 3) Send money + +In the wallet: + +- Choose **Send** +- Paste the recipient’s address (or choose from contacts if the wallet supports it) +- Choose an amount +- Confirm and send + +### 4) Verify (your receipt) + +Open the explorer and search for: + +- your address, or +- the transaction ID (if your wallet shows it) + +- **[Explorer → user guide](/docs/explorer/user-guide)** + +## Verify + +You’re done when: + +- the wallet shows the transfer as completed, and +- the explorer shows the transaction as applied. + +## Troubleshooting + +### “My balance didn’t change” + +Sometimes apps update slowly. The explorer is your source of truth: + +- **[Explorer → user guide](/docs/explorer/user-guide)** + +### “Wallet says wrong network” + +Make sure you’re using the wallet for the right network (testnet vs mainnet). If you’re unsure, stop and ask—this prevents sending to the wrong place. + +### Safety reminder + +Never paste your private key / recovery phrase into: + +- websites +- screenshots +- support chats + diff --git a/site/docs/use-cases/social-you-control.md b/site/docs/use-cases/social-you-control.md new file mode 100644 index 0000000..299ef95 --- /dev/null +++ b/site/docs/use-cases/social-you-control.md @@ -0,0 +1,47 @@ +--- +title: Social apps you control (not platforms) +sidebar_position: 3 +--- + +This page is for everyday users. + +## The problem + +On most social platforms: + +- the platform owns your identity and audience +- moderation and ranking rules change without you choosing them +- moving to another app often means starting over + +## What Catalyst enables + +Catalyst can support social apps where: + +- your identity can be **portable** between apps +- your content and relationships can be **yours**, not locked to one company +- you can choose apps that match your preferences without losing everything + +You shouldn’t need to understand “blockchains” to get these benefits. A good app will feel like a normal social app—just with better portability and user control. + +## What you do (as a user) + +### 1) Create an account in your wallet + +- **[Wallet → user guide](/docs/wallets/wallet-user-guide)** + +### 2) Pick a social app + +In the future, this docs site will link to an app directory so you can install apps without thinking about the underlying network. + +For now: use whichever Catalyst-enabled social app you trust and enjoy. + +### 3) Verify activity (optional) + +If you ever need an audit trail (for example, “did I post / did I follow / did I pay?”), explorers can provide public verification. + +- **[Explorer → user guide](/docs/explorer/user-guide)** + +## Safety reminder + +If you lose your wallet backup, you can lose access to accounts and assets. Follow your wallet’s backup guidance carefully. + diff --git a/site/src/components/HomepageFeatures/index.tsx b/site/src/components/HomepageFeatures/index.tsx index af8666c..99edb35 100644 --- a/site/src/components/HomepageFeatures/index.tsx +++ b/site/src/components/HomepageFeatures/index.tsx @@ -11,6 +11,22 @@ type FeatureItem = { }; const FeatureList: FeatureItem[] = [ + { + title: 'Use cases (for everyone)', + Svg: require('@site/static/img/undraw_docusaurus_react.svg').default, + description: ( + <> + Send money, play games, and use apps where you control your assets and identity—without needing to learn jargon. +
+ Send money + {' · '} + Games & assets + {' · '} + Social +
+ + ), + }, { title: 'Node operators', Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default, @@ -28,21 +44,21 @@ const FeatureList: FeatureItem[] = [ Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default, description: ( <> - Build dApps and tooling against the RPC surface and CTX2 signing model. + Build dApps and tooling against Catalyst, with a focus on safe defaults and simple deploy flows.
- RPC: tx lifecycle - {' · '} SDK get started + {' · '} + Deploy a contract
), }, { - title: 'Wallet + explorer + faucet', - Svg: require('@site/static/img/undraw_docusaurus_react.svg').default, + title: 'Wallet, explorer, and faucet', + Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default, description: ( <> - End-user guides and operator runbooks for ecosystem apps. + Guides for using Catalyst tools (and running them if you’re an operator).
Wallet user guide {' · '} @@ -57,7 +73,7 @@ const FeatureList: FeatureItem[] = [ function Feature({title, Svg, description}: FeatureItem) { return ( -
+
diff --git a/site/src/pages/index.tsx b/site/src/pages/index.tsx index d0566a8..71570c2 100644 --- a/site/src/pages/index.tsx +++ b/site/src/pages/index.tsx @@ -18,6 +18,9 @@ function HomepageHeader() {

{siteConfig.tagline}

+ + Use apps + @@ -26,9 +29,6 @@ function HomepageHeader() { Deploy a contract - - RPC: tx lifecycle - Get testnet funds