# Brane Research > Research EVM SDK patterns from viem (TypeScript) and alloy (Rust) when designing Brane features. Use when implementing new functionality, designing APIs, or solving problems that other SDKs have already addressed. Use when this capability is needed. - Skill: `tomevault-io/brane-research` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/brane-research` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/brane-research/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/brane-research --- # Brane SDK Research ## Purpose When implementing Brane features, reference how mature EVM SDKs solve the same problems: - **viem** (TypeScript) - Modern, type-safe, excellent documentation - **alloy** (Rust) - Performance-focused, similar design philosophy to Brane These SDKs have solved many of the same problems. Learn from their API design, naming conventions, and implementation patterns. --- ## Reference Sources ### viem (TypeScript) - **Documentation**: https://viem.sh - **GitHub**: https://github.com/wevm/viem - **Key strengths**: Excellent docs, modern API, comprehensive examples ### alloy (Rust) - **Documentation**: https://alloy.rs - **GitHub**: https://github.com/alloy-rs/alloy - **Key strengths**: Type safety, performance, similar goals to Brane --- ## When to Research Use this skill when: 1. **Designing new APIs** - How do viem/alloy name this? What parameters do they use? 2. **Implementing features** - What edge cases did they handle? 3. **Solving problems** - Has this been solved before? How? 4. **Naming things** - What's the conventional name for this concept? --- ## Research Workflow ### Step 1: Identify the Feature Area Map your Brane feature to the equivalent concept: | Brane Area | viem Equivalent | alloy Equivalent | |------------|-----------------|------------------| | `Brane.Reader` | `publicClient` / `PublicActions` | `Provider` | | `Brane.Signer` | `walletClient` / `WalletActions` | `Signer` + `Provider` | | `BraneContract.bind()` | `getContract()` | `ContractInstance` | | `TransactionRequest` | `TransactionRequest` | `TransactionRequest` | | `Address`, `Hash`, `HexData` | Branded types | `Address`, `B256`, `Bytes` | | ABI encoding | `encodeFunctionData` | `SolCall::abi_encode` | | ABI decoding | `decodeFunctionResult` | `SolCall::abi_decode` | | Gas estimation | `estimateGas` | `estimate_gas` | | Transaction receipt | `waitForTransactionReceipt` | `get_transaction_receipt` | ### Step 2: Fetch Documentation Use WebFetch to read the relevant documentation: ``` # viem examples https://viem.sh/docs/actions/public/getBalance https://viem.sh/docs/contract/readContract https://viem.sh/docs/actions/wallet/sendTransaction # alloy examples https://alloy.rs/examples/providers/builder.html https://alloy.rs/examples/contracts/deploy.html ``` ### Step 3: Compare and Adapt When adapting patterns to Java/Brane: | viem/alloy Pattern | Brane Adaptation | |-------------------|------------------| | Async/await | Blocking calls (Java's virtual threads handle concurrency) | | Generic type parameters | Java generics or method overloads | | Builder pattern | Same (Java builders work well) | | Result/Option types | Exceptions + Optional | | Branded types | Record types with validation | --- ## Common Research Scenarios ### Scenario: Implementing a new RPC method 1. Check viem docs for the action: `https://viem.sh/docs/actions/public/{methodName}` 2. Note the parameters, return type, and edge cases 3. Check if alloy has additional insights in their examples ### Scenario: Designing a new type 1. Look at viem's type definitions in their TypeScript source 2. Look at alloy's type definitions (usually in `alloy-primitives` or `alloy-rpc-types`) 3. Adapt to Java records with validation ### Scenario: Handling errors 1. Check viem's error types: https://viem.sh/docs/glossary/errors 2. See how they categorize and present errors 3. Map to Brane's exception hierarchy ### Scenario: Gas estimation strategy 1. viem: https://viem.sh/docs/actions/public/estimateGas 2. alloy: Check their provider examples 3. Note buffer strategies, EIP-1559 handling --- ## API Naming Conventions Learn from viem/alloy naming patterns: | Concept | viem | alloy | Brane (adopt) | |---------|------|-------|---------------| | Read contract | `readContract` | `call` | `call` or `read` | | Write contract | `writeContract` | `send_transaction` | `sendTransaction` | | Get balance | `getBalance` | `get_balance` | `getBalance` | | Get block | `getBlock` | `get_block` | `getBlock` | | Wait for receipt | `waitForTransactionReceipt` | `watch_pending_transaction` | `sendTransactionAndWait` | --- ## Key Documentation Pages ### viem - Bookmark These - **Public Actions**: https://viem.sh/docs/actions/public/introduction - **Wallet Actions**: https://viem.sh/docs/actions/wallet/introduction - **Contract**: https://viem.sh/docs/contract/introduction - **ABI**: https://viem.sh/docs/abi/introduction - **Utilities**: https://viem.sh/docs/utilities/introduction - **Errors**: https://viem.sh/docs/glossary/errors ### alloy - Bookmark These - **Book/Guide**: https://alloy.rs - **Examples**: https://alloy.rs/examples/ - **API Docs**: https://docs.rs/alloy/latest/alloy/ --- ## Example Research Session **Task**: Implement `eth_getLogs` with filter support **Research steps**: 1. **viem docs**: Fetch https://viem.sh/docs/actions/public/getLogs - Note: filter parameters, block range handling, topics array format - Note: How they handle "block range too large" errors 2. **alloy examples**: Check their filtering examples - Note: Type definitions for LogFilter 3. **Adapt to Brane**: - Create `LogFilter` record with builder - Return `List` - Handle block range errors with `RpcException.isBlockRangeTooLarge()` --- ## Things viem/alloy Do Well (Learn From) 1. **Type safety** - Both have strong typing; Brane should too 2. **Ergonomic APIs** - Easy common cases, flexible advanced cases 3. **Good defaults** - Sensible defaults, explicit overrides 4. **Error messages** - Clear, actionable error messages 5. **Documentation** - Examples for every feature --- ## Things to Adapt (Not Copy Directly) | Pattern | Why Adapt | |---------|-----------| | Async everywhere | Java uses blocking + virtual threads | | Function overloading via types | Java uses method overloading | | Optional chaining | Java uses Optional or null checks | | Destructuring | Java uses record accessors | --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/noise-xyz) — claim your Tome and manage your conversions.