name: algorand-ts-migration description: > 将智能合约从 TEALScript 或 Algorand TypeScript Beta 迁移到 Algorand TypeScript 1.0。适用于将 TEALScript 合约转换为 Algorand TypeScript、将 Algorand TypeScript Beta 代码升级到 1.0、用户提及迁移或升级到 Algorand TypeScript / puya-ts / algo-ts 1.0，或用户拥有 TealScript 代码并希望将其现代化的场景。

Algorand TypeScript 迁移

将智能合约从 TEALScript 或 Algorand TypeScript Beta 迁移到 Algorand TypeScript 1.0。

迁移工作流

1. 识别源语言

确定代码是 TEALScript 还是 Algorand TypeScript Beta：

标识	TEALScript	Algorand TypeScript Beta
导入源	`@algorandfoundation/tealscript`	`@algorandfoundation/algorand-typescript`
全局类型	使用 `assert`、`uint64` 而无需导入	需要显式导入
事件日志	`new EventLogger<...>()`	N/A
内部交易	`sendAssetConfig({...})`	`itxn.assetConfig({...})`
逻辑签名方法	`logic()`	`program()`
类型语法	`uint256`、`uint8` 字面量	`arc4.UintN<256>`、`arc4.UintN8`

2. 加载迁移指南

根据源语言，阅读相应的参考文档：

从 TEALScript 迁移：阅读 references/from-tealscript.md
从 Algorand TypeScript Beta 迁移：阅读 references/from-beta.md

3. 执行迁移

按照加载的参考文件中的检查清单进行操作。系统地应用转换：

从导入和类型重命名开始（机械性更改）
更新语法模式（内部交易、方法调用）
在需要的地方添加显式类型注解
处理语义变化（可变性、资源编码）
如果适用，重命名测试文件

4. 验证迁移

迁移后：

确保所有导入都从 @algorandfoundation/algorand-typescript 解析
验证没有剩余的 TypeScript 错误
运行 Algorand TypeScript 编译器进行验证

快速参考

常见导入模式 (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';

关键类型变更

旧	新 (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`

关键函数变更

旧	新 (1.0)
`x.copy()`	`clone(x)`
`arc4EncodedLength<T>()`	`sizeOf<T>()`
`arc4.interpretAsArc4<T>(b)`	`arc4.convertBytes<T>(b, { strategy: 'validate' })`
`x.native`	`x.asUint64()` 或 `x.asBigUint()`
`sendMethodCall<T>({...})`	`arc4.abiCall({ method: T, ... })`

资源

references/

from-beta.md：从 Algorand TypeScript Beta 迁移到 1.0 的完整指南。包含 13 个破坏性变更的检查清单及前后示例。
from-tealscript.md：从 TEALScript 迁移到 Algorand TypeScript 1.0 的完整指南。包含类型迁移表和 13 个迁移模式示例。