TypeScript-first Cardano development with static type inference
Build robust Cardano applications with modern TypeScript, functional programming, and comprehensive type safety.
๐ Documentation โข ๐ Quick Start โข ๐ก Examples โข ๐ค Contributing
Evolution SDK is a TypeScript-first Cardano development framework. Define your data schemas and build transactions with full type safety. You'll get back strongly typed, validated results with comprehensive error handling.
import { Address, Transaction, Coin, Devnet } from "@evolution-sdk/evolution"
// Define and validate a Cardano address
const address = Address.Codec.Decode.bech32(
"addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3jcu5d8ps7zex2k2xt3uqxgjqnnj0vs2qd4a8cpkp0k8cqq0sq2nq"
)
// Convert between formats with type safety
const addressHex = Address.Codec.Encode.hex(address)
const addressBytes = Address.Codec.Encode.bytes(address)
// Work with CBOR data confidently using Codec
const transaction = Transaction.Codec.Decode.hex("84a3008282...")
const coin = Coin.Codec.Decode.bytes(coinBytes)
// Effect-powered error handling
const addressEffect = Address.Codec.DecodeEffect.bech32(
"addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3jcu5d8ps7zex2k2xt3uqxgjqnnj0vs2qd4a8cpkp0k8cqq0sq2nq"
)
// Start a local development network instantly
const devnet = await Devnet.Cluster.start({
kupo: { enabled: true },
ogmios: { enabled: true }
})
โข Zero runtime errors - Comprehensive TypeScript types for all Cardano primitives
โข Effect-powered - Built on Effect for robust error handling and async operations
โข Blazing fast - Modern tooling with hot reload and optimized builds
โข DevNet ready - Local blockchain development with Docker integration
โข Modular design - Tree-shakeable exports for minimal bundle size
โข CBOR first-class - Native support for Cardano's binary format
โข Battle-tested - Production-ready with comprehensive test coverage
npm install @evolution-sdk/evolution
import { Address, TransactionHash, Devnet } from "@evolution-sdk/evolution"
// Create and validate addresses
const address = Address.Codec.Decode.bech32(
"addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3jcu5d8ps7zex2k2xt3uqxgjqnnj0vs2qd4a8cpkp0k8cqq0sq2nq"
)
// Handle transactions with type safety
const txHash = TransactionHash.Codec.Decode.hex("915cb8b7b58c6a4db9ff6c0c4b6e6e9b4c8b5a6f4e6e8a5b2c9d8f7e1a4b3c2d1")
// Start a development network
const devnet = await Devnet.Cluster.makeOrThrow({
clusterName: "my-devnet",
kupo: { enabled: true },
ogmios: { enabled: true }
})
await Devnet.Cluster.startOrThrow(devnet)
Evolution SDK provides comprehensive type inference for all Cardano primitives:
import { Address, CBOR, Effect } from "@evolution-sdk/evolution"
// Type-safe CBOR operations
const encoded = CBOR.Codec.Encode.bytes(myData) // Uint8Array
const decoded = CBOR.Codec.Decode.bytes(encoded) // Decoded data
// Effect-powered error handling
const result = await Effect.runPromise(
Address.Codec.DecodeEffect.bech32(bech32String)
)
Evolution SDK is built as a single package with a clean, modular structure that's ready for future expansion:
evolution-sdk/
โโโ ๐ฆ packages/
โ โโโ evolution/ # Main SDK package
โ โโโ src/
โ โ โโโ Address.ts # Address utilities
โ โ โโโ Transaction.ts # Transaction building
โ โ โโโ Devnet/ # Development network tools
โ โ โโโ ...
โ โโโ dist/ # Compiled output
โโโ ๐ docs/ # Documentation
โโโ ๐งช examples/ # Usage examples
โโโ turbo.json # Turbo configuration
โโโ pnpm-workspace.yaml # Workspace configuration
โโโ flake.nix # Nix development environment
The monorepo structure is designed to accommodate additional packages.
Package | Description | Status | Documentation |
---|---|---|---|
@evolution-sdk/evolution |
Complete Cardano SDK with address management, transactions, and DevNet tools | ๐ง In Development | README |
- ๐ Address Management: Create, validate, and convert Cardano addresses
- ๐ฐ Transaction Building: Construct and serialize transactions with type safety
- ๐ง CBOR Encoding/Decoding: Handle Cardano's binary data format
- ๐ Network Utilities: Tools for different Cardano networks
- ๐ณ DevNet Integration: Local development blockchain with Docker
- ๐ Data Schemas: Comprehensive Cardano data type definitions
# Clone the repository
git clone https://github.com/no-witness-labs/evolution-sdk.git
cd evolution-sdk
# Enter Nix development shell (optional but recommended)
nix develop
# Install dependencies
pnpm install
# Build all packages
pnpm turbo build
# Start development mode with file watching
pnpm turbo dev
# Run type checking
pnpm turbo type-check
Command | Description |
---|---|
pnpm turbo build |
Build the package with optimal caching |
pnpm turbo dev |
Start development mode with hot reload |
pnpm turbo type-check |
Run TypeScript type checking |
pnpm turbo test |
Run all tests (when available) |
pnpm turbo lint |
Run code quality checks |
pnpm turbo clean |
Clean all build artifacts |
TypeScript |
Turbo |
Effect |
Docker |
Nix |
For comprehensive guides, tutorials, and interactive examples, visit our official documentation.
Complete API documentation with type definitions and examples is available in our API reference.
- Getting Started Guide - Your first steps with Evolution SDK
- Examples Repository - Real-world usage examples and patterns
- Video Tutorials - Visual guides for complex topics
- Migration Guide - Upgrading from other Cardano libraries
Get started with Evolution SDK by watching our introductory video: Introduction to Evolution SDK โ
Join our thriving community of Cardano developers:
- ๐ฌ Discord - Get help, share projects, and discuss development
- X - Latest announcements and ecosystem updates
- ๐ GitHub Issues - Bug reports and feature requests
- ๐ก GitHub Discussions - Questions, ideas, and community showcases
- Found a bug? Open an issue with a minimal reproduction
- Need help? Ask in our Discord community
- Have an idea? Start a discussion on GitHub
- Want to contribute? Check our contribution guide
- Core SDK Foundation
- TypeScript package setup with strict typing
- Modern build configuration with Turbo
- Comprehensive Cardano primitive types (78 modules)
- Codec pattern for all data operations
- Effect integration for error handling
- Docker DevNet integration
- ESM module format with tree-shaking
- Complete type definitions and IntelliSense
- Address Management (10 modules)
-
Address
- Core address utilities with bech32/hex encoding -
BaseAddress
,ByronAddress
,EnterpriseAddress
- All address types -
PaymentAddress
,PointerAddress
,RewardAddress
- Specialized addresses -
AddressDetails
,AddressTag
,StakeReference
- Address metadata
-
- Transaction Handling (7 modules)
-
Transaction
,TransactionBody
,TransactionHash
- Core transaction -
TransactionInput
,TransactionOutput
,TransactionIndex
- I/O handling -
TransactionMetadatumLabels
- Metadata support
-
- Cryptography & Security (9 modules)
-
Ed25519Signature
,KesSignature
,VrfCert
- Digital signatures -
Hash28
,KeyHash
,VrfKeyHash
- Hash utilities -
VKey
,KESVkey
,VrfVkey
- Verification keys
-
- Value & Assets (7 modules)
-
Coin
,PositiveCoin
,Value
- ADA and multi-asset handling -
MultiAsset
,AssetName
,PolicyId
- Asset management -
Mint
- Minting operations
-
- Scripts & Certificates (7 modules)
-
Certificate
,NativeScripts
,NativeScriptJSON
- Script support -
ScriptDataHash
,ScriptHash
,ScriptRef
- Script utilities
-
- Governance & Staking (12 modules)
-
DRep
,DRepCredential
,VotingProcedures
- Governance -
ProposalProcedures
,CommitteeColdCredential
,CommitteeHotCredential
- Committee -
PoolKeyHash
,PoolMetadata
,PoolParams
- Pool management -
Withdrawals
,Credential
- Staking operations
-
- Network & Communication (11 modules)
-
Network
,NetworkId
,Relay
- Network utilities -
IPv4
,IPv6
,Port
,DnsName
,Url
- Network addressing -
SingleHostAddr
,SingleHostName
,MultiHostName
- Host management
-
- Data Types & Primitives (15 modules)
-
Bytes
,BoundedBytes
+ 8 fixed-size byte arrays -
Text
,Text128
,BigInt
,Natural
- Text and numeric types -
NonZeroInt64
,Numeric
,UnitInterval
- Specialized numbers
-
- Blockchain Primitives (12 modules)
-
Block
,BlockBodyHash
,BlockHeaderHash
- Block structure -
Header
,HeaderBody
,EpochNo
- Block components -
AuxiliaryDataHash
,OperationalCert
,ProtocolVersion
- Protocol -
Pointer
,Anchor
,RewardAccount
- Blockchain references
-
- Core Utilities (8 modules)
-
CBOR
,Codec
,Combinator
- Core encoding/decoding -
Data
,DataJson
,DatumOption
- Data handling -
Bech32
,FormatError
- Utilities and error handling
-
- Development Tools (2 modules)
-
Devnet
,DevnetDefault
- Local development network
-
- Transaction Builder Components
- Transaction builder with fluent API
- UTXO selection algorithms
- Fee calculation utilities
- Balance and change computation
- Multi-asset transaction support
- Script witness attachment
- Provider Integrations
-
Maestro
- Maestro API provider -
Blockfrost
- Blockfrost API provider -
Koios
- Koios API provider -
KupoOgmios
- Kupo/Ogmios provider -
UtxoRpc
- UTXO RPC provider - Provider abstraction layer
- Failover and load balancing
-
- Wallet Integration
- Hardware wallet support (Ledger, Trezor)
- Browser wallet integration (Nami, Eternl, Flint)
- Multi-signature wallet support
- Wallet connector abstraction layer
- CIP-30 standard implementation
- Smart Contract Support
- UPLC evaluation from Aiken
- UPLC evaluation from Helios
- UPLC evaluation from Plu-ts
- UPLC evaluation from Scalus
- Script validation utilities
- Datum and redeemer handling
- Script cost estimation
- Effect 4.0 Migration
- Upgrade to Effect 4.0 when released
- Leverage new Effect features and performance improvements
- Update all Codec and Error handling patterns
- Maintain backward compatibility where possible
- Enhanced DevNet (Completed)
- Custom network configuration
- Automated testing framework
- Transaction simulation
- Performance monitoring
- Hydra Integration
- Hydra Head management
- State channel operations
- Off-chain transaction handling
- Hydra Head lifecycle management
- Layer 2 scaling utilities
- DeFi Primitives
- DEX integration utilities
- Liquidity pool management
- Yield farming helpers
- NFT marketplace tools
- Developer Experience
- CLI tool for project scaffolding
- VS Code extension
- Interactive tutorials
- Schema types from Plutus blueprint types
We're currently prioritizing transaction building components and provider integrations (Maestro, Blockfrost, Koios, Kupo/Ogmios, UTXO RPC) to provide developers with the essential infrastructure needed for building production Cardano applications.
We love your input! We want to make contributing to Evolution SDK as easy and transparent as possible.
-
Fork and clone the repository
git clone https://github.com/your-username/evolution-sdk.git cd evolution-sdk
-
Install dependencies
pnpm install
-
Start development
pnpm turbo dev
-
Make your changes and test them
pnpm turbo build pnpm turbo type-check
-
Create a pull request
Command | Description |
---|---|
pnpm turbo build |
Build all packages with optimal caching |
pnpm turbo dev |
Start development mode with hot reload |
pnpm turbo type-check |
Run TypeScript type checking |
pnpm turbo test |
Run all tests |
pnpm turbo lint |
Run code quality checks |
pnpm turbo clean |
Clean all build artifacts |
- ๐ Bug fixes - Help us squash those pesky issues
- โจ New features - Extend Evolution SDK's capabilities
- ๐ Documentation - Improve guides, examples, and API docs
- ๐งช Tests - Increase our test coverage
- ๐จ Examples - Show off creative use cases
- ๐ Performance - Make Evolution SDK even faster
- Follow TypeScript best practices - Use strict typing and modern patterns
- Add tests for new features and bug fixes
- Update documentation when adding new APIs
- Keep changes focused - One feature/fix per pull request
- Follow conventional commits - Use clear, descriptive commit messages
Read our full Contribution Guide for detailed guidelines.
This project is licensed under the MIT License - see the LICENSE file for details.
Help us build the future of Cardano development
Your sponsorship helps us maintain Evolution SDK, create educational content, and support the community.
Evolution SDK builds on the incredible work of:
- ๐๏ธ Turborepo - For the incredible build system
- โก Effect - For functional programming excellence
- Our contributors - Building the future together
Built with โค๏ธ by No Witness Labs
โญ Star us on GitHub โข Follow on X โข ๐ฌ Join Discord
๐ Read the docs to get started building with Evolution SDK