Cairo

Cairo 2.x

Starknet

为 STARK 证明系统设计的语言，原生支持可证明计算

Cairo 从零为 zk 证明设计：程序执行轨迹会生成 STARK 证明，在以太坊上验证。Cairo 2 引入了类似 Rust 的所有权与 trait 体系，编译目标是 Sierra 中间表示。理解重点在于「存储变量（storage var）」「合约入口（entry point）」「felt252 这个原生字段类型」。

2 个语法章节2 段可复制代码含在线练习

从 Solidity 视角看差异

如果已经会 Solidity，这张表比从头读语法快得多。

差异点	说明
入口注解	用 #[external(v0)] 暴露外部入口，#[abi(embed_v0)] 嵌入接口实现。
存储访问	状态在 self.xxx 下，通过 ContractState trait 读写；Map 是 Starknet 原生存储映射，不可遍历。
数据类型	felt252 是原生字段元素（约 251 位），u256 由两个 felt252 组成，成本显著更高。
错误处理	用 Result 与 panic! / assert! 混合风格；断言失败会回滚整笔交易。

合约结构与存储

1 段代码

Starknet 合约由 #[starknet::contract] 标注，#[storage] 声明状态布局。

#[starknet::interface] 定义 ABI，配合 #[abi(embed_v0)] 自动生成桩代码
构造器 #[constructor] 返回 self，用来初始化存储
Map<key, value> 是可寻址存储，不能遍历，需要自己维护索引
LegacyMap 是旧写法，新合约统一用 Map

Starknet 存储合约

Starknet 存储合约Cairo

#[starknet::interface]
pub trait ICounter<TContractState> {
    fn get(self: @TContractState) -> u128;
    fn increment(ref self: TContractState);
    fn set(ref self: TContractState, value: u128);
}

#[starknet::contract]
pub mod Counter {
    use starknet::ContractAddress;

    #[storage]
    struct Storage {
        owner: ContractAddress,
        value: u128,
        per_user: Map<ContractAddress, u128>,
    }

    #[event]
    #[derive(Drop, starknet::Event)]
    enum Event {
        Incremented: Incremented,
    }

    #[derive(Drop, starknet::Event)]
    struct Incremented {
        caller: ContractAddress,
        new_value: u128,
    }

    #[constructor]
    fn constructor(ref self: ContractState, initial: u128) {
        self.owner.write(starknet::get_caller_address());
        self.value.write(initial);
    }

    #[external(v0)]
    impl CounterImpl of ICounter<ContractState> {
        fn get(self: @ContractState) -> u128 {
            self.value.read()
        }

        fn increment(ref self: ContractState) {
            let caller = starknet::get_caller_address();
            let next = self.value.read() + 1;

            self.value.write(next);
            self.per_user.write(caller, next);

            self.emit(Event::Incremented(Incremented { caller, new_value: next }));
        }

        fn set(ref self: ContractState, value: u128) {
            assert!(starknet::get_caller_address() == self.owner.read(), "not owner");
            self.value.write(value);
        }
    }
}

@ContractState 只读用 self: @T，要修改用 ref self: T，编译器会强制区分。

错误处理与断言

1 段代码

Cairo 用 panic! 与 assert!，也支持自定义错误 enum 以便前端解析。

assert!(cond, "message") 失败时回滚交易并写入简短字符串
panic_with_felt252 用于返回错误码，便于程序化处理
Result<T, E> 用于库内部逻辑，外层用手动 unwrap 或显式 match 处理
Starknet 交易回滚同样不消耗已执行部分的 Gas，但会收一笔执行费

断言与自定义错误

断言与自定义错误Cairo

#[derive(Drop, Serde)]
pub enum VaultError {
    NotOwner,
    Insufficient: u128,
    ZeroAmount,
}

#[starknet::contract]
pub mod Vault {
    use starknet::ContractAddress;
    use super::VaultError;

    #[storage]
    struct Storage {
        owner: ContractAddress,
        balance: u128,
    }

    #[generate_trait]
    impl Internal of InternalTrait {
        fn require_owner(self: @ContractState, caller: ContractAddress) {
            if caller != self.owner.read() {
                core::panic_with_felt252('NOT_OWNER');
            }
        }
    }

    #[external(v0)]
    fn withdraw(ref self: ContractState, amount: u128) {
        let caller = starknet::get_caller_address();
        self.require_owner(caller);

        assert!(amount > 0, "zero amount");

        let balance = self.balance.read();
        assert!(balance >= amount, "insufficient");

        self.balance.write(balance - amount);
    }
}

本章练习

这一段要让你看懂：Starknet 的存储与算术基本单位是 felt252（约 251 位的字段元素），不是 EVM 的 256 位整数。u256 由两个 felt252 拼成，成本显著更高；地址也只有 251 位有效范围。

▶

试一试 · felt252、u256 与地址边界

可直接改代码 · 在浏览器沙箱里真跑

playground.jsJavaScript

// STARK 字段的素数：所有 felt252 运算都在模 P 下进行
const P = 2n ** 251n + 17n * 2n ** 192n + 1n;

console.log('P =', P.toString());
console.log('P 的二进制位数 =', P.toString(2).length, '（所以叫 felt252）');
console.log('EVM 的 uint256 上限 =', (2n ** 256n - 1n).toString());
console.log('P 比 2^256 小？', P < 2n ** 256n, '→ felt252 装不下 uint256 的全范围\n');

// 溢出行为不同：EVM 会回绕到 0，felt252 会模 P
const halfP = P / 2n;
console.log('felt252 溢出演示：');
console.log('  P - 1 =', (P - 1n).toString());
console.log('  (P - 1) + 2 =', ((P - 1n + 2n) % P).toString());
console.log('  → 回绕到 1，而不是 EVM 式的 0 附近跳变。任何依赖回绕的写法都不能照搬。\n');

// u256 在 Cairo 里是两个 felt252：low + high * 2^128
function toCairoU256(v) {
  const MASK = 2n ** 128n - 1n;
  return { low: v & MASK, high: v >> 128n };
}

for (const v of [7n, 2n ** 128n - 1n, 2n ** 128n, 2n ** 200n + 7n]) {
  const { low, high } = toCairoU256(v);
  console.log(
    'u256 ' + v.toString().padStart(24),
    '→ low =', low.toString().padStart(20),
    ' high =', high.toString()
  );
}

console.log('\n每一半都是独立的存储槽/字段，因此 u256 的加减乘比 u128 贵得多。');
console.log('合约里能用 u128 就别用 u256——这是 Cairo 与 Solidity 优化直觉最大的不同。');

运行环境：iframe 沙箱（无 cookie 权限）。只支持纯 JS 片段，不支持 import / require；需要模块请用下方的完整示例复制到项目里。

检查点（跑完后逐条核对）

felt252 的位数是 252（P 的二进制长度为 252 位）
P 小于 2^256，说明 felt252 装不下 uint256 全范围
felt252 的溢出是模 P 回绕，不是 EVM 式的截断
2^128 拆出的 low 是 0、high 是 1

切换其他语言

Solidity Vyper Rust（Solana / Anchor）Move 标准查询（EIPs）