Building Smart Contracts

Create modern Algorand smart contracts in Algorand TypeScript or Algorand Python—statically-typed subsets compiled to TEAL bytecode by the Puya compiler.

Overview / Core Workflow

1. Search Algorand documentation for concepts and best practices
2. Retrieve canonical examples from priority repositories
3. Generate code adapting examples to requirements
4. Include integration tests using generated clients
5. Build and test with AlgoKit commands

How to proceed

1. Search documentation first:

   • Use

     kappa_search_algorand_knowledge_sources

     MCP tool for conceptual guidance
   • If MCP unavailable, use web search: "site:dev.algorand.co {concept}"
   • If no results, proceed with caution using known patterns

2. Retrieve canonical examples:

   • Priority 1:

     algorandfoundation/devportal-code-examples

   • Priority 2:

     algorandfoundation/puya-ts

     (examples/)
   • Priority 3:

     algorandfoundation/algokit-typescript-template

   • Always include corresponding test files

3. Generate code:

   • Default to TypeScript unless user explicitly requests Python
   • Adapt examples carefully, preserving safety checks
   • Follow syntax rules from

     algorand-typescript

     skill

4. Include tests:

   • Always include or suggest integration tests
   • Use generated clients for testing contracts
   • See

     test-smart-contracts

     skill for patterns

5. Build and test:

   algokit project run build   # Compile contracts
   algokit project run test    # Run tests
   

Important Rules / Guidelines

• NEVER use PyTEAL or Beaker — these are legacy, superseded by Puya
• NEVER write raw TEAL — always use Algorand TypeScript/Python
• NEVER import external libraries into contract code
• Default to TypeScript unless user explicitly requests Python
• Always search docs first before writing code
• Always retrieve examples from priority repositories

Common Variations / Edge Cases

devportal-code-examples/contracts/BoxStorage/

puya-ts/examples/hello_world_arc4/

algorandfoundation/puya

references/python/

References / Further Reading

• Detailed Workflow
• Syntax Rules
• Testing Patterns
• AlgoKit Commands