release: v1.3.0 → stable

.claude/rules/go.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - "**/*.go"
+---
+
+- Follow standard Go conventions: `gofmt`, exported names have doc comments.
+- Error handling: always check and return errors, never ignore with `_`.
+- Use the functional options pattern for configuration (see `sdk/go/config.go`).
+- Shared packages live in `pkg/` — check there before creating new utilities.
+- Test files go in the same package with `_test.go` suffix.
+- Run tests from repo root: `go test ./sdk/go/...` (scoped) or `go test ./...` (all).

.claude/rules/solidity.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "contracts/**/*.sol"
+---
+
+- Foundry project — use `forge build`, `forge test`, `forge fmt`.
+- NatSpec comments on all public/external functions.
+- Security first: validate all inputs, check for reentrancy, use OpenZeppelin where applicable.
+- Test files in `contracts/test/` with `.t.sol` extension.
+- Gas optimization matters — avoid unnecessary storage writes.
+- Style guide: https://github.com/layer-3/clearsync/blob/master/contracts/solidity-style-guide.md
+- Development practices: https://github.com/layer-3/clearsync/blob/master/contracts/solidity-development-practices.md

.claude/rules/typescript.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "sdk/**/*.ts"
+  - "sdk/**/*.tsx"
+---
+
+- Use `const` by default, `let` only when reassignment is needed. No `var`.
+- Prefer `viem` over `ethers.js` for Ethereum interactions in production code.
+- All public API functions must be exported through the barrel `index.ts`.
+- Use strict TypeScript — no `any` unless absolutely unavoidable (e.g., RPC wire types).
+- Async functions preferred over raw Promise chains.
+- Test files use `.test.ts` extension (not `.spec.ts`).
+- When modifying sdk-compat: never barrel re-export SDK classes (SSR risk). Only `export type` is safe.

.claude/settings.json

@@ -0,0 +1,35 @@
+{
+    "permissions": {
+        "allow": [
+            "Bash(npm test*)",
+            "Bash(npm run build*)",
+            "Bash(npm run typecheck*)",
+            "Bash(npm run lint*)",
+            "Bash(npm run clean*)",
+            "Bash(npx jest*)",
+            "Bash(npx prettier*)",
+            "Bash(npx tsx *)",
+            "Bash(go test *)",
+            "Bash(go build *)",
+            "Bash(go vet *)",
+            "Bash(go run *)",
+            "Bash(forge build*)",
+            "Bash(forge test*)",
+            "Bash(forge fmt*)",
+            "Bash(git status*)",
+            "Bash(git log*)",
+            "Bash(git diff*)",
+            "Bash(git branch*)",
+            "Bash(gh pr *)",
+            "Bash(gh issue *)",
+            "Bash(gh run *)"
+        ],
+        "deny": [
+            "Bash(git push --force*)",
+            "Bash(git reset --hard*)",
+            "Bash(rm -rf *)",
+            "Bash(*>.env*)",
+            "Bash(npm publish*)"
+        ]
+    }
+}

.claude/skills/build-sdk/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: build-sdk
+description: Build SDK packages in the correct dependency order
+allowed-tools: Bash, Read
+---
+
+Build SDK packages for: $ARGUMENTS
+
+**Important:** sdk/ts-compat depends on sdk/ts via `"@yellow-org/sdk": "file:../ts"`. Always respect build order.
+
+1. If $ARGUMENTS is "all" or empty, build everything in order:
+   - `cd sdk/ts && npm run build` (this runs tests then tsc)
+   - `cd sdk/ts-compat && npm run build`
+   - `go build ./sdk/go/...`
+
+2. If $ARGUMENTS specifies a single package, build just that:
+   - "ts" -> `cd sdk/ts && npm run build`
+   - "ts-compat" or "compat" -> check sdk/ts/dist/ exists first; if not, build sdk/ts first, then `cd sdk/ts-compat && npm run build`
+   - "go" -> `go build ./sdk/go/...`
+
+3. Report build success/failure for each package with any error details.

.claude/skills/lint/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: lint
+description: Run linters and formatters for the appropriate language
+allowed-tools: Bash, Read
+---
+
+Lint and check formatting for: $ARGUMENTS
+
+Route to the correct linter based on context:
+
+- **sdk/ts/** -> `cd sdk/ts && npm run lint && npx prettier --check .`
+- **sdk/ts-compat/** -> `cd sdk/ts-compat && npm run typecheck` (no dedicated lint script; typecheck is the closest)
+- **contracts/** -> `cd contracts && forge fmt --check`
+- **Go code** -> `go vet ./...` from repo root (or scope to specific path like `./sdk/go/...`)
+
+If no arguments provided, run all applicable linters and report a summary.
+
+Report any issues found. Suggest fixes but do not auto-apply unless the user asks.

.claude/skills/review-pr/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: review-pr
+description: Thorough code review of current changes or a specific PR
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+Review changes for: $ARGUMENTS
+
+1. **Get the diff:**
+   - If $ARGUMENTS is a PR number: `gh pr diff $ARGUMENTS`
+   - If no arguments: `git diff` and `git diff --staged` for uncommitted changes
+
+2. **For each changed file, check:**
+   - **Correctness:** Does the logic do what it claims? Any off-by-one errors, race conditions, or wrong assumptions?
+   - **Types:** Are TypeScript types accurate and strict? Are Go errors properly handled?
+   - **Security:** No exposed secrets, no injection vectors, no reentrancy (contracts), no XSS
+   - **Tests:** Are new functions tested? Are edge cases and error paths covered?
+   - **Exports:** If public API changed, is the barrel `index.ts` updated? (sdk-compat: no SSR-unsafe re-exports)
+   - **Docs:** If behavior changed, are README/CLAUDE.md/migration docs updated?
+   - **Style:** Consistent with existing patterns in the file and project conventions
+
+3. **Categorize findings:**
+   - **CRITICAL:** Must fix before merge (bugs, security issues, data loss risk)
+   - **WARNING:** Should fix (missing tests, poor error handling, incomplete docs)
+   - **SUGGESTION:** Nice to have (naming improvements, minor refactors, style tweaks)
+
+4. **Give an overall verdict:** APPROVE / REQUEST CHANGES / COMMENT

.claude/skills/test/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: test
+description: Run tests for a specific module or the whole project
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+Run tests for: $ARGUMENTS
+
+Detect the target module and run the appropriate test command:
+
+1. If $ARGUMENTS names a specific file or directory, use that to determine the module
+2. If no arguments, detect from the current working directory or recently edited files
+
+Route to the correct test runner:
+- **sdk/ts/** -> `cd sdk/ts && npm test`
+- **sdk/ts-compat/** -> `cd sdk/ts-compat && npm test`
+- **sdk/go/** or Go files under sdk/go/ -> `go test ./sdk/go/... -v` (from repo root)
+- **contracts/** or .sol files -> `cd contracts && forge test`
+- **nitronode/** -> `go test ./nitronode/... -v` (from repo root)
+- **test/integration/** -> `cd test/integration && npm test`
+- **Repo root with no argument** -> run `go test ./...` (Go packages only — does NOT cover `sdk/ts`, `sdk/ts-compat`, `contracts`, or `test/integration`). Ask the user to specify a target for non-Go tests.
+
+If a specific test file is given (e.g., `sdk/ts/test/unit/utils.test.ts`), run only that file:
+- For Jest: `cd sdk/ts && npx jest test/unit/utils.test.ts`
+- For Go: resolve the file's containing package, then run `go test ./sdk/go/<pkg> -run '^TestName$'`
+- For Forge: `cd contracts && forge test --match-path test/MyTest.t.sol`
+
+Report results: pass count, fail count, and any error details.

.claude/skills/typecheck/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: typecheck
+description: Run TypeScript type checking across SDK packages
+allowed-tools: Bash, Read
+---
+
+Run typecheck for: $ARGUMENTS
+
+1. If $ARGUMENTS specifies a package ("ts", "ts-compat", or "both"), check that package
+2. If no arguments, check both TypeScript packages:
+
+```bash
+cd sdk/ts && npm run typecheck
+cd sdk/ts-compat && npm run typecheck
+```
+
+3. Report any type errors with file paths and line numbers
+4. If the user asks about Go type checking, suggest `go vet ./...` instead

.cursorrules

@@ -0,0 +1,82 @@
+# Nitrolite — Cursor Rules
+
+## What This Project Is
+
+Nitrolite is a state channel protocol for Ethereum/EVM blockchains. Off-chain instant transactions with on-chain security. The repo contains: Solidity contracts (Foundry), a Go nitronode broker (renamed from clearnode), TypeScript + Go SDKs, and MCP servers for AI tooling.
+
+## Architecture
+
+- **Channels**: State containers between a User and a Node. Hold asset allocations, support off-chain state updates.
+- **States**: Versioned allocations. Each new state = previous version + 1. Mutually signed states are enforceable on-chain.
+- **Nitronode** (formerly Clearnode): Off-chain broker. WebSocket JSON-RPC. Wire format: `{ "req": [REQUEST_ID, METHOD, PARAMS, TIMESTAMP], "sig": ["SIGNATURE"] }`
+- **App Sessions**: Multi-party extensions on channels with quorum-based governance (weight + threshold voting).
+
+## TypeScript SDK Conventions
+
+- `@yellow-org/sdk` = v1 protocol SDK (use for all new code)
+- `@yellow-org/sdk-compat` = bridges 0.5.x API surface to v1 runtime (migration only, wraps Client with NitroliteClient)
+- V1 API source of truth: `docs/api.yaml`. Do NOT reference `docs/legacy/API.md` for v1 methods (it has 0.5.x names)
+- Use `const` by default, `let` only when reassignment is needed. No `var`.
+- Prefer `viem` over `ethers.js` for Ethereum interactions.
+- All public API functions exported through barrel `index.ts`.
+- Strict TypeScript — no `any` unless unavoidable (e.g., RPC wire types).
+- Async functions preferred over raw Promise chains.
+- Tests: `.test.ts` extension, Jest. Run: `cd sdk/ts && npm test`
+- sdk-compat: NEVER barrel re-export SDK classes (SSR risk). Only `export type` is safe.
+- Build order: `sdk/ts` must build before `sdk/ts-compat`.
+
+## Go SDK Conventions
+
+- Module: `github.com/layer-3/nitrolite` (root go.mod, Go 1.25)
+- Follow standard Go: `gofmt`, exported names have doc comments.
+- Error handling: always check and return errors, never ignore with `_`.
+- Functional options pattern for configuration (see `sdk/go/config.go`).
+- Shared packages in `pkg/` — check there before creating new utilities.
+- Tests: `_test.go` suffix, same package. Run from repo root: `go test ./sdk/go/...`
+- Use `context.Context` for all async operations, `github.com/shopspring/decimal` for amounts.
+
+## Solidity Conventions
+
+- Foundry project: `forge build`, `forge test`, `forge fmt`.
+- NatSpec comments on all public/external functions.
+- Security first: validate inputs, check reentrancy, use OpenZeppelin.
+- Tests in `contracts/test/` with `.t.sol` extension.
+- Gas optimization matters — avoid unnecessary storage writes.
+- Style guide: https://github.com/layer-3/clearsync/blob/master/contracts/solidity-style-guide.md
+- Development practices: https://github.com/layer-3/clearsync/blob/master/contracts/solidity-development-practices.md
+
+## Key SDK Methods (Both TS and Go)
+
+- `Deposit(chainId, asset, amount)` — deposit funds, creates channel if needed
+- `Transfer(recipient, asset, amount)` — off-chain instant transfer
+- `Checkpoint(asset)` — submit co-signed state to blockchain (required after deposit, withdraw, close)
+- `CloseHomeChannel(asset)` — prepare finalize state (follow with Checkpoint)
+- `CreateAppSession(definition, sessionData, quorumSigs)` — create multi-party session
+- `SubmitAppState(appStateUpdate, quorumSigs)` — submit app state (Operate, Withdraw, or Close intent)
+- `GetChannels(wallet)`, `GetBalances(wallet)`, `GetConfig()` — queries
+
+> No `CloseAppSession()` exists on the SDK Client. Close via `SubmitAppState` with Close intent.
+
+## Key Reference Files
+
+- Protocol description: `protocol-description.md`
+- Smart contract invariants: `contracts/SECURITY.md`
+- Main SC entrypoint: `contracts/src/ChannelHub.sol` (design: `contracts/suggested-contract-design.md`)
+- Nitronode logic: `nitronode/README.md`, `docs/legacy/`
+- Advanced protocol docs: `docs/protocol/`
+
+## Commit Convention
+
+```
+feat|fix|chore|test|docs(scope): description
+```
+Examples: `feat(sdk/ts): add transfer batching`, `fix(sdk-compat): export missing type`
+
+## Common Mistakes to Avoid
+
+- Don't use `ethers.js` — use `viem` for Ethereum interactions
+- Don't ignore Go errors with `_`
+- Don't barrel re-export classes in sdk-compat (causes SSR failures)
+- Don't run `npm test && npm run build` in sdk/ts (double-tests; build already runs tests)
+- Don't edit `.env` files or commit secrets
+- Don't create new utilities without checking `pkg/` first (Go)

.dockerignore

@@ -1,21 +1,17 @@
 .dockerignore
 .gitignore
 .gitmodules
-docker-compose.yml
 .git/
 .github/
 LICENSE
 contracts/
 docs/
 sdk/ts/
-test/
 
 *.md
 
-# clearnode
-clearnode/Dockerfile
-clearnode/.gitignore
-clearnode/docs/
-clearnode/chart/
-clearnode/scripts/
-clearnode/docker-compose.yml
+# nitronode
+nitronode/Dockerfile
+nitronode/.gitignore
+nitronode/docs/
+nitronode/chart/

.github/CODEOWNERS

@@ -1,4 +1,4 @@
 # CODEOWNERS: https://help.github.com/articles/about-codeowners/
 
 # Yellow Network - Research and Development
-* @alessio @dimast-x @nksazonov @philanton @ihsraham
+* @dimast-x @nksazonov @philanton @ihsraham

.github/copilot-instructions.md

@@ -0,0 +1,61 @@
+# Nitrolite Copilot Instructions
+
+Nitrolite is a state channel protocol for Ethereum/EVM blockchains — off-chain instant transactions with on-chain security. Repo contains: Solidity contracts (Foundry), Go nitronode broker (renamed from clearnode), TypeScript + Go SDKs.
+
+## Architecture
+
+- Channels: state containers between User and Node, hold asset allocations
+- States: versioned allocations, each version = previous + 1, mutually signed = enforceable on-chain
+- Nitronode (formerly Clearnode): off-chain broker, WebSocket JSON-RPC wire format
+- App Sessions: multi-party extensions with quorum-based governance
+
+## TypeScript SDK (`@yellow-org/sdk`)
+
+- `@yellow-org/sdk` = v1 protocol SDK. Use for all new code.
+- `@yellow-org/sdk-compat` = bridges 0.5.x API to v1 runtime. Migration only. Wraps Client with NitroliteClient.
+- V1 API source of truth: `docs/api.yaml`. `docs/legacy/API.md` has 0.5.x method names.
+- Use `const` by default, `viem` over `ethers.js`, strict TypeScript (no `any`)
+- All public API through barrel `index.ts`, async/await preferred
+- Tests: `.test.ts`, Jest. Run: `cd sdk/ts && npm test`
+- Build order: `sdk/ts` before `sdk/ts-compat`
+- sdk-compat: NEVER barrel re-export classes (SSR risk), only `export type`
+
+## Go SDK (`github.com/layer-3/nitrolite/sdk/go`)
+
+- Root go.mod, Go 1.25. Standard Go: `gofmt`, doc comments on exports
+- Always check errors, never ignore with `_`
+- Functional options pattern (`sdk/go/config.go`), shared utils in `pkg/`
+- Tests: `_test.go`, run from repo root: `go test ./sdk/go/...`
+- Use `context.Context`, `github.com/shopspring/decimal` for amounts
+
+## Solidity (`contracts/`)
+
+- Foundry: `forge build`, `forge test`, `forge fmt`
+- NatSpec on public/external functions, security-first, OpenZeppelin
+- Tests: `.t.sol` in `contracts/test/`
+- Style: https://github.com/layer-3/clearsync/blob/master/contracts/solidity-style-guide.md
+- Practices: https://github.com/layer-3/clearsync/blob/master/contracts/solidity-development-practices.md
+
+## Key SDK Methods (both TS and Go)
+
+Deposit, Transfer, Checkpoint (required after deposit/withdraw/close), CloseHomeChannel (follow with Checkpoint), CreateAppSession (definition, sessionData, quorumSigs), SubmitAppState (appStateUpdate, quorumSigs — use Close intent to close sessions), GetChannels(wallet), GetBalances(wallet), GetConfig
+
+> No CloseAppSession() on SDK Client. Close via SubmitAppState with Close intent.
+
+## Key Reference Files
+
+- Protocol description: `protocol-description.md`
+- Smart contract invariants: `contracts/SECURITY.md`
+- Main SC entrypoint: `contracts/src/ChannelHub.sol` (design: `contracts/suggested-contract-design.md`)
+- Nitronode logic: `nitronode/README.md`, `docs/legacy/`
+- Advanced protocol docs: `docs/protocol/`
+
+## Commits
+
+`feat|fix|chore|test|docs(scope): description`
+
+## Avoid
+
+- ethers.js (use viem), ignoring Go errors, barrel re-exporting classes in sdk-compat
+- Running `npm test && npm run build` in sdk/ts (build already runs tests)
+- Editing .env files, committing secrets