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:

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:

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:

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<LogEntry>
   • 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)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.