Reference

laplace-receipt crate

The Rust crate a program imports to read a final receipt.

laplace-receipt is what a Solana program imports to act on a model's answer. It has one function, read, which takes a receipt account and returns the model, the hash of the input and the output, only when the receipt is final. This page lists everything the crate has.

Dependency

Cratelaplace-receipt 0.1.0, Apache-2.0
Sourcebackend/chain/crates/laplace-receipt in the Laplace source
Depends onanchor-lang =0.31.1, the laplace program crate (feature no-entrypoint), laplace-vm

The crate is a path dependency of the Laplace source tree:

TOML
[dependencies]
anchor-lang = "=0.31.1"
laplace-receipt = { path = "<laplace>/backend/chain/crates/laplace-receipt" }

<laplace> is the folder that holds the Laplace source. The crate pins anchor-lang to 0.31.1, so the program that imports it builds on the same Anchor.

read

Rust
pub fn read(account: &AccountInfo) -> Result<Final>

Reads a receipt account and returns its answer. It runs three checks, in this order:

  1. The account is owned by the Laplace program (CdwvX8HQX3r89DpjZEfZ2VmtsxCCVdejrpwd5qD25iHq). Otherwise NotAReceipt.
  2. The account's data deserializes as a Receipt: the 8-byte Anchor discriminator matches and the fields decode. Otherwise NotAReceipt.
  3. The receipt's state is final. Otherwise NotFinal.

read takes any &AccountInfo, so an UncheckedAccount in an Anchor accounts struct is passed as &ctx.accounts.receipt. The account needs no constraint of its own: the owner and discriminator checks are what make it a receipt.

read writes nothing and costs no fee. It reads the account passed in, so the receipt's address is one of the instruction's accounts, read-only.

Final

Rust
pub struct Final {
    pub model: Pubkey,
    pub input_hash: [u8; 32],
    pub output: Vec<u16>,
}
modelPubkey
The model account the receipt answers: the address at seeds ["model", slug] under the Laplace program.
input_hash[u8; 32]
SHA-256 of the input tokens, each written as a u16 in little-endian bytes.
outputVec<u16>
The output tokens of the answer that stands: the operator's, or a challenger's that won a dispute. Exactly the model's output_len tokens.

Errors

The crate's errors are Anchor errors raised inside the calling program, so a failed transaction reports them as that program's custom errors.

CodeNameMessageWhen
6000NotAReceiptThe account is not a Laplace receiptThe account is not owned by the Laplace program, or its data is not a Receipt.
6001NotFinalThe receipt is not finalThe receipt is requested, answered, challenged or void.

The codes start at 6000, the same range as the calling program's own #[error_code] enum. The error name in the transaction logs tells them apart.

Checking what was asked

read says that a model answered an input. The calling program decides whether it is the model and the input it expects. Both are fixed before the request is made, so a program stores them when it is set up and compares them when it reads:

  • The model. Compare model with the model account's address. The address of judge is the program-derived address of ["model", "judge"] under the Laplace program; the SDK gives it as pda.model('judge').
  • The input. Compare input_hash with the hash of the exact tokens the request carries. The SDK computes both: tokenizer(slug).encode(input) gives the tokens and inputHash(tokens) from @laplace/sdk/vm gives the hash, the same SHA-256 read returns.
TypeScript
import { createLaplace, pda } from '@laplace/sdk'
import { inputHash } from '@laplace/sdk/vm'

const laplace = createLaplace({ rpcUrl: process.env.LAPLACE_RPC!, apiUrl: process.env.LAPLACE_API! })
const tokens = (await laplace.tokenizer('judge')).encode({
  claim: 'The bridge opened in 1932.',
  evidence: 'The bridge opened to traffic in March 1932.',
})
const model = pda.model('judge') // the expected `model`
const hash = await inputHash(tokens) // the expected `input_hash`

A receipt for another model or another question passes read and fails the program's own comparison.

Reading the label

Both models answer one token, the index of a label, so output holds one element:

output[0]judgemarket
0yesnegative
1unclearneutral
2nopositive
Rust
let answer = laplace_receipt::read(&ctx.accounts.receipt)?;
match answer.output[0] {
    0 => { /* judge: yes, market: negative */ }
    2 => { /* judge: no, market: positive */ }
    _ => { /* judge: unclear, market: neutral */ }
}

The same token means a different label under each model, so a program compares model first, as above, and then reads the label of the model it expects.

In an instruction

A complete instruction that pays a stake out on the judge's final answer:

Rust
pub fn settle(ctx: Context<Settle>) -> Result<()> {
    let answer = laplace_receipt::read(&ctx.accounts.receipt)?;
    let m = &ctx.accounts.market;
    require_keys_eq!(answer.model, m.model, MarketError::WrongModel);
    require!(answer.input_hash == m.input_hash, MarketError::WrongQuestion);

    let to = match answer.output[0] {
        YES => ctx.accounts.yes.to_account_info(),
        NO => ctx.accounts.no.to_account_info(),
        _ => ctx.accounts.funder.to_account_info(), // unclear: the stake goes back
    };
    let from = ctx.accounts.market.to_account_info();
    let stake = m.stake;
    **from.try_borrow_mut_lamports()? -= stake;
    **to.try_borrow_mut_lamports()? += stake;
    ctx.accounts.market.stake = 0;
    Ok(())
}

#[derive(Accounts)]
pub struct Settle<'info> {
    #[account(mut, has_one = yes, has_one = no, has_one = funder)]
    pub market: Account<'info, Market>,
    /// CHECK: checked by laplace_receipt::read: owned by the Laplace program and final
    pub receipt: UncheckedAccount<'info>,
    /// CHECK: the market's yes recipient
    #[account(mut)]
    pub yes: UncheckedAccount<'info>,
    /// CHECK: the market's no recipient
    #[account(mut)]
    pub no: UncheckedAccount<'info>,
    /// CHECK: the market's funder
    #[account(mut)]
    pub funder: UncheckedAccount<'info>,
}

Quickstart: read a receipt from a program has the whole program, with the instruction that opens the market and the client that sends both.