Merge pull request #2 from catalyst-network/docs/use-cases-user-first

docs: clarify SDK install and contract calling

Author: TheNewAutonomy

site/docs/quickstarts/i-want-to-build-a-dapp.md

@@ -10,12 +10,27 @@ title: "Quickstart: I want to build a dApp"
 
 ## Steps
 
-1) Install the SDK package:
+1) Get the SDK:
+
+:::note
+If `@catalyst/sdk` is not published to npm yet, use the repo-based workflow below (clone + build).
+:::
+
+Option A (npm, when published):
 
 ```bash
 npm install @catalyst/sdk
 ```
 
+Option B (repo, works today):
+
+```bash
+git clone https://github.com/catalyst-network/catalyst-sdk
+cd catalyst-sdk
+npm install
+npm run build
+```
+
 2) Read the tx lifecycle (so you understand domain separation + receipts):
 
 - **[RPC: transaction lifecycle](/docs/rpc-reference/transaction-lifecycle)**

site/docs/sdk/common-pitfalls.md

@@ -47,3 +47,34 @@ Fix:
 
 - increase poll interval and add exponential backoff + jitter
 
+## Explorer shows “missing txs”
+
+Symptom:
+
+- your deploy/call CLI shows `receipt_status: applied`
+- but the block explorer does not show the transaction
+
+Cause (common):
+
+- explorer/indexer is behind, stalled, or pointed at a different backend/RPC
+
+Fix:
+
+- treat RPC as source of truth:
+  - `catalyst_getTransactionReceipt(txid)` (check `applied_cycle`)
+  - `catalyst_getBlockByNumber(applied_cycle, false)` (check tx is included)
+
+## Payable calls / `msg.value`
+
+Symptom:
+
+- a contract requires a non-zero `msg.value` (e.g. fee-based registration)
+
+Cause:
+
+- current Catalyst testnet CALL transactions do not carry an Ethereum-style `value`
+
+Fix:
+
+- set fees to zero for testnet workflows, or avoid payable patterns until value support is exposed
+

site/docs/sdk/deploy-contract.md

@@ -109,15 +109,25 @@ code_verified: true
 
 This is a **transaction** (not `eth_call`).
 
+You must provide **calldata bytes** (hex). If you have Foundry installed, you can generate calldata with `cast calldata`.
+
 ```bash
+DATA=$(cast calldata "setNumber(uint256)" 42)
+
 node packages/cli/dist/index.js call \
   --rpc-url "$RPC_URL" \
   --key-file ../catalyst-node-rust/wallet.key \
   --to 0x<contract_address> \
-  --data 0x \
+  --data "$DATA" \
   --wait
 ```
 
+::::caution
+EVM `value` (payable calls)
+
+On current Catalyst testnet, EVM calls do not carry an Ethereum-style `value`. Contracts that require `msg.value` may not be usable until value support is exposed by the runtime/RPC.
+::::
+
 ### Option B: Deploy to public testnet
 
 Follow the same CLI command, but:

site/docs/sdk/get-started.md

@@ -17,10 +17,29 @@ This section is for builders (dApps, tooling, wallets). If you’re just using a
 
 ### 1) Install the SDK
 
+:::note
+`@catalyst/sdk` is a TypeScript package that is intended to be published to npm.
+
+If the package is not published yet, use the **repo-based workflow** below (clone + build) or use the **deploy CLI** directly:
+
+- **[Deploy a contract](/docs/sdk/deploy-contract)** (uses `catalyst-sdk` CLI)
+:::
+
+#### Option A: npm (when published)
+
 ```bash
 npm install @catalyst/sdk
 ```
 
+#### Option B: repo (works today)
+
+```bash
+git clone https://github.com/catalyst-network/catalyst-sdk
+cd catalyst-sdk
+npm install
+npm run build
+```
+
 ### 2) Connect to RPC and fetch the tx signing domain
 
 ```ts

site/docs/smart-contracts/contract-repo-workflows.md

@@ -11,6 +11,15 @@ This page links to existing Catalyst contract repos and recommended workflows.
   Designed to be usable by wallets/nodes that can only read raw EVM storage (`catalyst_getStorageAt`).
 - **General contracts**: `catalyst-contracts` (currently minimal; expect changes)
 
+## Identity contracts: recommended deploy + test flow
+
+The identity contracts repo contains a Foundry `forge script --broadcast` deploy script, but Catalyst deployments should be done via **CTX2** tooling.
+
+Recommended workflow:
+
+- deploy: `catalyst-sdk/scripts/deploy-catalyst-identity-contracts.sh`
+- smoke test: `catalyst-sdk/scripts/test-deployed-identity-contracts.mjs`
+
 ## Recommended workflow (Foundry)
 
 1) Write + test contracts:

site/docs/smart-contracts/evm-support-status.md

@@ -13,6 +13,7 @@ Based on the current node implementation:
 - **Read code**: supported via `catalyst_getCode(address20)`
 - **Storage reads**: supported via `catalyst_getStorageAt(address20, slot32)`
 - **Receipts**: supported via `catalyst_getTransactionReceipt(tx_id)`
+- **`eth_call` equivalent**: not a standard part of the Catalyst workflow today (calls are submitted as transactions)
 
 Canonical references:
 
@@ -25,6 +26,7 @@ Canonical references:
 - **Submission method**: `catalyst_sendRawTransaction` (not `eth_sendRawTransaction`)
 - **Signing domain**: `catalyst_getTxDomain` (single-call domain separation; includes `genesis_hash`)
 - **Cycle/block semantics**: some cycles produce no block/LSU; explorers must handle gaps
+- **Payable calls**: EVM calls do not currently carry an Ethereum-style `value` (`msg.value`)
 
 ## Verify