Sui 结构

本节是可选的，并启用高级用例。

您可以纯粹通过客户端 CLI 以及提供的 JSON 或 HTTP API 与 Walrus 交互，而无需直接在 Sui 上查询或执行交易。然而，Walrus 使用 Sui 来管理其元数据，智能合约开发人员可以在 Sui 上读取有关 Walrus 系统以及存储的 blob 的信息。

Walrus 测试网合约的 Move 代码可在 https://github.com/MystenLabs/walrus-docs/blob/main/contracts 获取。使用 Walrus 合约的示例包可在 https://github.com/MystenLabs/walrus-docs/blob/main/examples/move 获取。

以下部分提供了对合约的进一步见解，并概述了如何在您自己的 Sui 智能合约中使用 Walrus 对象。

Blob 和存储对象

Walrus blob 表示为类型为 Blob 的 Sui 对象。首先注册一个 blob，表示存储节点应期望存储来自 Blob ID 的片段。然后认证一个 blob，表示已存储足够数量的片段以保证 blob 的可用性。当一个 blob 被认证时，其 certified_epoch 字段包含其被认证的 epoch。

Blob 对象始终与 Storage 对象相关联，为 blob 的存储保留足够长时间的足够空间。认证的 blob 在底层存储资源保证存储的期间内可用。

具体来说，Blob 和 Storage 对象具有以下字段，可以通过 Sui SDK 读取：

/// The blob structure represents a blob that has been registered to with some storage,
/// and then may eventually be certified as being available in the system.
public struct Blob has key, store {
    id: UID,
    registered_epoch: u32,
    blob_id: u256,
    size: u64,
    encoding_type: u8,
    // Stores the epoch first certified.
    certified_epoch: option::Option<u32>,
    storage: Storage,
    // Marks if this blob can be deleted.
    deletable: bool,
}

/// Reservation for storage for a given period, which is inclusive start, exclusive end.
public struct Storage has key, store {
    id: UID,
    start_epoch: u32,
    end_epoch: u32,
    storage_size: u64,
}

Blob 和 Storage 对象的所有字段都可以使用预期的函数读取：

// Blob functions
public fun blob_id(b: &Blob): u256;
public fun size(b: &Blob): u64;
public fun erasure_code_type(b: &Blob): u8;
public fun registered_epoch(self: &Blob): u32;
public fun certified_epoch(b: &Blob): &Option<u32>;
public fun storage(b: &Blob): &Storage;
...

// Storage functions
public fun start_epoch(self: &Storage): u32;
public fun end_epoch(self: &Storage): u32;
public fun storage_size(self: &Storage): u64;
...

事件

当一个 blob 首次注册时，会发出一个 BlobRegistered 事件，通知存储节点它们应该期望与其 Blob ID 相关的片段。最终，当 blob 被认证时，会发出一个 BlobCertified 事件，其中包含有关 blob ID 和 blob 将被删除的 epoch 的信息。在该 epoch 之前，blob 保证可用。

/// Signals that a blob with metadata has been registered.
public struct BlobRegistered has copy, drop {
    epoch: u32,
    blob_id: u256,
    size: u64,
    encoding_type: u8,
    end_epoch: u32,
    deletable: bool,
    // The object id of the related `Blob` object
    object_id: ID,
}

/// Signals that a blob is certified.
public struct BlobCertified has copy, drop {
    epoch: u32,
    blob_id: u256,
    end_epoch: u32,
    deletable: bool,
    // The object id of the related `Blob` object
    object_id: ID,
    // Marks if this is an extension for explorers, etc.
    is_extension: bool,
}

BlobCertified 事件中 deletable 设置为 false 且 end_epoch 在未来，表示该 blob 将在此 epoch 之前可用。轻客户端证明此事件为 blob ID 发出，构成该 blob ID 数据的可用性证明。

当一个可删除的 blob 被删除时，会发出一个 BlobDeleted 事件：

/// Signals that a blob has been deleted.
public struct BlobDeleted has copy, drop {
    epoch: u32,
    blob_id: u256,
    end_epoch: u32,
    // The object ID of the related `Blob` object.
    object_id: ID,
    // If the blob object was previously certified.
    was_certified: bool,
}

当存储节点检测到编码错误的 blob 时，会发出 InvalidBlobID 事件。任何尝试读取此类 blob 的人都保证会将其检测为无效。

/// Signals that a BlobID is invalid.
public struct InvalidBlobID has copy, drop {
    epoch: u32, // The epoch in which the blob ID is first registered as invalid
    blob_id: u256,
}

系统级事件如 EpochChangeStart 和 EpochChangeDone 表示 epoch 之间的过渡。相关事件如 ShardsReceived、EpochParametersSelected 和 ShardRecoveryStart 表示与 epoch 过渡、分片迁移和 epoch 参数相关的存储节点级事件。

系统和质押信息

Walrus 系统对象包含有关可用和已用存储的元数据，以及每 KiB 存储的 FROST 存储价格。系统对象内的委员会结构可用于读取当前的 epoch 编号以及有关委员会的信息。

public struct SystemStateInnerV1 has key, store {
    id: UID,
    /// The current committee, with the current epoch.
    committee: BlsCommittee,
    // Some accounting
    total_capacity_size: u64,
    used_capacity_size: u64,
    /// The price per unit size of storage.
    storage_price_per_unit_size: u64,
    /// The write price per unit size.
    write_price_per_unit_size: u64,
    /// Accounting ring buffer for future epochs.
    future_accounting: FutureAccountingRingBuffer,
    /// Event blob certification state
    event_blob_certification_state: EventBlobCertificationState,
}

/// This represents a BLS signing committee for a given epoch.
public struct BlsCommittee has store, copy, drop {
    /// A vector of committee members
    members: vector<BlsCommitteeMember>,
    /// The total number of shards held by the committee
    n_shards: u16,
    /// The epoch in which the committee is active.
    epoch: u32,
}

public struct BlsCommitteeMember has store, copy, drop {
    public_key: Element<G1>,
    weight: u16,
    node_id: ID,
}