@danogo-js/sdk

DanogoJS SDK

TypeScript SDK for Cardano blockchain development, providing high-level abstractions for smart contract deployment, NFT/FT minting, and blockchain interactions. Built with Bun runtime and Evolution SDK.

Core Components

SDK Architecture

• Deployer: Abstract base class with manager composition pattern for contract deployment
• Blueprint Utils: Plutus blueprint code generation using Evolution SDK v0.5.2+ native codegen
• Koios API Client: Blockchain data provider with stable API endpoints. See API Documentation
• Provider Factory: Automatic provider selection (Kupmios, Blockfrost, Maestro) based on environment configuration

Manager Classes

The Deployer uses specialized managers for different concerns with definite assignment semantics:

• UTxO Manager: UTxO preparation, fund management, reference script handling, and input exclusion
• Minting Manager: NFT/FT minting operations and asset management
• Protocol Manager: Protocol UTxO lifecycle operations with datum management
• Script Manager: Script deployment, validation, and reference script management
• Transaction Manager: Transaction building, submission, and confirmation with robust option handling

CLI Tools

• CBOR Parser: Parse Cardano transaction CBOR and generate Aiken test snippets
• Blueprint Generator: Convert Plutus blueprints to strongly-typed TypeScript interfaces

Usage

Installation

npm install @danogo-js/sdk
# or
bun add @danogo-js/sdk

Basic Deployer Pattern

import { Deployer } from '@danogo-js/sdk';

class MyDeployer extends Deployer {
  async deploy() {
    // UTxO preparation is automatic via run() lifecycle
    const fundUtxo = this.utxoManager!.getFundUtxo();

    // Deploy validators as reference scripts
    await this.scriptManager!.deployNewScript(validator);

    // Mint NFTs/FTs with metadata
    const nft = await this.mintingManager!.mintNft(assets, metadata);

    // Deploy protocol UTxOs
    await this.protocolManager!.deployProtocolUtxo(datum, assets);
  }
}

// Usage
const deployer = new MyDeployer();
await deployer.run(); // Handles full lifecycle

CLI Tools

# Generate TypeScript from Plutus blueprint
bun danogo blueprint src/plutus/contract.json src/generated/contract.ts

# Parse transaction CBOR and generate Aiken tests
bun danogo cbor --input tx.cbor --output test.ak

# Get help for any command
bun danogo --help
bun danogo blueprint --help
bun danogo cbor --help

Development Workflow

Environment Setup

Required environment variables:

NETWORK=Preview|Preprod|Mainnet

# Choose at least ONE of these provider configurations:
# Option 1: Kupmios (local development)
KUPO_ENDPOINT=http://localhost:1442
OGMIOS_ENDPOINT=ws://localhost:1337

# Option 2: Blockfrost (cloud provider)
BLOCKFROST_URL=https://cardano-preview.blockfrost.io/api/v0
BLOCKFROST_PROJECT_ID=preview...

# Option 3: Maestro (alternative cloud provider)
MAESTRO_URL=https://mainnet.maestroapi.com
MAESTRO_API_KEY=your_api_key

# Optional for additional features
KOIOS_URL=your_koios_url
KOIOS_TOKEN=your_koios_id

The SDK automatically selects a provider based on available environment variables (Blockfrost → Maestro → Kupmios priority).

Build & Publish

Build Process

# Build main library
bun run build:sdk

# Build CLI scripts
bun run build:scripts

# Build both (recommended)
bun run build

# Type checking
bun run typecheck

Publishing

Publishing is done from the /dist directory after building:

# Update version in package.json if needed
bun publish

Architecture Highlights

Manager Composition Pattern

The Deployer uses composition with definite assignment for specialized managers:

export abstract class Deployer {
  // Managers are initialized during run() with definite assignment
  declare utxoManager: DeployerUtxoManager;
  declare mintingManager: DeployerMintingManager;
  declare protocolManager: DeployerProtocolManager;
  declare scriptManager: DeployerScriptManager;
  declare txManager: DeployerTransactionManager;

  async run() {
    await this.createClientInstance();
    await this.initializeManagers(); // Guarantees all managers are assigned
    await this.utxoManager.prepareFundUtxos();
    await this.deploy(); // Your implementation
  }
}

UTxO Management Strategy

• Fund UTxOs: Clean UTxOs (≥100 ADA, no extra assets) reserved for reliable transaction fees with exclusion support
• Operational UTxOs: Used for non-funding operations to avoid conflicts and enable parallel transactions
• Reference Scripts: Deployed as reference UTxOs for cost reduction and proper credential handling
• Input Exclusion: Supports excluding specific UTxOs from selection for fine-grained control

Provider Support

The SDK now supports multiple blockchain data providers with automatic selection:

• Kupmios: Full-featured local indexer (KUPO + Ogmios) - best for development
• Blockfrost: Simple cloud-based provider with full Cardano support
• Maestro: Feature-rich cloud provider with advanced query capabilities
• Automatic Selection: The provider factory automatically chooses the best available provider based on environment configuration

Key Benefits

• Type Safety: Full TypeScript with native Evolution SDK code generation
• Cost Efficient: Reference script pattern reduces transaction costs
• Multi-Provider: Flexible provider selection for different environments
• Reliable: Definite assignment eliminates null coalescing in hot paths
• Extensible: Manager pattern allows easy customization and testing
• Production Ready: Battle-tested with comprehensive error handling