类型系统

静态类型约束

Vyper 没有"模糊子类型层级"。类型之间不存在隐式继承关系， 每个值都必须通过显式的 convert() 来进行类型转换。

核心原则：

• 类型越明确，调用边界越清晰。
• 编译器知道得越多，运行时越不容易出现意外行为。
• 显式转换优先于隐式魔法。

Boolean

关键字： bool

布尔值只有 True 和 False 两个取值。

and 和 or 遵循短路求值，与 Python 行为一致。

有符号整数（intN）

关键字： intN（例如 int128）

可存储正数和负数。N 是 8 到 256 之间的 8 的倍数。 取值范围为 -2^(N-1) 到 2^(N-1) - 1。

delta: int128 = -5
big: int256 = -999999999

比较运算符： <、<=、==、!=、>=、>（两端必须类型相同）

算术运算符：

位运算符： &、|、^（两端必须类型相同）

移位运算符： <<、>>（仅对 int256 可用，y 为无符号整数。int256 的右移会编译为 EVM 的 SAR 有符号右移指令）

无符号整数（uintN）

关键字： uintN（例如 uint256、uint8）

只能存储非负整数。N 是 8 到 256 之间的 8 的倍数。 取值范围为 0 到 2^N - 1。

counter: uint256 = 0
small: uint8 = 255

运算符与有符号整数相同，额外支持 ~x（按位取反，目前仅 uint256 可用）。

移位运算仅对 uint256 可用，右移编译为 EVM 的 SHR 无符号右移指令。

Decimal（十进制定点数）

关键字： decimal

从 v0.4.0 起，使用 decimal 需要通过 CLI 标志 --enable-decimals 显式启用。

精度为 10 位小数。ABI 类型为 int168。 字面量必须包含小数点才能被解释为 decimal。

price: decimal = 0.1
rate: decimal = 3.14

算术运算符： +、-、-x（取负）、*、/（注意是十进制除法，不是整数除法）、%

比较运算符与整数类型一致。

Address

关键字： address

存储一个 20 字节的以太坊地址。地址字面量必须使用 0x 前缀的十六进制格式，并通过 EIP-55 校验和验证。

owner: address = 0x1234567890123456789012345678901234567890

地址成员

访问方式：_address.balance、_address.codesize 等。

固定字节数组（bytesM）

关键字： bytesM（例如 bytes32、bytes4）

M 字节宽的固定大小字节数组。在 ABI 层表示为 bytesM。

hash: bytes32
some_method_id: bytes4 = 0x01abcdef

常用操作包括 keccak256(x)、concat(x, ...)、slice(x, start, length)。

动态字节数组（Bytes）

关键字： Bytes

语法为 Bytes[maxLen]，其中 maxLen 是最大字节数。ABI 层表示为 bytes。

bytes_string: Bytes[100] = b"\x01"
hex_bytes: Bytes[100] = x"01"

字符串（String）

关键字： String

固定最大长度的字符串类型。实际内容可以短于最大长度。ABI 层表示为 string。

example_str: String[100] = "Test String"

Flag（标志枚举）

关键字： flag

自定义枚举类型，至少 1 个成员，最多 256 个。 成员值为 uint256，形式为 2^n，其中 n 为成员在 0 到 255 范围内的索引。

flag Roles:
    ADMIN
    USER

role: Roles = Roles.ADMIN

比较运算符： ==、!=、in、not in

位运算符： &、|、^、~

成员组合可以通过位运算操作。in 和 not in 可以检查成员是否存在于某个组合中：

flag Roles:
    MANAGER
    ADMIN
    USER

@external
def foo(a: Roles) -> bool:
    return a in (Roles.MANAGER | Roles.USER)

位运算还可用于添加和撤销权限：

@external
def add_user(a: Roles) -> Roles:
    ret: Roles = a
    ret |= Roles.USER     # 设置 USER 位为 1
    return ret

@external
def revoke_user(a: Roles) -> Roles:
    ret: Roles = a
    ret &= ~Roles.USER    # 设置 USER 位为 0
    return ret

标量类型速查

以下是所有基础标量类型的快速参考：

集合类型

固定长度数组

语法为 _name: _ValueType[_Integer]（不支持 Bytes[N]、String[N] 和 flag 作为元素类型）。

exampleList: int128[3]

# 赋值
exampleList = [10, 11, 12]
exampleList[2] = 42

# 访问
return exampleList[0]

多维数组的声明顺序与访问顺序是反过来的：

# 声明：2 行 5 列
exampleList2D: int128[5][2] = empty(int128[5][2])

# 访问：[行索引][列索引]
exampleList2D[0][4] = 42

动态数组（DynArray）

运行时可变长度的有界数组，声明语法为 DynArray[_Type, _Integer]。

exampleList: DynArray[int128, 3]

exampleList = []
exampleList.append(42)     # 长度变为 1
exampleList.append(120)    # 长度变为 2
exampleList.append(356)    # 长度变为 3
# exampleList.append(1)   # 会 revert！已满

myValue: int128 = exampleList.pop()  # myValue == 356，长度变为 2

关键限制：

• 越界访问、对空数组 pop() 或对满数组 append() 都会触发 REVERT。
• 迭代数组时不能修改数组内容。
• ABI 表示为 _Type[]，例如 DynArray[int128, 3] 表示为 int128[]。

Struct（结构体）

自定义复合类型，可组合多个字段。结构体可嵌套数组和其他结构体，但不能包含映射。

struct MyStruct:
    value1: int128
    value2: decimal

exampleStruct: MyStruct = MyStruct(value1=1, value2=2.0)
exampleStruct.value1 = 1

HashMap（映射）

哈希表类型，虚拟初始化为所有可能的键都映射到类型的零值。键的数据本身不存储， 只用其 keccak256 哈希来查找值。

exampleMapping: HashMap[int128, decimal]
exampleMapping[0] = 10.1

• _KeyType 可以是任何基础类型或字节类型，不支持映射、数组或结构体作为键。
• _ValueType 可以是任何类型，包括映射（嵌套映射）。
• 映射只能作为状态变量声明。
• 映射没有"长度"概念，不能被迭代。

初始值

Vyper 没有 null 概念。每种类型都有默认的零值。 检查变量是否为空需要与对应类型的默认值比较。 使用内建的 empty() 函数可以将变量重置为默认值。

转换规则

Vyper 的所有类型转换必须通过 convert(a, btype) 显式完成。 转换被设计为安全且直观的——所有转换都会检查输入是否在输出类型的有效范围内。

x: uint256 = 100
y: int256 = convert(x, int256)

who: address = 0x1234567890123456789012345678901234567890
who_as_num: uint160 = convert(who, uint160)

转换原则

核心规则总结：