Algorand TypeScript Migration
Migrate smart contracts to Algorand TypeScript 1.0 from TEALScript or Algorand TypeScript Beta.
Migration Workflow
1. Identify Source Language
Determine whether the code is TEALScript or Algorand TypeScript Beta:
| Indicator |
TEALScript |
Algorand TypeScript Beta |
| Import source |
@algorandfoundation/tealscript |
@algorandfoundation/algorand-typescript |
| Global types |
Uses assert, uint64 without imports |
Requires explicit imports |
| Event logging |
new EventLogger<...>() |
N/A |
| Inner transactions |
sendAssetConfig({...}) |
itxn.assetConfig({...}) |
| Logic sig method |
logic() |
program() |
| Type syntax |
uint256, uint8 literals |
arc4.UintN<256>, arc4.UintN8 |
2. Load Migration Guide
Based on the source language, read the appropriate reference:
- From TEALScript: Read references/from-tealscript.md
- From Algorand TypeScript Beta: Read references/from-beta.md
3. Execute Migration
Follow the checklist in the loaded reference file. Apply transformations systematically:
- Start with imports and type renames (mechanical changes)
- Update syntax patterns (inner transactions, method calls)
- Add explicit type annotations where required
- Handle semantic changes (mutability, resource encoding)
- Rename test files if applicable
4. Verify Migration
After migration:
- Ensure all imports resolve from
@algorandfoundation/algorand-typescript
- Verify no TypeScript errors remain
- Run the Algorand TypeScript compiler to validate
Quick Reference
Common Import Pattern (1.0)
import {
Contract,
GlobalState,
LocalState,
Box,
BoxMap,
arc4,
uint64,
bytes,
Bytes,
Uint64,
assert,
err,
emit,
clone,
itxn,
gtxn,
Txn,
Global,
op,
} from '@algorandfoundation/algorand-typescript';
Key Type Changes
| Old |
New (1.0) |
uint8, uint16, uint256 |
arc4.Uint<8>, arc4.Uint<16>, arc4.Uint<256> |
arc4.UintN64, arc4.UintN<N> |
arc4.Uint64, arc4.Uint<N> |
arc4.UFixedNxM<N,M> |
arc4.UFixed<N,M> |
MutableArray |
ReferenceArray |
BoxRef |
Box<bytes> |
Address (TEALScript) |
Account |
AppID (TEALScript) |
Application |
AssetID (TEALScript) |
Asset |
Key Function Changes
| Old |
New (1.0) |
x.copy() |
clone(x) |
arc4EncodedLength<T>() |
sizeOf<T>() |
arc4.interpretAsArc4<T>(b) |
arc4.convertBytes<T>(b, { strategy: 'validate' }) |
x.native |
x.asUint64() or x.asBigUint() |
sendMethodCall<T>({...}) |
arc4.abiCall({ method: T, ... }) |
Resources
references/
from-beta.md: Complete migration guide from Algorand TypeScript Beta to 1.0. Includes checklist of 13 breaking changes with before/after examples.
from-tealscript.md: Complete migration guide from TEALScript to Algorand TypeScript 1.0. Includes type migration table and 13 migration patterns with examples.
1---2name: algorand-ts-migration3description: Migrate smart contracts to Algorand TypeScript 1.0 from either TEALScript or Algorand TypeScript Beta. Use when converting TEALScript contracts to Algorand TypeScript, upgrading Algorand TypeScript beta code to 1.0, user mentions migrating or upgrading to Algorand TypeScript / puya-ts / algo-ts 1.0, or user has TealScript code and wants to modernize it.4---56# Algorand TypeScript Migration78Migrate smart contracts to Algorand TypeScript 1.0 from TEALScript or Algorand TypeScript Beta.910## Migration Workflow1112### 1. Identify Source Language1314Determine whether the code is **TEALScript** or **Algorand TypeScript Beta**:1516| Indicator | TEALScript | Algorand TypeScript Beta |17|-----------|------------|--------------------------|18| Import source | `@algorandfoundation/tealscript` | `@algorandfoundation/algorand-typescript` |19| Global types | Uses `assert`, `uint64` without imports | Requires explicit imports |20| Event logging | `new EventLogger<...>()` | N/A |21| Inner transactions | `sendAssetConfig({...})` | `itxn.assetConfig({...})` |22| Logic sig method | `logic()` | `program()` |23| Type syntax | `uint256`, `uint8` literals | `arc4.UintN<256>`, `arc4.UintN8` |2425### 2. Load Migration Guide2627Based on the source language, read the appropriate reference:2829- **From TEALScript**: Read [references/from-tealscript.md](references/from-tealscript.md)30- **From Algorand TypeScript Beta**: Read [references/from-beta.md](references/from-beta.md)3132### 3. Execute Migration3334Follow the checklist in the loaded reference file. Apply transformations systematically:35361. Start with imports and type renames (mechanical changes)372. Update syntax patterns (inner transactions, method calls)383. Add explicit type annotations where required394. Handle semantic changes (mutability, resource encoding)405. Rename test files if applicable4142### 4. Verify Migration4344After migration:45- Ensure all imports resolve from `@algorandfoundation/algorand-typescript`46- Verify no TypeScript errors remain47- Run the Algorand TypeScript compiler to validate4849## Quick Reference5051### Common Import Pattern (1.0)5253```ts54import {55 Contract,56 GlobalState,57 LocalState,58 Box,59 BoxMap,60 arc4,61 uint64,62 bytes,63 Bytes,64 Uint64,65 assert,66 err,67 emit,68 clone,69 itxn,70 gtxn,71 Txn,72 Global,73 op,74} from '@algorandfoundation/algorand-typescript';75```7677### Key Type Changes7879| Old | New (1.0) |80|-----|-----------|81| `uint8`, `uint16`, `uint256` | `arc4.Uint<8>`, `arc4.Uint<16>`, `arc4.Uint<256>` |82| `arc4.UintN64`, `arc4.UintN<N>` | `arc4.Uint64`, `arc4.Uint<N>` |83| `arc4.UFixedNxM<N,M>` | `arc4.UFixed<N,M>` |84| `MutableArray` | `ReferenceArray` |85| `BoxRef` | `Box<bytes>` |86| `Address` (TEALScript) | `Account` |87| `AppID` (TEALScript) | `Application` |88| `AssetID` (TEALScript) | `Asset` |8990### Key Function Changes9192| Old | New (1.0) |93|-----|-----------|94| `x.copy()` | `clone(x)` |95| `arc4EncodedLength<T>()` | `sizeOf<T>()` |96| `arc4.interpretAsArc4<T>(b)` | `arc4.convertBytes<T>(b, { strategy: 'validate' })` |97| `x.native` | `x.asUint64()` or `x.asBigUint()` |98| `sendMethodCall<T>({...})` | `arc4.abiCall({ method: T, ... })` |99100## Resources101102### references/103104- **[from-beta.md](references/from-beta.md)**: Complete migration guide from Algorand TypeScript Beta to 1.0. Includes checklist of 13 breaking changes with before/after examples.105106- **[from-tealscript.md](references/from-tealscript.md)**: Complete migration guide from TEALScript to Algorand TypeScript 1.0. Includes type migration table and 13 migration patterns with examples.
tools-only