algorand-typescript

Algorand TypeScript

Write, test, deploy, and troubleshoot Algorand TypeScript smart contracts.

Quick Start

algokit init -n my-project -t typescript --answer preset_name production --defaults
cd my-project
algokit project run build    # Compile .algo.ts → ARC-56 + typed client
algokit project run test     # Run Vitest tests
algokit localnet start       # Start local network
algokit project deploy localnet  # Deploy

Critical Rules

• File extension: Contract files MUST use .algo.ts
• NEVER use number: Use uint64 and Uint64() for all numeric values in contracts
• Always clone() storage reads/writes: clone(this.box(k).value) — see syntax-types.md decision table
• fee: Uint64(0) on all inner transactions: Prevents app account drain; caller covers via fee pooling
• Fund app account before box operations: Box storage requires MBR funding
• NEVER use PyTEAL, Beaker, or raw TEAL: Only use Algorand TypeScript (PuyaTs)
• Always search docs first: Use Kapa MCP or web search before writing contract code
• Always include tests: Use algorandFixture for E2E integration tests
• Understand AVM constraints: See algorand-core skill for the foundational mental model

Reference Guide

Read the specific reference file for your task. Each file is self-contained.

Contract Syntax

• syntax-types.md — AVM types (uint64, bytes, bigint), number rules, clone(), value semantics, union type workarounds, array rules
• syntax-storage.md — GlobalState, LocalState, BoxMap, Box, MBR funding patterns, @contract decorator for dynamic keys, choosing storage types
• syntax-methods.md — Method visibility (public/private), @abimethod/@readonly decorators, transaction-type parameters, lifecycle methods, emit() events, assertMatch with comparison operators
• syntax-transactions.md — gtxn typed access, ABI method transaction parameters, itxn inner transactions, itxnCompose/itxn.submitGroup, fee pooling, asset creation