brane-research

name	brane-research
description	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.

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

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