一项私密信贷决策

贷款方公布其评分模型。申请人在自己的数据上运行该模型，再交给贷款方一份写着“通过”或“拒绝”的回执。贷款方看不到数据，申请人既无法改动模型，也无法向模型输入伪造的数据。

这是证明计算的最小实用案例，采用公开程序、公开参数和私有输入。模型是一个整数算术的两层神经网络。同样的结构适用于监管方或交易对手希望能够查验的任何规则：定价公式、资格测试、风险限额。

示例程序介绍了四个示例页面共有的准备工作。

1. 它证明什么

涉及三方：

• 贷款方部署程序，并把模型作为程序的公开段。程序 id 指明了这个模型。任何人都可以从链上读回权重。
• 认证方（征信机构、银行、雇主）掌握申请人的数据。它向申请人提供特征值、一个随机的 16 字节盐值，以及它对承诺 SHA-256(salt ‖ features) 的签名。
• 申请人以盐值和特征值作为私有输入调用程序。

该调用证明：

1. 每个特征都在模型为其声明的范围之内；
2. 模型在这些特征上的评分不低于阈值（状态 1），或低于阈值（状态 2）；
3. 公布的承诺是盐值与这些相同特征的 SHA-256。

贷款方检查回执的程序 id、状态，以及该承诺是否为认证方签过名的承诺。它只得知关于申请人的一比特信息。

**私有输入本身不能证明任何关于现实世界的事。**没有第 3 点，申请人可以随意填入任何数字。承诺把证明中的数字与有人担保过的数字联系起来。签名本身由贷款方在链下检查：Dilithium 或 ECDSA 验证放不进一次调用的预算，而且由于承诺是公开的，它也不需要放进证明里。

2. 接口

每个公开字都是 i32，以其二进制补码 u32 存储。

只有状态为 1 或 2 时才会公布承诺。输入超出范围时，程序会在任何哈希计算之前停机。

3. 算术

模型只使用整数。机器没有浮点运算，而验证者必须能精确复现评分，浮点运算无法保证跨机器一致。

hidden[j] = max( (b1[j] + Σ w1[j][i] · x[i]) >> s , 0 )      for each hidden unit j
score     = (b2 + Σ w2[j] · hidden[j]) >> s
approved  = score >= threshold

权重为带 s 个小数位的定点数：s = 8 时，权重 256 表示 1.0。求和使用 i64，每次乘法和加法都经过检查，因此权重大到会溢出的模型得到的是状态 4，而不是错误的评分。Rust 中对负的 i64 做 >> 向负无穷取整，Python 的 >> 也是如此，所以一个十行的 Python 函数就可以作为参考实现。

演示模型有八个特征和四个隐藏单元。它的权重是为本页手工编写的。它不是训练出来的模型，也不能说明任何关于信用的事。

{
  "shift": 8,
  "threshold": 600,
  "features": [
    {"name": "age_years", "min": 18, "max": 120},
    {"name": "income_thousands", "min": 0, "max": 100000},
    {"name": "debt_to_income_pct", "min": 0, "max": 1000},
    {"name": "on_time_payments_pct", "min": 0, "max": 100},
    {"name": "utilisation_pct", "min": 0, "max": 100},
    {"name": "history_years", "min": 0, "max": 100},
    {"name": "inquiries_12m", "min": 0, "max": 100},
    {"name": "delinquencies", "min": 0, "max": 100}
  ],
  "w1": [
    [  64,   96,  -512,  1536,  -640,  1024, -2048, -8192],
    [   0,  256, -1024,     0,     0,     0,     0,     0],
    [   0,    0,     0,  2560, -1280,     0, -4096, -16384],
    [ 128,    0,     0,     0,     0,  2048,     0,     0]
  ],
  "b1": [25600, 12800, -128000, 0],
  "w2": [160, 96, 224, 128],
  "b2": 76800
}

4. Guest 程序

my-guests/score/src/main.rs，完整代码：

#![no_std]
#![no_main]

use guest_sdk::{halt, read_input, read_public, sha256_compress, write_output};

const MAX_FEATURES: usize = 16;
const MAX_HIDDEN: usize = 16;

const APPROVED: u32 = 1;
const DECLINED: u32 = 2;
const OUT_OF_RANGE: u32 = 3;
const BAD_MODEL: u32 = 4;

/// SHA-256's initial state (FIPS 180-4 §5.3.3).
const IV: [u32; 8] = [
    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
];

/// SHA-256 of `words`, each word taken as four big-endian bytes. The message is whole words,
/// so the padding is whole words too: `0x80000000`, zeros, then the bit length in the last
/// word of a block (the length's high word is always zero here).
fn sha256_words(words: &[u32]) -> [u32; 8] {
    let mut buf = [0u32; 24];
    buf[16..].copy_from_slice(&IV);
    let mut fill = 0;
    for &w in words {
        buf[fill] = w;
        fill += 1;
        if fill == 16 {
            sha256_compress(&mut buf);
            fill = 0;
        }
    }
    buf[fill] = 0x8000_0000;
    fill += 1;
    if fill > 14 {
        buf[fill..16].fill(0);
        sha256_compress(&mut buf);
        fill = 0;
    }
    buf[fill..15].fill(0);
    buf[15] = 32 * words.len() as u32;
    sha256_compress(&mut buf);
    let mut out = [0u32; 8];
    out.copy_from_slice(&buf[16..]);
    out
}

/// `weight · x`, added to `acc`; `None` when it does not fit an i64.
fn mul_add(acc: i64, weight: u32, x: i64) -> Option<i64> {
    acc.checked_add((weight as i32 as i64).checked_mul(x)?)
}

/// Runs the model in the public segment over the private features.
fn score(features: &[i32], hidden: usize, shift: u32) -> Option<i64> {
    let n = features.len();
    // The public segment after the header and the feature ranges:
    // hidden × n first-layer weights, hidden biases, hidden second-layer weights, one bias.
    let w1 = 4 + 2 * n;
    let b1 = w1 + hidden * n;
    let w2 = b1 + hidden;
    let b2 = w2 + hidden;

    let mut out = read_public(b2 as u32) as i32 as i64;
    for j in 0..hidden {
        let mut acc = read_public((b1 + j) as u32) as i32 as i64;
        for (i, &x) in features.iter().enumerate() {
            acc = mul_add(acc, read_public((w1 + j * n + i) as u32), x as i64)?;
        }
        // Fixed point: drop the fractional bits, then ReLU.
        let h = (acc >> shift).max(0);
        out = mul_add(out, read_public((w2 + j) as u32), h)?;
    }
    Some(out >> shift)
}

/// Public segment, fixed at deploy (every value an i32):
///   [features n, hidden units, threshold, fractional bits,
///    n × (min, max), hidden × n weights, hidden biases, hidden weights, bias]
/// Private input: [salt (4 words), n features].
/// Outputs: [status, 0, commitment (first 5 words), 0], where
/// commitment = SHA-256(salt ‖ features), every word big-endian.
#[no_mangle]
pub extern "C" fn main() -> ! {
    let n = read_public(0) as usize;
    let hidden = read_public(1) as usize;
    let threshold = read_public(2) as i32 as i64;
    let shift = read_public(3);
    if n == 0 || n > MAX_FEATURES || hidden == 0 || hidden > MAX_HIDDEN || shift > 31 {
        write_output(0, BAD_MODEL);
        halt();
    }

    // The committed message: the salt, then the features, in input order.
    let mut message = [0u32; 4 + MAX_FEATURES];
    for (i, w) in message.iter_mut().enumerate().take(4 + n) {
        *w = read_input(i as u32);
    }
    let mut features = [0i32; MAX_FEATURES];
    let mut in_range = true;
    for i in 0..n {
        let x = message[4 + i] as i32;
        let min = read_public(4 + 2 * i as u32) as i32;
        let max = read_public(5 + 2 * i as u32) as i32;
        in_range &= min <= x && x <= max;
        features[i] = x;
    }
    if !in_range {
        write_output(0, OUT_OF_RANGE);
        halt();
    }

    let status = match score(&features[..n], hidden, shift) {
        Some(s) if s >= threshold => APPROVED,
        Some(_) => DECLINED,
        None => BAD_MODEL,
    };
    let commitment = sha256_words(&message[..4 + n]);

    write_output(0, status);
    for k in 0..5 {
        write_output(2 + k as u32, commitment[k]);
    }
    halt();
}

**模型是数据，而不是代码。**权重通过 read_public 读取，因此同一个已部署的镜像可以服务任何不超过 16 个特征和 16 个隐藏单元的模型。更换模型就是用新的公开段重新部署同一份代码，得到新的程序 id。贷款方无法在申请人不知情时替换权重，申请人也无法挑选一个更宽松的模型：回执注明程序 id，而该 id 绑定了权重。

**范围是模型的一部分。**没有范围，申请人固然无法谎报某个值（承诺阻止了这一点），但认证方可能会签下荒谬的数值，例如年龄为 −5，而带负权重的模型会对这样的值给予奖励。这项检查同时也限定了算术的取值范围。

**盐值承担两项任务。**其一，它使承诺无法被猜出：八个小整数的熵很少，没有盐值的话，任何人都可以对候选申请人逐一哈希再比对。其二，它让 128 个随机比特参与计算。在约束集 7 对证明的总线总和加入盲化之前，对少量小的私有字的调用可以直接从证明本身暴力破解，fullnode 的说明也要求这类程序读取随机字。Chain 18 运行的是约束集 8，该问题已修复，但盐值只需四个输入字，就能让这个问题不复存在。

5. 主机端

score.py 只使用 Python 标准库：

score.py setup   <model.json>                            writes public.txt
score.py witness <model.json> <salt: 32 hex> <x0> <x1> …  prints the private words;
                                                        stderr: the score, the decision, the commitment
score.py commit  <salt: 32 hex> <x0> <x1> …              prints the commitment alone

参考评分函数和承诺的完整代码：

def score(m, x):
    """The guest's arithmetic exactly: integers, a floor shift after each layer, ReLU between."""
    out = m["b2"]
    for row, b, w2 in zip(m["w1"], m["b1"], m["w2"]):
        h = max((b + sum(w * xi for w, xi in zip(row, x))) >> m["shift"], 0)
        out += w2 * h
    return out >> m["shift"]

def commitment(salt: bytes, x):
    return hashlib.sha256(salt + b"".join(struct.pack(">i", xi) for xi in x)).digest()

$ cd my-guests/score
$ python3 score.py setup model.json
wrote public.txt (61 words)
$ cat public.txt
8 4 600 8 18 120 0 100000 0 1000 0 100 0 100 0 100 0 100 0 100 64 96 4294966784 1536 4294966656 1024 4294965248 4294959104 0 256 4294966272 0 0 0 0 0 0 0 0 2560 4294966016 0 4294963200 4294950912 128 0 0 0 0 2048 0 0 25600 12800 4294839296 0 160 96 224 128 76800

较大的数字是负权重：4294966784 即 −512。

guest 程序已与该参考实现对照测试：对 300 个随机申请人比较决策和全部五个承诺字，并对评分为 599 和 600 的申请人做了测试。每一例都一致。

6. 构建与运行

$ rand-guest build my-guests/score --max-words 65535
462 words against a cap of 65535 (fits); 0 ecall(s) with a non-static a7
OK
wrote my-guests/score/image.bin and its .sha256 (462 words, hc c63d7b15a165a11d007ce48bc37563b71f77fcc4991ffe0182c8cf4c77b6e7b5, program id ce8d234faf737c24bdd2826933ac843973c140c53e76fbb2cccaef3073da9818)

一位 41 岁的申请人，收入 8.5 万，负债收入比 28%，按时还款率 97%，额度使用率 22%，信用历史 12 年，一次查询，无违约记录：

$ python3 score.py witness model.json 00112233445566778899aabbccddeeff 41 85 28 97 22 12 1 0 > witness.txt
score 1075 approved
commitment 9430c3818f5966f8dd33f78e05a7d079355191e6
$ cat witness.txt
1122867 1146447479 2291772091 3437096703 41 85 28 97 22 12 1 0
$ rand-guest run image.bin --public $(cat public.txt) --input $(cat witness.txt) --tier 14
out[0] = 1
out[1] = 0
out[2] = 2486223745
out[3] = 2405000952
out[4] = 3711170446
out[5] = 94883961
out[6] = 894538214
out[7] = 0
cycles 1810
tier 12
tier 14: fits (cycles 1946 of 16383, Poseidon2 permutations 136 of 2048)

2486223745 即 0x9430c381，是承诺的前四个字节。评分 1075 没有出现在任何输出中。

第二位申请人（23、31、55、82、91、2、6、2，使用另一个盐值）评分为 417，得到 out[0] = 2 和他自己的承诺，周期数同样是 1,810。把第一位申请人的年龄改为 17，得到 out[0] = 3，没有承诺。

7. 预算

这是四个程序中成本最低的。前向传播为 36 次乘法。处于程序上限的模型，即 16 个特征和 16 个隐藏单元，是 272 次乘法和 325 个字的公开段。它在模拟器中测得 7,900 个周期，约为第 14 档的一半。

运行成本与数据无关：200 个随机申请人，无论通过还是拒绝，每个都恰好用了 1,810 个周期。一次调用声明的 gas 上限是公开的，由该次运行的 gas 取整得出，因此周期数随输入变化的程序会泄露一点输入信息。这个程序在这方面没有可泄露的东西。

自 Chain 18 起，钱包会打印该次运行的确切 gas 和它声明的上限：

gas: 2011 (declaring 2048, tier 12)

1,948 行，每行 1 gas，外加一次压缩的 63。

8. 部署

模型的 61 个字与代码字按同样方式计费：0.001 + 0.0001 × (462 + 61) = 0.0533 RAND。

$ rand fee deploy 462 --public-words 61
0.0533 RAND
$ rand program deploy image.bin --public public.txt
program id: 7bbec14289f4446231b3a9a5ac18cb0613a373ca8a14fe4f046f3fde7ae6c73c (462 words, hc 157b3dc61da165a18be47c00b76375c3c4fc771f01fe1f994ccfc882b5e7b677, public input 61 words, digest a08a7c691c45babeb39e953930d4d7174662b7b8adcc2d0f4e6c193d362d6668)
proving the spend authorisation on this machine (tier 10; seconds)…
authorisation proved in 7.4s: tier 10, 1364940 bytes
proving the bundle (tier 14; about a minute and a half on a laptop)…
proved in 123.5s: tier 14, 1497319 bytes
submitted deploy d47a9323ea53bfafc3faa36d004416d374bf3c2a48971d87e346be426b0caf14
  0 RAND out, 59.7229 RAND change, fee 0.0533 RAND, anchored at height 98062, proved in 123.5s (bundle) + 7.4s (auth)

9. 调用

$ rand call 7bbec14289f4446231b3a9a5ac18cb0613a373ca8a14fe4f046f3fde7ae6c73c \
    $(sed 's/[0-9][0-9]*/--input &/g' witness.txt)

proving the call locally (12 inputs stay private, over the program's 61-word public input)…
gas: 2011 (declaring 2048, tier 12)
fee 0.005673037 RAND (incl. two price steps of headroom)
proved in 30.6s: tier 12, 1838256 bytes, outputs [1, 0, 2486223745, 2405000952, 3711170446, 94883961, 894538214, 0]
proving the spend authorisation on this machine (tier 10; seconds)…
authorisation proved in 6.8s: tier 10, 1369611 bytes
proving the bundle (tier 14; about a minute and a half on a laptop)…
proved in 124.3s: tier 14, 1499112 bytes
submitted call 454c1b9eb1e159e682d4ff26b71f77d8a950b813533d91a89293dd432fdcf6f7
  0 RAND out, 59.696058627 RAND change, fee 0.005673037 RAND, anchored at height 98832, proved in 124.3s (bundle) + 6.8s (auth)
{
  "h_in": "ef80c744a8cdea62b56e334baaf7372e4a2e6c8282d37aa8ae96b4f039ec1a22",
  "h_pub": "a08a7c691c45babeb39e953930d4d7174662b7b8adcc2d0f4e6c193d362d6668",
  "height": 98993,
  "index": 0,
  "outputs": [
    1,
    0,
    2486223745,
    2405000952,
    3711170446,
    94883961,
    894538214,
    0
  ],
  "program": "7bbec14289f4446231b3a9a5ac18cb0613a373ca8a14fe4f046f3fde7ae6c73c",
  "tier": 12,
  "tx": "454c1b9eb1e159e682d4ff26b71f77d8a950b813533d91a89293dd432fdcf6f7"
}
input transcript published; open it with `rand open-call 454c1b9eb1e159e682d4ff26b71f77d8a950b813533d91a89293dd432fdcf6f7`

状态为 1，承诺为十六进制的 9430c381 8f5966f8 dd33f78e 05a7d079 355191e6。h_pub 是模型 61 个字的摘要。特征、盐值和评分都不在交易中。

在 Apple Silicon 笔记本上，这次调用耗时三分多钟：调用证明 31 秒，花费授权 7 秒，捆绑包 124 秒，峰值内存 6.2 GB。证明大小为 1,838,256 字节。

10. 自行验证

贷款方一侧，手里只有回执和认证方签过名的承诺：

1. **模型。**对程序 id 调用 rand_getProgramPublic 会返回这 61 个字。将它们与公布的 model.json 比较（score.py setup 可以重建它们）。
2. **代码。**在相同的 circuits 提交上重新构建 my-guests/score，并把 hc 与程序的 code_hash 比较。
3. 回执。program 是模型的 id，输出 0 为 1，槽 7 不是 3735928559。
4. **承诺。**输出 2 到 6 以十六进制打印，即认证方所签承诺的前 20 字节：

$ python3 score.py commit 00112233445566778899aabbccddeeff 41 85 28 97 22 12 1 0
9430c3818f5966f8dd33f78e05a7d079355191e6

拒绝同样是一份回执。第二位申请人的调用 119e7834…1b3b(在 chain 18 上;在 chain 20 上重复执行为 c8a60183…9f73,结果同样是拒绝)以同样的方式被证明并提交:

$ python3 score.py witness model.json 0f1e2d3c4b5a69788796a5b4c3d2e1f0 23 31 55 82 91 2 6 2 > witness.txt
score 417 declined
commitment 0313ea462178574c49a10fe7ea1d84207652e1a3
$ rand call 7bbec14289f4446231b3a9a5ac18cb0613a373ca8a14fe4f046f3fde7ae6c73c \
    $(sed 's/[0-9][0-9]*/--input &/g' witness.txt)
…
gas: 2011 (declaring 2048, tier 12)
proved in 26.1s: tier 12, 1836624 bytes, outputs [2, 0, 51636806, 561534796, 1235292135, 3927802912, 1985143203, 0]
…
submitted call 119e7834033edd19bba8e10c1a764e8bdbc0b1c8415a42f041faa392c6411b3b

状态为 2,而 51636806 即 0x0313ea46。Gas、声明的上限和档位都与获批调用相同,因此两者在链上只有状态字和承诺不同,别无差异。申请人没有理由公开一次拒绝,但无论哪种结果,放款方都可以要求出示回执,而被拒绝的申请人无法拿出一份获批的回执。

证明不能给你什么

• 数据的真实性。 证明表明模型是在已承诺的数值上运行的。这些数值是否真实,取决于证明方的一面之词,放款方为此只能信任证明方的签名。
• 申请人的不可关联性。 承诺是一个稳定的标识符:证明方能够认出它,而承诺相同的两份回执对应的是同一位申请人和同一份数据。证明方为每次申请提供一个新的盐值,可以解决后一点,但解决不了前一点。
• 保密的模型。 权重是公开的。对于一条必须让人读得懂的规则,这正是目的所在;而对于把模型视为商业秘密的放款方,这是一个缺点。申请人也可以搜索能够通过的输入,但没有证明方对这些输入的签名,就无法使用它们。
• 防范不诚实的证明方进行探测。 任何知道特征的人都可以自己运行这个公开的模型。这里的隐私,是申请人相对于放款方和公众而言的,而不是相对于提供数据的一方。
• 大型模型。 十六个特征和十六个隐藏单元只是一张评分卡,而不是深度网络。一次调用的上限为 14 档,约一万六千个周期。