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