organvm-iv-taxis/blockchain-integration-builder

Blockchain Integration Builder

Design blockchain systems using universal patterns applicable across chains.

Core Abstractions

Blockchain-agnostic thinking: focus on what you're trying to achieve, then select chain/framework.

Fundamental Primitives

| Primitive | What It Is | Chain Examples | |-----------|------------|----------------| | Account | Identity with balance | EOA (Eth), Wallet (Solana), Account (Near) | | Transaction | State change request | Signed message + gas | | Block | Batch of transactions | Time-ordered, immutable | | Contract | On-chain program | Solidity, Rust, Move | | Event/Log | Indexed side-effect | Emitted by contracts, queryable | | State | Persistent data | Mappings, storage slots |

Selection Criteria

| Need | Consider | Why | |------|----------|-----| | Programmability | Ethereum, Arbitrum, Base | Mature tooling, EVM ecosystem | | Speed/Cost | Solana, Sui, Aptos | High throughput, low fees | | Privacy | Aztec, Zcash | Zero-knowledge proofs | | Interoperability | Cosmos, Polkadot | Cross-chain communication | | Simplicity | Bitcoin, Litecoin | Limited scripting, proven security |

Pattern Library

Identity Patterns

Wallet-Based Identity

User → Wallet → Sign Message → Verify Signature → Authenticated

• No passwords stored
• User controls identity
• Works across applications

Soul-Bound Tokens (SBTs)

Issuer → Mint SBT → User Wallet (non-transferable)

• Credentials, achievements, reputation
• Cannot be sold or transferred
• Revocable by issuer (optionally)

Decentralized Identifiers (DIDs)

did:method:identifier → Resolve → DID Document → Public Keys, Services

• Self-sovereign identity
• Cross-chain portable
• W3C standard

Token Patterns

Fungible Tokens (ERC-20 pattern)

// Universal interface
balanceOf(address) → uint256
transfer(to, amount) → bool
approve(spender, amount) → bool
transferFrom(from, to, amount) → bool

Non-Fungible Tokens (ERC-721 pattern)

// Universal interface
ownerOf(tokenId) → address
transferFrom(from, to, tokenId)
tokenURI(tokenId) → string (metadata)

Semi-Fungible (ERC-1155 pattern)

// Batch operations, mixed fungible/non-fungible
balanceOf(account, id) → uint256
balanceOfBatch(accounts[], ids[]) → uint256[]
safeTransferFrom(from, to, id, amount, data)

Governance Patterns

Token Voting

Proposal → Snapshot Balances → Vote Period → Tally → Execute (if passed)

Quadratic Voting

Cost of N votes = N² tokens
Reduces plutocratic dominance

Optimistic Governance

Proposal → Challenge Period → Execute if unchallenged

Economic Patterns

Bonding Curves

Price = f(Supply)
Buy: Price increases with supply
Sell: Price decreases with supply
Creates automatic market making

Staking/Slashing

Stake tokens → Perform duties → Earn rewards
Misbehave → Lose stake (slashing)

Streaming Payments

Deposit → Linear unlock over time → Recipient claims

Architecture Patterns

On-Chain vs Off-Chain

| Aspect | On-Chain | Off-Chain | |--------|----------|-----------| | Cost | High (gas fees) | Low/free | | Speed | Slow (block time) | Fast | | Trust | Trustless | Requires trust | | Privacy | Public | Can be private | | Storage | Expensive | Cheap |

Hybrid approach:

Off-chain: Computation, storage, user experience
On-chain: Verification, settlement, ownership
Bridge: Oracles, merkle proofs, signatures

Indexing Pattern

Blockchain data is hard to query directly. Use indexers:

Blockchain → Events → Indexer → Database → API → Frontend

Tools: The Graph, Goldsky, custom indexers

Oracle Pattern

Bring external data on-chain:

External Data → Oracle Network → Consensus → On-chain Value

Use cases: Price feeds, random numbers, API data

Security Principles

Smart Contract Security

1. Check-Effects-Interactions: Update state before external calls
2. Reentrancy Guards: Prevent recursive calls
3. Access Control: Verify caller permissions
4. Input Validation: Never trust user input
5. Upgrade Patterns: Plan for bug fixes (proxies, migrations)

Common Vulnerabilities

| Vulnerability | Description | Prevention | |---------------|-------------|------------| | Reentrancy | Recursive calls drain funds | Checks-effects-interactions | | Integer overflow | Math wraps around | SafeMath or Solidity 0.8+ | | Front-running | Miners/validators see pending txs | Commit-reveal, flashbots | | Oracle manipulation | Fake price data | Multiple oracles, TWAP | | Access control | Missing permission checks | Role-based access |

Integration Workflow

1. Define Requirements

• What needs to be trustless?
• What can stay off-chain?
• Who are the actors?
• What are the assets?

2. Select Chain

Based on: throughput needs, cost constraints, ecosystem fit, team expertise

3. Design Contracts

• Keep contracts simple and focused
• Separate concerns into multiple contracts
• Plan upgrade path

4. Build Indexing

• Determine query patterns
• Index relevant events
• Build API layer

5. Create Frontend

• Wallet connection
• Transaction signing
• State display
• Error handling

6. Test & Audit

• Unit tests
• Integration tests
• Formal verification (for critical contracts)
• Third-party audit

References

• references/contract-patterns.md - Common smart contract patterns
• references/chain-comparison.md - Chain-specific considerations