blocksense-network · zah · Jun 5, 2025
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -112,15 +112,151 @@ Please see our [security policy](/.github/SECURITY.md).
 
 ---
 
-### 💾 Formatting & Saving Code Before Commit
+## 💾 Formatting & Saving Code Before Commit
 
-Before committing, **format your code** using:
+### 📝 Editor Configuration
 
-**yarn format:write**
+1. **Install EditorConfig plugin** for your editor
+2. **Configure your editor** to:
+   - Use spaces (not tabs) for indentation
+   - Trim trailing whitespace on save
+   - Ensure files end with a newline
+   - Use LF line endings (not CRLF)
+
+### Recommended VS Code Extensions
+
+- EditorConfig for VS Code
+- Prettier - Code formatter
+- rust-analyzer
+- Nix IDE
+
+### 🔧 Pre-commit Hooks
+
+This project uses pre-commit hooks to maintain code quality and consistency. When you make a commit, several tools automatically check your code:
+
+#### Enabled Tools
+
+| Tool             | Purpose                    | Files Checked                    |
+| ---------------- | -------------------------- | -------------------------------- |
+| **Prettier**     | Code formatting            | TypeScript, JavaScript, Markdown |
+| **Rustfmt**      | Code formatting            | Rust files (\*.rs)               |
+| **Nixfmt**       | Code formatting            | Nix files (\*.nix)               |
+| **Clippy**       | Rust linting               | Rust files (\*.rs)               |
+| **Statix**       | Nix linting                | Nix files (\*.nix)               |
+| **Deadnix**      | Dead code detection        | Nix files (\*.nix)               |
+| **EditorConfig** | Consistent editor settings | All files                        |
+
+#### When Hooks Fail
+
+Pre-commit hooks behave differently depending on their purpose:
+
+##### 🔧 Auto-Fixing Hooks (Fix and Reject)
+
+These hooks automatically fix issues but reject the commit so you can review changes:
+
+| Hook         | What it fixes             | Next steps                                                |
+| ------------ | ------------------------- | --------------------------------------------------------- |
+| **Prettier** | JS/TS/Markdown formatting | Review with `git diff`, then `git add .` and commit again |
+| **Rustfmt**  | Rust code formatting      | Review with `git diff`, then `git add .` and commit again |
+| **Nixfmt**   | Nix code formatting       | Review with `git diff`, then `git add .` and commit again |
+
+##### ❌ Check-Only Hooks (Reject Only)
+
+These hooks only check and reject commits - you must fix issues manually:
+
+| Hook             | What it checks              | How to fix                                       |
+| ---------------- | --------------------------- | ------------------------------------------------ |
+| **Clippy**       | Rust code quality           | `just fix-lint-rust` (auto-fixes some issues)    |
+| **Statix**       | Nix best practices          | `just fix-lint-nix` (auto-fixes most issues)     |
+| **Deadnix**      | Unused Nix code             | `just fix-lint-nix-deadcode` (removes dead code) |
+| **EditorConfig** | File formatting consistency | Manual fixes for whitespace, line endings, etc.  |
+
+### Quick Fixes Through the Lint Tool Itself
+
+```bash
+# After auto-fixing hooks (prettier, rustfmt, nixfmt):
+git diff                # Review the automatic changes
+git add .               # Stage the fixes
+git commit              # Try committing again
+
+# After check-only hooks (clippy, statix, deadnix):
+just fix-lint-rust      # Fix Clippy issues (auto-fixable ones)
+just fix-lint-nix       # Fix Statix issues
+just fix-lint-nix-deadcode  # Remove dead Nix code
+
+# For EditorConfig issues:
+just check-editorconfig # See specific violations
+# Then manually fix whitespace, line endings, etc.
+```
+
+### Composite Commands
+
+```bash
+# Fix all formatting at once
+just format
+
+# Fix all linting at once
+just lint-fix
+
+# Fix everything
+just fix-all
+
+# Check everything (without fixes)
+just check-all
+```
+
+### Manual Hook Management
+
+```bash
+# Run hooks manually on all files
+pre-commit run --all-files
+
+# Run specific hook
+pre-commit run prettier --all-files
+
+# Skip hooks for a commit (use sparingly)
+git commit --no-verify
+```
+
+### 🔍 Code Quality Commands
+
+#### Formatting
+
+| Command            | Description                           |
+| ------------------ | ------------------------------------- |
+| `just format`      | Format all code (JS/TS, Rust, Nix)    |
+| `just format-js`   | Format JavaScript/TypeScript/Markdown |
+| `just format-rust` | Format Rust code                      |
+| `just format-nix`  | Format Nix code                       |
+
+#### Linting
+
+| Command                  | Description                  |
+| ------------------------ | ---------------------------- |
+| `just lint`              | Run all linters (check only) |
+| `just lint-rust`         | Run Clippy on Rust code      |
+| `just lint-nix`          | Run Statix on Nix code       |
+| `just lint-nix-deadcode` | Check for dead Nix code      |
+
+#### Linting with Fixes
+
+| Command                      | Description                     |
+| ---------------------------- | ------------------------------- |
+| `just lint-fix`              | Run all linters with auto-fixes |
+| `just fix-lint-rust`         | Fix Rust issues with Clippy     |
+| `just fix-lint-nix`          | Fix Nix issues with Statix      |
+| `just fix-lint-nix-deadcode` | Remove dead Nix code            |
+
+#### Combined Commands
+
+| Command          | Description                          |
+| ---------------- | ------------------------------------ |
+| `just check-all` | Run all checks without fixes         |
+| `just fix-all`   | Run all formatting and linting fixes |
 
 ---
 
-### ✨ Commit Messages
+## ✨ Commit Messages
 
 ```
 <type><scope>: <subject>
@@ -154,7 +290,7 @@ Before committing, **format your code** using:
   - Must be parse-able by git interpret-trailers
   - BREAKING CHANGE: - needed for commits
 
-#### Commit Types
+### Commit Types
 
 - feat (_feature_) - Add new user-facing functionality or update a public API.
   - If the commit changes a library (and so its users are developers, not actual end-users), feat relates to its public API
@@ -211,4 +347,36 @@ Before committing, **format your code** using:
 Whenever you're stuck or do not know how to proceed, you can always ask for help.
 We invite you to use our [public Discord](https://discord.gg/b3xmcWs4Qp) to ask questions.
 
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### Pre-commit hooks taking too long
+
+```bash
+# Clear pre-commit cache
+pre-commit clean
+pre-commit install
+```
+
+#### Nix development shell issues
+
+```bash
+# Reload the environment
+direnv reload
+
+# Force rebuild
+nix develop --rebuild
+```
+
+#### Cargo/Rust build issues
+
+```bash
+# Clean build artifacts
+cargo clean
+
+# Update dependencies
+cargo update
+```
+
 ## [Git Tips & Tricks](./GITTIPS.md)
diff --git a/.github/SETUP.md b/.github/SETUP.md
@@ -17,6 +17,53 @@ direnv allow
 
 ---
 
+## 🚀 Development Workflow
+
+### Building and Testing
+
+```bash
+# Build TypeScript packages
+just build-ts
+
+# Test TypeScript packages
+just test-ts
+
+# Build Rust workspace
+cargo build --release
+
+# Build the full Blocksense system
+just build-blocksense
+
+# Start the system
+just start-blocksense
+```
+
+### Oracle Development
+
+```bash
+# Build a specific oracle
+just build-oracle crypto-price-feeds
+
+# Start an oracle with hot reload
+just start-oracle crypto-price-feeds
+```
+
+### Working with Smart Contracts
+
+```bash
+# Navigate to contracts directory
+cd libs/ts/contracts
+
+# Compile contracts
+yarn hardhat compile
+
+# Run tests
+yarn hardhat test
+
+# Deploy to a network
+yarn hardhat run scripts/deploy.ts --network <network>
+```
+
 # ⚡ Running the System
 
 ## ✅ Supported Deployment Options

diff --git a/Justfile b/Justfile
@@ -56,3 +56,116 @@ clean:
     -e .vscode \
     -e .pre-commit-config.yaml \
     -- {{root-dir}}
+
+# === FORMATTING COMMANDS ===
+
+format-js:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "📝 Formatting TypeScript/JavaScript/Markdown files..."
+  yarn prettier --write .
+
+format-rust:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "🦀 Formatting Rust files..."
+  cargo fmt
+
+format-nix:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "❄️  Formatting Nix files..."
+  nix fmt
+
+format:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "🔧 Running all formatters..."
+  just format-js
+  just format-rust
+  just format-nix
+  echo "✅ All formatting complete!"
+
+# === LINTING COMMANDS ===
+
+lint-rust:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "🦀 Running Clippy (Rust linter)..."
+  cargo clippy --all-targets --all-features
+
+lint-nix:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "❄️  Running Statix (Nix linter)..."
+  statix check .
+
+lint-nix-deadcode:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "🧹 Checking for dead Nix code..."
+  deadnix .
+
+lint:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "🔍 Running all linters..."
+  just lint-rust
+  just lint-nix
+  just lint-nix-deadcode
+  echo "✅ All linting complete!"
+
+# === LINTING FIX COMMANDS ===
+
+fix-lint-rust:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "🦀 Running Clippy with fixes..."
+  cargo clippy --fix --allow-dirty --allow-staged
+
+fix-lint-nix:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "❄️  Running Statix fixes..."
+  statix fix .
+
+fix-lint-nix-deadcode:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "🧹 Running Deadnix cleanup..."
+  deadnix --edit .
+
+lint-fix:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "🔍 Running linters with auto-fix..."
+  just fix-lint-rust
+  just fix-lint-nix
+  just fix-lint-nix-deadcode
+  echo "✅ All linting fixes complete!"
+
+# === EDITORCONFIG ===
+
+check-editorconfig:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "⚙️  Checking EditorConfig compliance..."
+  editorconfig-checker
+
+# === COMBINED COMMANDS ===
+
+check-all:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "🔍 Running all checks (formatting + linting + editorconfig)..."
+  just lint
+  just check-editorconfig
+  echo "✅ All checks complete!"
+
+fix-all:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  echo "🔧 Running all fixes (formatting + linting)..."
+  just format
+  just lint-fix
+  echo "✅ All fixes complete!"
diff --git a/libs/sdk/wit/deps/filesystem/types.wit b/libs/sdk/wit/deps/filesystem/types.wit
@@ -272,10 +272,10 @@ interface types {
     /// A 128-bit hash value, split into parts because wasm doesn't have a
     /// 128-bit integer type.
     record metadata-hash-value {
-       /// 64 bits of a 128-bit hash value.
-       lower: u64,
-       /// Another 64 bits of a 128-bit hash value.
-       upper: u64,
+      /// 64 bits of a 128-bit hash value.
+      lower: u64,
+      /// Another 64 bits of a 128-bit hash value.
+      upper: u64,
     }
 
     /// A descriptor is a reference to a filesystem object, which may be a file,