Solana 程序

​

四个已部署的程序

​

程序 ID 与派生账户

​

哪个身份对应哪个字段

​

订单结构

pub struct StandardOrder {
    pub user: Pubkey,
    pub nonce: u128,
    pub origin_chain_id: u128,
    pub expires: u32,
    pub fill_deadline: u32,
    pub input_oracle: Pubkey,
    pub input: MandateInput,
    pub outputs: Vec<MandateOutput>,
}

pub struct MandateInput {
    pub token: Pubkey,  // SPL mint
    pub amount: u64,
}

pub struct MandateOutput {
    pub oracle: [u8; 32],      // output-side oracle identifier
    pub settler: [u8; 32],     // output settler identifier
    pub chain_id: [u8; 32],    // u128, big-endian, padded to 32 bytes
    pub token: [u8; 32],
    pub amount: [u8; 32],
    pub recipient: [u8; 32],
    pub callback_data: Vec<u8>,
    pub context: Vec<u8>,      // order type and auction parameters
}

​

输入结算：input_settler_escrow

​

程序状态

/// PDA("input_settler_escrow") — singleton, created by initialize().
pub struct InputSettlerEscrowAccount {
    pub chain_id: u128,
    pub bump: u8,
}

/// PDA("order_context", order_id) — owns the escrow token account.
/// Created at open, closed at finalise / finalise_with_prefill / refund /
/// refund_on_non_fill. Rent goes to the sponsor (see "Rent returns" below).
pub struct OrderContext {
    pub input_token: Pubkey,
    pub user: Pubkey,
    pub sponsor: Pubkey,
    pub bump: u8,
}

/// PDA("consumed_order", order_id) — empty replay marker, never closed.
pub struct ConsumedOrder {}

​

开启

760 + 302·N_outputs + Σ(|callback_data| + |context|) − (32 if sponsor == user)

​

租金退还

​

结算

[attestation_0, …, attestation_(N−1), rent_refund_0, …, rent_refund_(N−1)]

• 同链输出对应的认证是一个 LocalAttestation；跨链输出对应的是一个由该订单的 input_oracle 创建的 Attestation。
• 只有当本地认证的消费方是托管程序（output.oracle = input_settler_escrow 程序 ID）时，租金退还槽位才有意义。此时两个账户都必须可写，且退还账户必须是该认证中存储的 rent_refund；finalise 会消费该认证并退还其租金。
• 对于其他所有认证——远程认证，以及使用规范编码的同链认证——该槽位必须提供但会被忽略。任何已存在的账户都可以，例如 system program，且两项都可以是只读的。

pub struct FinalisedEvent {
    pub settler: Pubkey,          // the order_context PDA
    pub order_id: [u8; 32],
    pub solver: [u8; 32],
    pub destination: [u8; 32],
}

​

先释放输入的结算（finalise_with_prefill）

​

退款

• refund(order) —— 一旦到达 order.expires（now >= expires），任何人都可以调用。
• refund_on_non_fill(order, output_index) —— 一旦某个输出被证明未被填充，任何人都可以调用，而这最早可以发生在 fill_deadline 刚过之后。证明一个输出未被填充就会为整个订单退款，因为 finalise 要求所有输出都被证明已填充。它需要托管程序的 local_consumer PDA 和 intents_protocol 程序，以及恰好两个 remaining_accounts：[attestation, rent_refund]，其消费或忽略规则与 finalise 相同。关于未填充证明是如何产生的，见未填充认证。

​

输出结算：output_settler_simple

​

订单类型

​

填充

• fill(order_id, mandate_output, fill_deadline, filler_data) —— 用于经典 SPL 和兼容的 Token-2022 输出。它会将代币转给接收方，创建 FillRecord 和 LocalAttestation 账户，并发出一个 OutputFilledEvent。order_id 是输入链的标识符；填充时不会对其进行验证。
• native_fill(...) —— 用于原生 SOL 输出。输出代币必须是零地址 [0; 32]；转账通过 system program 进行。
• fill_samechain(args) 和 native_fill_samechain(args) —— 同样的两种交付方式，但由 CompactSamechainOrder 而非 MandateOutput 驱动。两者都必须作为顶层指令调用（NotTopLevel），都会将签名者记录为求解器而不是读取 filler_data 字段，并且都只创建 FillRecord——不创建 LocalAttestation。只能在同一笔交易中一个匹配的 finalise_with_prefill 之后使用它们。

pub struct FillSamechainArgs {
    pub order_id: [u8; 32],
    pub order: CompactSamechainOrder,
}

pub struct CompactSamechainOrder {
    pub nonce: u128,
    pub expires: u32,
    pub fill_deadline: u32,
    pub input_amount: u64,
    pub output_amount: u64,
    pub context: CompactSamechainContext,  // None | ExclusiveFor | ExclusiveForSelf
}

​

填充记录

/// PDA([order_id, mandate_output_hash]) under output_settler_simple.
pub struct FillRecord {
    pub rent_refund: Pubkey,  // the filler that paid the rent
    pub close_after: u64,     // fill_deadline + 172,800 seconds (48 hours)
}

oracle[32] || settler[32] || chain_id[32] || token[32] || amount[32]
|| recipient[32] || callback_length[u16 BE] || callback_data
|| context_length[u16 BE] || context

​

未填充认证的创建

fill_deadline < now <= fill_deadline + 172,800

​

认证

• LocalAttestation 在某个输出于 Solana 上通过 fill 或 native_fill 被填充时，在 Solana 上创建（紧凑填充不会创建它）。它证明了这次填充发生在它所在的那条链上。
• Attestation 在某个预言机验证了一个远程证明或消息之后，在 Solana 上创建。它代表的是发生在另一条链上的一次填充。

​

被认证的内容

• FillDescription 表示某个输出已被填充。它的魔数是 keccak("OIF.Fill") 的前 4 个字节（0xd1252dff），其布局为 MAGIC || solver (32B) || order_id (32B) || timestamp (u32 BE) || common_payload。
• NotFilledDescription 表示某个输出在其截止时间之前未被填充。它的魔数是 keccak("OIF.NotFilled") 的前 4 个字节（0x830c1e1c），其布局为 MAGIC || order_id (32B) || fill_deadline (u32 BE) || common_payload。

• data_hash，被 LocalAttestation 使用，是不包含时间戳的描述的 keccak 值。时间戳单独存储在账户中并单独验证。
• payload_hash，被 Attestation 使用，是完整描述（包含时间戳）的 keccak 值。

​

LocalAttestation：Solana 上的填充

/// 46 bytes including the 8-byte discriminator.
pub struct LocalAttestation {
    timestamp: u32,          // private; read it only after validating the PDA
    pub bump: u8,
    pub rent_refund: Pubkey, // whoever paid for the account — the filler, or the attest_not_filled caller
    pub consumed: bool,      // false at creation
}

​

消费本地认证

​

Attestation：从预言机接收到的证明

• source —— 输出链上预言机或发出方的 32 字节标识符。
• application —— 输出结算器的 32 字节标识符，通常就是 MandateOutput.settler。

​

端到端的证明流程

​

未填充认证（提前退款）

• 在输出链上，output_settler_simple::attest_not_filled 会创建一个 LocalAttestation，其 data_hash 是完整 NotFilledDescription 的 keccak 值，其存储的时间戳是该输出的 fill_deadline。
• 预言机中继它的方式与中继一份填充负载完全相同——NOT_FILLED_MAGIC 前缀会在两端选中”未填充”的哈希规则。
• 在输入链上，refund_on_non_fill 会验证由此产生的 LocalAttestation（同链）或 Attestation（跨链），并在不等待 expires 的情况下为该托管退款——见退款。
• 未填充的 LocalAttestation 只能在 fill_deadline 之后 48 小时内创建——见未填充认证的创建。

​

链配置

• ChainId —— 一个单例 PDA（种子 "chain_id"），保存该部署的规范链 id。set_chain_id(chain_id) 只能被调用一次，任何签名者都可以调用——各部署会将其作为最初的第一步执行，在任何其他人抢先之前完成。各结算器程序会在自己的 initialize 时复制这个值。
• ChainMapping —— 一个 PDA（种子为 ["chain_mapping", oracle, protocol_chain_id_le]），将某个消息传递协议自己的链 id 映射到规范链 id。每个协议都有自己的方案：Polymer 对 EVM 链使用 EVM 链 id，但对 Solana 使用自己的协议 id（2）；Wormhole 则使用它自己的 u16 id。每个预言机的所有者会通过该预言机的 set_chain_mapping(protocol_chain_id, chain_id) 指令创建映射——仅限所有者调用，且每个映射只能设置一次。跨链认证需要这些映射：如果某个证明来自一条没有映射的链，它就无法被注册。

​

事件

• LocalAttestationCreatedEvent
• LocalAttestationConsumedEvent { attestator, consumer, data_hash, rent_refund }
• LocalAttestationRentDeferredEvent { local_attestation, rent_refund } —— 已消费，但由于 rent_refund 是可执行账户，租金被暂时保留
• LocalAttestationRentReclaimedEvent { local_attestation, rent_refund }
• AttestationCreatedEvent
• ChainIdConfiguredEvent
• ChainMapConfiguredEvent

• input_settler_escrow —— OpenEvent、FinalisedEvent（两条完结路径都是）、RefundedEvent
• output_settler_simple —— OutputFilledEvent、OutputNotFilledEvent、FillRecordClosedEvent { order_id, output_hash, rent_refund }
• polymer 和 wormhole —— OutputProvenEvent

​

常见陷阱

• 32 字节标识符填错。 每个体系都有自己的 32 字节表示方式：Solana 的 Pubkey::to_bytes()、左侧补零到 32 字节的 EVM 地址、Wormhole 的 emitter 地址。把它们弄混，会得到一个验证方永远找不到的 PDA。
• 每个身份字段在不同阶段失败。 在填充之前，请对照身份矩阵核对全部三者：
  • 如果 MandateOutput.settler 填错了，填充会被拒绝。该订单会一直无法填充，直到过期退款。
  • 如果 StandardOrder.input_oracle 填错了，完结逻辑会用错误的认证方派生出预期的 Attestation 地址，因此永远找不到预言机实际创建的那个认证。
  • 如果 MandateOutput.oracle 填错了，填充仍会成功，因为这个字段在填充时不会被检查。求解器的资产会立即离开；但之后的证明提交会因认证被拒绝而失败，求解器也就得不到偿付。
• 时间戳不一致。 同链验证要求 LocalAttestation.timestamp == SolveParams.timestamp。如果求解器传入的时间戳与输出结算器存储的不一致，完结就会失败。
• 缺少租金退还槽位。 finalise 和 refund_on_non_fill 要求为每个认证提供一个租金退还槽位，即使该槽位会被忽略。只传入认证会以 WrongAttestationCount 失败。

​

同链意图

• 标准路径： fill 创建一个 LocalAttestation，之后的 finalise 直接验证它——不涉及任何预言机程序。该认证不会被消费，因此其租金不会被退还。
• 先释放输入： 先释放输入的结算会在交付输出的同一笔交易中向求解器付款，因此求解器可以直接用用户的输入来置办这笔输出，而不必动用自己的余额。紧凑填充不会创建任何认证。该订单还必须满足：callback_data 为空，且 context 为空或为独占限价。EVM 通过 finalise 的回调达到同样的效果；Solana 没有回调机制，而是需要一条特定的后置填充指令。

​

预言机

​

扩展该系统

​

程序 IDL

​

后续步骤