title	description	tags	version	last_updated	status
Aiken Developer Reference Guide for AI Coding Assistants	Comprehensive Aiken smart contract development guide optimized for AI assistants and developers	aiken cardano smart-contracts ai-optimized plutus blockchain cryptocurrency	v1.1.15+	December 2024	mixed-security

Aiken Developer's Reference Guide for AI Coding Assistants

Welcome to the AI-optimized knowledge base for the Aiken smart contract language on Cardano. This guide is designed for developers and AI coding assistants (like Cursor, Cody, and GitHub Copilot) to quickly find, understand, and implement Aiken smart contracts.

Version Compatibility

Aiken Version: This guide is compatible with Aiken v1.1.15+ (tested v1.1.15 & v1.1.19)
Last Updated: December 2024
Status: 🚀 ENHANCED ARCHITECTURE - Branch-based quality separation implemented

🏗️ REPOSITORY STRUCTURE FOR VISITORS

This repository uses a unique branch-based quality architecture to ensure maximum safety and learning value:

📊 Choose Your Branch Based on Your Needs

🎯 Your Goal	🌟 Use This Branch	📋 What You'll Find	⚠️ Deployment Safety
Deploy to Production	main	✅ Audited, production-ready examples	✅ Safe for mainnet (with proper review)
Explore New Features	development	🔧 Latest features, functional implementations	⚠️ Development/testnet only
Learn Smart Contract Security	educational	📚 Security tutorials, vulnerability demonstrations	❌ Never deploy (learning only)

🚀 Quick Start for New Visitors

1. For Production Development → You're in the right place! (main branch)

• ✅ Production-ready examples: hello-world, escrow-contract
• ✅ Enterprise-grade security and documentation
• ✅ Safe for mainnet deployment with proper review

2. For Learning → Switch to educational branch

• 📚 Comprehensive security tutorials
• 🎓 Step-by-step vulnerability analysis
• ⚠️ Safe learning environment with intentional flaws for education

3. For Advanced Features → Check development branch

• 🔧 Cutting-edge Aiken patterns
• 🆕 Features in active development
• ⚠️ Functional but may have limitations

📖 Architecture Documentation

• Branch Strategy: BRANCH_STRATEGY.md
• Repository Navigation: NAVIGATION.md
• Security Status: SECURITY_STATUS.md

Mission

This reference provides a comprehensive, structured, and easily searchable set of documents covering the Aiken language, from basic syntax to advanced security patterns. The content is optimized for Large Language Models (LLMs) to ensure accurate and efficient code generation and problem-solving.

🚀 Quick Deploy with Monitoring

Deploy Changes with Real-Time Validation

# Deploy with real-time CI/CD monitoring
git add .
git commit -m "feat: update Aiken documentation"
git push origin main

# Monitor deployment status (requires gh CLI)
gh run list --limit 5
gh run watch  # Real-time workflow monitoring

# Check specific workflow status
gh run list --workflow="CI – Examples" --limit 3
gh run list --workflow="CI – Core" --limit 3

Advanced Monitoring & Validation

# Monitor all workflows simultaneously
gh api repos/:owner/:repo/actions/runs --jq '.workflow_runs[] | select(.status=="in_progress") | {name: .name, status: .status}'

# Check deployment health across all examples
gh workflow list
gh run view --log  # View detailed logs for troubleshooting

How to Use This Guide

Quick Start

• New to Aiken? Start with QUICK_START.md for a 5-minute setup guide
• Need Navigation? Use NAVIGATION.md to find exactly what you need

User Types

• AI Assistants: Ingest the docs/ directory to provide your language model with a deep understanding of Aiken. The modular structure allows for precise context-sourcing.
• Developers: Browse the docs/ directory to find specific topics. Each file is self-contained but links to related concepts, allowing for easy navigation.
• New Users: Follow the user journey paths in NAVIGATION.md for guided learning

Enhanced Repository Structure

🌟 Multi-Branch Architecture

🚀 main (Production Excellence)
├── examples/
│   ├── hello-world/           # ✅ Production-ready validator
│   └── escrow-contract/       # ✅ Enterprise-grade escrow
└── docs/                      # Production documentation

🔧 development (Active Innovation)
├── examples/
│   ├── nft-one-shot/          # 🔄 Advanced NFT features in progress
│   └── new-patterns/          # 🆕 Emerging Cardano integrations
└── docs/                      # Development documentation

📚 educational (Learning Excellence)
├── examples/
│   ├── security-tutorials/    # 📖 Step-by-step vulnerability education
│   └── fungible-token/        # ⚠️ Educational security demonstrations
└── docs/                      # Educational content & tutorials

📂 Common Structure (All Branches)

aiken/
├── README.md                    # Branch-specific overview
├── BRANCH_STRATEGY.md          # Quality architecture details
├── CONTENT_MIGRATION_PLAN.md   # Migration strategy
├── NAVIGATION.md               # Repository navigation guide
├── QUICK_START.md              # 5-minute setup guide
├── CONTRIBUTING.md             # Branch-specific contribution guidelines
├── .github/workflows/          # Enhanced CI/CD automation
│   ├── _reusable-production-check.yml  # Production quality gates
│   ├── production-promotion.yml        # Automated promotion system
│   ├── ci-examples-enhanced.yml        # Branch-aware validation
│   ├── quality-monitoring.yml          # Continuous quality assessment
│   └── [legacy workflows]              # Existing excellent workflows
├── docs/                       # Comprehensive documentation
│   ├── overview/              # Introduction and getting started
│   ├── language/              # Core language syntax and features
│   ├── patterns/              # Design patterns and best practices
│   ├── security/              # Security-first development
│   ├── code-examples/         # Working contract examples
│   ├── performance/           # Optimization and benchmarking
│   ├── integration/           # Off-chain tools and deployment
│   └── references/            # Quick reference and troubleshooting
└── scripts/                   # Branch management and quality tools

Documentation Sections

• docs/overview/: Introduction, ecosystem links, and getting started
• docs/language/: Core language syntax, features, and testing
• docs/patterns/: Common smart contract design patterns with code
• docs/security/: Security best practices, vulnerabilities, and checklists
• docs/code-examples/: Complete, real-world contract examples
• docs/performance/: Guides for optimizing on-chain execution costs
• docs/integration/: Off-chain integration, deployment, and monitoring
• docs/references/: Glossaries, links, and troubleshooting

Key Features

🏗️ Enhanced Architecture Excellence

• Branch-Based Quality: Production/Development/Educational separation for maximum safety
• Automated Promotion Gates: Comprehensive quality validation before production promotion
• Security-First Design: Zero-compromise security standards with clear safety guarantees
• Professional Credibility: Industry-grade reference trusted for production deployment

📚 Documentation Excellence

• LLM-Optimized: Short, declarative sentences and consistent, predictable structure
• Modular: Each topic is in its own file, making it easy for AI to find relevant context
• Code-Centric: Every concept is supported by working, syntax-highlighted code snippets
• Security Integrated: Security considerations are integrated into every relevant topic
• Cross-Referenced: Documents are linked to provide a cohesive learning path
• Branch-Aware: Documentation tailored to branch-specific quality standards

🚀 Production Readiness

• Main Branch Guarantee: All examples safe for production deployment (with proper review)
• Comprehensive Testing: >95% test coverage across all production examples
• Performance Benchmarked: All contracts include performance characteristics
• Cross-Version Compatibility: Validated across Aiken v1.1.15 & v1.1.19
• Enhanced CI/CD: Multi-branch validation with automated quality gates
• Professional Documentation: Enterprise-grade documentation standards

---

This guide is maintained to reflect the latest stable version of Aiken. For bleeding-edge features, always consult the official Aiken documentation.