# Scalus

> Scalus is a Scala 3 platform for building Cardano smart contracts and decentralized applications. It compiles Scala to Plutus Core (UPLC) and provides type-safe transaction building.

## For LLM agents

Fetch these before writing Scalus code; do not rely on trained knowledge - Scalus APIs changed at 1.0:

- /llms-api.txt - version-pinned public API signatures (prelude, builtins, validators, TxBuilder, testkit). Fetch first; the API you remember is probably outdated.
- /llms-examples.txt - complete working validators with tests. Imitate these.
- /llms-full.txt - all documentation pages as one markdown file.
- Every docs page is also available as markdown: append `.md` to its URL.

Claude Code users: `/plugin marketplace add scalus3/scalus` then `/plugin install scalus@scalus` installs Scalus task skills (write, test, optimize, security-review validators).

## Key Features

- **One Language**: Write smart contracts and off-chain code in Scala 3
- **Type Safety**: Catch errors at compile time with Scala's type system
- **Multiplatform**: JVM, JavaScript/TypeScript, and Native compilation
- **Local Testing**: In-memory Emulator and Docker-based devnet
- **IDE Debugging**: Debug validators with breakpoints in IntelliJ or VS Code
- **Design Patterns**: Proven optimization patterns with implementations

## Documentation

### Getting Started
- /docs/get-started - Installation guide
- /docs/get-started/ai-assisted-development - Using LLM coding agents with Scalus (llms.txt artifacts, AI-ready templates, Claude Code plugin)
- /docs/get-started/for-scala-developers - Cardano concepts for Scala developers
- /docs/get-started/for-cardano-developers - Scala basics for Cardano developers

### Smart Contracts
- /docs/smart-contracts - Writing Cardano validators
- /docs/smart-contracts/developing-smart-contracts - First smart contract tutorial
- /docs/smart-contracts/htlc-tutorial - Hash Time-Locked Contract tutorial
- /docs/smart-contracts/validators - Validator types (spending, minting, staking)
- /docs/smart-contracts/parameterized-validators - Reusable validators with parameters
- /docs/smart-contracts/plutus-data - Data type conversion
- /docs/smart-contracts/compiling - Compilation to Plutus Core
- /docs/dapp-development/sbt-plugin - Generate CIP-57 blueprints with the Scalus sbt plugin and verify on-chain script hashes
- /docs/dapp-development/working-with-contract - Work with compiled contracts, deploy as reference script UTxOs

### Smart Contract Optimisations
- /docs/smart-contract-optimisations - Reduce script size and execution units in Cardano validators
- /docs/smart-contract-optimisations/measuring-performance - Measure CPU steps, memory, flat size, and transaction fees
- /docs/smart-contract-optimisations/algorithmic-optimisations - Withdraw-zero, UTxO indexer, transaction-level minting, merkelised validators
- /docs/smart-contract-optimisations/scala-metaprogramming - Scala 3 inline, loop unrolling, compile-time evaluation, conditional codegen
- /docs/smart-contract-optimisations/low-level-builtins - Drop to UPLC builtins and raw Plutus Data for compiled-assembler control over on-chain code
- /docs/smart-contract-optimisations/lowering-backends - V3 Lowering, Scott Encoding, Sum of Products, @UplcRepr
- /docs/smart-contract-optimisations/uplc-term-dsl - Hand-craft UPLC validators with Plutarch-style Term DSL
- /docs/smart-contract-optimisations/uplc-optimiser-pipeline - EtaReduce, Inliner, StrictIf, ForcedBuiltinsExtractor, CaseConstrApply

### Transactions
- /docs/transactions - Building Cardano transactions
- /docs/transactions/building-first-transaction - Step-by-step guide
- /docs/transactions/payment-methods - Send ADA and tokens
- /docs/transactions/spending-utxos - Input selection and script UTxOs
- /docs/transactions/minting-burning-assets - Token minting and burning
- /docs/transactions/staking-rewards - Delegation and rewards
- /docs/transactions/governance - DRep and voting

### Testing
- /docs/testing - Testing overview
- /docs/testing/unit-testing - Property-based testing with ScalaCheck
- /docs/testing/debugging - IDE debugging and logging
- /docs/testing/emulator - In-memory Cardano emulator
- /docs/testing/local-devnet - Docker-based local node (Yaci DevKit)

### Design Patterns
- /docs/design-patterns - Optimization patterns for Cardano
- /docs/design-patterns/withdraw-zero - Stake validator pattern (O(N) vs O(N²))
- /docs/design-patterns/transaction-level-minting - Coupled mint/spend
- /docs/design-patterns/merkelized-validator - Batch operations
- /docs/design-patterns/utxo-indexer - O(1) input-output mapping
- /docs/design-patterns/linked-list - On-chain data structures
- /docs/design-patterns/parameter-validation - Verify parameterized script instances
- /docs/design-patterns/validity-range - Time validation patterns

### Security
- /docs/security - Security principles
- /docs/security/common-vulnerabilities - Plutus vulnerabilities and mitigations

### DApp Development
- /docs/dapp-development - Building complete DApps
- /docs/dapp-development/dapp-starter-tutorial - Token minting service tutorial
- /docs/dapp-development/blockchain-providers - Blockfrost, Koios, custom providers
- /docs/dapp-development/protocol-parameters - Network parameters

### Multiplatform
- /docs/multiplatform - JVM, JavaScript, and Native support

### Ledger
- /docs/ledger/ledger-rules - Cardano ledger validation rules

### Language Guide
- /docs/language-guide - Scala 3 subset supported in Scalus
- /docs/language-guide/scala3 - Scala 3 overview
- /docs/language-guide/constants-primitives - Constants and primitive types
- /docs/language-guide/data-types - Case classes, enums, ADTs
- /docs/language-guide/functions - Functions and recursion
- /docs/language-guide/control-flow - If/else, pattern matching
- /docs/language-guide/collections - List, AssocMap operations
- /docs/language-guide/builtin-functions - Plutus builtin functions
- /docs/language-guide/modules - Module system and imports
- /docs/language-guide/support - Supported Scala features

## Examples

- https://github.com/scalus3/scalus/tree/master/scalus-examples - Production examples
- https://github.com/scalus3/scalus-starter - Complete DApp template

## API Reference

- https://scalus.org/api - Scaladoc API documentation

## Source Code

- https://github.com/scalus3/scalus - Main repository