slot-vrng

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Slot vRNG

Cartridge's Verifiable Random Number Generator provides cheap, atomic, verifiable randomness for onchain games. Randomness is generated and verified within a single transaction.

Cartridge的可验证随机数生成器（vRNG）为链上游戏提供低成本、原子化、可验证的随机数。随机数的生成与验证在单笔交易内完成。

Contract Addresses

合约地址

Network	Address
Mainnet	`0x051fea4450da9d6aee758bdeba88b2f665bcbf549d2c61421aa724e9ac0ced8f`
Sepolia	`0x051fea4450da9d6aee758bdeba88b2f665bcbf549d2c61421aa724e9ac0ced8f`

网络	地址
主网	`0x051fea4450da9d6aee758bdeba88b2f665bcbf549d2c61421aa724e9ac0ced8f`
Sepolia测试网	`0x051fea4450da9d6aee758bdeba88b2f665bcbf549d2c61421aa724e9ac0ced8f`

Cairo Interface

Cairo 接口

rust

#[starknet::interface]
trait IVrfProvider<TContractState> {
    fn request_random(self: @TContractState, caller: ContractAddress, source: Source);
    fn consume_random(ref self: TContractState, source: Source) -> felt252;
}

#[derive(Drop, Copy, Clone, Serde)]
pub enum Source {
    Nonce: ContractAddress,
    Salt: felt252,
}

rust

#[starknet::interface]
trait IVrfProvider<TContractState> {
    fn request_random(self: @TContractState, caller: ContractAddress, source: Source);
    fn consume_random(ref self: TContractState, source: Source) -> felt252;
}

#[derive(Drop, Copy, Clone, Serde)]
pub enum Source {
    Nonce: ContractAddress,
    Salt: felt252,
}

Source Types

源类型

```
Source::Nonce(ContractAddress)
```
: Uses the address's internal nonce. Each request generates a different seed.
```
Source::Salt(felt252)
```
: Uses a provided salt. Same salt = same random value.

```
Source::Nonce(ContractAddress)
```
: 使用地址的内部随机数（nonce）。每次请求都会生成不同的种子。
```
Source::Salt(felt252)
```
: 使用提供的盐值（salt）。相同的盐值会生成相同的随机数。

Usage in Contracts

在合约中的使用

rust

const VRF_PROVIDER_ADDRESS: starknet::ContractAddress =
    starknet::contract_address_const::<0x051fea4450da9d6aee758bdeba88b2f665bcbf549d2c61421aa724e9ac0ced8f>();

fn roll_dice(ref self: ContractState) {
    let vrf_provider = IVrfProviderDispatcher { contract_address: VRF_PROVIDER_ADDRESS };
    let player_id = get_caller_address();
    let random_value = vrf_provider.consume_random(Source::Nonce(player_id));
    // Use random_value in game logic
}

rust

const VRF_PROVIDER_ADDRESS: starknet::ContractAddress =
    starknet::contract_address_const::<0x051fea4450da9d6aee758bdeba88b2f665bcbf549d2c61421aa724e9ac0ced8f>();

fn roll_dice(ref self: ContractState) {
    let vrf_provider = IVrfProviderDispatcher { contract_address: VRF_PROVIDER_ADDRESS };
    let player_id = get_caller_address();
    let random_value = vrf_provider.consume_random(Source::Nonce(player_id));
    // Use random_value in game logic
}

Executing vRNG Transactions

执行vRNG交易

request_random

must be the first call in the multicall. The Cartridge Paymaster wraps the multicall with

submit_random

and

assert_consumed

const call = await account.execute([
  // First: request_random
  {
    contractAddress: VRF_PROVIDER_ADDRESS,
    entrypoint: 'request_random',
    calldata: CallData.compile({
      caller: GAME_CONTRACT,
      // Source::Nonce(address)
      source: { type: 0, address: account.address },
      // Or Source::Salt(felt252)
      // source: { type: 1, salt: 0x123 },
    }),
  },
  // Then: your game call
  {
    contractAddress: GAME_CONTRACT,
    entrypoint: 'roll_dice',
    // ...
  },
]);

The

source

request_random

must match the

source

consume_random

request_random

必须是多调用中的第一个调用。 Cartridge付费主合约会将多调用用

submit_random

和

assert_consumed

进行包装。

const call = await account.execute([
  // First: request_random
  {
    contractAddress: VRF_PROVIDER_ADDRESS,
    entrypoint: 'request_random',
    calldata: CallData.compile({
      caller: GAME_CONTRACT,
      // Source::Nonce(address)
      source: { type: 0, address: account.address },
      // Or Source::Salt(felt252)
      // source: { type: 1, salt: 0x123 },
    }),
  },
  // Then: your game call
  {
    contractAddress: GAME_CONTRACT,
    entrypoint: 'roll_dice',
    // ...
  },
]);

request_random

中的

source

必须与

consume_random

中的

source

一致。

Controller Policy

控制器策略

Add the vRNG contract to your Controller policies:

typescript

const policies: Policy[] = [
  // ... your existing policies ...
  {
    target: VRF_PROVIDER_ADDRESS,
    method: "request_random",
    description: "Allows requesting random numbers from the VRF provider",
  },
];

将vRNG合约添加到你的控制器策略中：

typescript

const policies: Policy[] = [
  // ... your existing policies ...
  {
    target: VRF_PROVIDER_ADDRESS,
    method: "request_random",
    description: "Allows requesting random numbers from the VRF provider",
  },
];

Security

安全性

Phase 0 assumes the Provider has not revealed the private key and does not collude with players. Future plans include moving the Provider to a Trusted Execution Environment (TEE).

第0阶段假设服务提供商未泄露私钥，且未与玩家合谋。未来计划将服务提供商迁移至可信执行环境（TEE）。