the implementation, ze-gent

§07 / the implementation

the implementation

ze-gent is a single rust program of roughly nine hundred lines, deployed as a token-2022 transfer hook against the ze-gent mint on solana mainnet. on every transfer it reads the shielded reference price, updates the class assignment of the wallets involved, recomputes the linkability matrix across all classes, and applies a levy proportional to the squared leakage between the current holder distribution and the nearest point on the maximum-entropy frontier. all four operations execute atomically inside the same transaction and complete within a compute budget of two hundred thousand units.

the data layout

three pdas hold the protocol's mutable state. ["classes", mint] holds the packed class table, one byte per wallet (four bits value bucket, four bits diversifier window), up to sixty-five thousand wallets per account. ["linkability", mint] holds a thirty-six by thirty-six i128 fixed-point matrix, roughly twenty kilobytes. ["shield", mint] holds the accrued levy and a small distribution-state struct tracking the most recent payout slot.

// account layouts for the ze-gent transfer hook program
const CLASS_GRID_SIZE: usize = 36;          // 6 value buckets × 6 diversifier windows
const MAX_WALLETS: usize = 65_536;          // capacity of the class table
const FP_SCALE: i128 = 1_000_000_000_000;   // 1e12 fixed-point

#[account]
pub struct ClassTable {
    pub mint: Pubkey,
    pub wallet_count: u32,
    pub last_update_slot: u64,
    pub assignments: [u8; MAX_WALLETS],        // packed class index per wallet
    pub value_log: [u64; MAX_WALLETS],         // last known note value (for class transitions)
    pub first_seen_slot: [u64; MAX_WALLETS],   // for diversifier-age window calculation
}

#[account]
pub struct LinkabilityMatrix {
    pub mint: Pubkey,
    pub last_update_slot: u64,
    pub class_entropy: [i128; CLASS_GRID_SIZE],
    pub class_variance: [i128; CLASS_GRID_SIZE],
    pub linkability: [[i128; CLASS_GRID_SIZE]; CLASS_GRID_SIZE],
}

#[account]
pub struct ShieldState {
    pub mint: Pubkey,
    pub accrued: u64,
    pub last_distribution_slot: u64,
    pub total_distributed: u128,
    pub bump: u8,
}

the transfer hook

the transfer hook is the entry point. it is invoked by the token-2022 program on every transfer of the ze-gent mint, regardless of which application initiated it. the hook reads the shielded reference price, looks up source and destination wallets, transitions their class assignments if a value or age boundary has been crossed, updates the running class statistics, and returns the levy to be withheld from the input amount before the transfer settles.

// the transfer hook entry point, invoked on every transfer
pub fn execute(ctx: Context<Execute>, amount: u64) -> Result<u64> {
    let clock = Clock::get()?;
    let classes = &mut ctx.accounts.class_table;
    let link = &mut ctx.accounts.linkability_matrix;
    let shield = &mut ctx.accounts.shield;

    // 1. read shielded reference price
    let price_fp = read_shielded_reference_price(&ctx.accounts.curve_state)?;

    // 2. update source and destination class assignments
    let src_idx = lookup_or_insert(classes, &ctx.accounts.source.owner, clock.slot)?;
    let dst_idx = lookup_or_insert(classes, &ctx.accounts.destination.owner, clock.slot)?;

    let src_old_class = classes.assignments[src_idx];
    let dst_old_class = classes.assignments[dst_idx];

    let src_new_value = ctx.accounts.source.amount.saturating_sub(amount);
    let dst_new_value = ctx.accounts.destination.amount.saturating_add(amount);

    let src_new_class = compute_class(
        src_new_value,
        clock.slot.saturating_sub(classes.first_seen_slot[src_idx]),
    );
    let dst_new_class = compute_class(
        dst_new_value,
        clock.slot.saturating_sub(classes.first_seen_slot[dst_idx]),
    );

    classes.assignments[src_idx] = src_new_class;
    classes.assignments[dst_idx] = dst_new_class;
    classes.value_log[src_idx] = src_new_value;
    classes.value_log[dst_idx] = dst_new_value;
    classes.last_update_slot = clock.slot;

    // 3. update linkability matrix incrementally
    incremental_linkability_update(
        link,
        src_old_class, src_new_class,
        dst_old_class, dst_new_class,
        price_fp,
    )?;

    // 4. compute leakage in bits and apply the levy
    let leakage_fp = leakage_bits(link);
    let leak_sq_fp = (leakage_fp * leakage_fp) / FP_SCALE;
    let levy_rate_fp = (LEVY_K_FP * leak_sq_fp) / FP_SCALE;
    let levy = ((amount as i128 * levy_rate_fp) / FP_SCALE)
        .max(0)
        .min(amount as i128) as u64;

    shield.accrued = shield.accrued.saturating_add(levy);
    Ok(levy)
}

the linkability update

the linkability update is the most expensive operation in the hook. a naive recompute of the full thirty-six by thirty-six matrix on every transfer would exceed the compute budget by an order of magnitude. the implementation here is incremental: when a transfer moves a wallet between classes, only the rows and columns touching those two classes are updated, in constant time, using welford's online algorithm. total cost is bounded at four class updates and one hundred forty-four cell updates, regardless of how many wallets the protocol tracks.

// incremental linkability update using welford's online algorithm
fn incremental_linkability_update(
    link: &mut LinkabilityMatrix,
    src_old: u8, src_new: u8,
    dst_old: u8, dst_new: u8,
    price_fp: i128,
) -> Result<()> {
    let affected: [u8; 4] = [src_old, src_new, dst_old, dst_new];

    for &class_i in affected.iter() {
        let i = class_i as usize;
        let n = (link.class_entropy[i].abs() / FP_SCALE).max(1);
        let delta = price_fp - link.class_entropy[i];
        link.class_entropy[i] += delta / n;
        let delta2 = price_fp - link.class_entropy[i];
        link.class_variance[i] += (delta * delta2) / FP_SCALE;

        for j in 0..CLASS_GRID_SIZE {
            if j == i { continue; }
            let cross = ((price_fp - link.class_entropy[i]) * (price_fp - link.class_entropy[j]))
                / FP_SCALE;
            link.linkability[i][j] = (link.linkability[i][j] * (n - 1) + cross) / n;
            link.linkability[j][i] = link.linkability[i][j];  // symmetric
        }
        link.linkability[i][i] = link.class_variance[i];
    }

    link.last_update_slot = Clock::get()?.slot;
    Ok(())
}

the leakage

leakage is computed in closed form. the standard approach inverts the linkability matrix, which is expensive. the implementation here uses a banded approximation that exploits a property of the class grid: classes far apart on the value-age grid are nearly unlinkable, so off-band entries can be treated as zero. inverting a banded matrix is linear in matrix size rather than cubic, which fits the budget. the result is a single fixed-point value: the leakage, in bits, from the holder set to the frontier.

// leakage via banded matrix inversion
const BAND_WIDTH: usize = 5;

fn leakage_bits(link: &LinkabilityMatrix) -> i128 {
    let mut banded = [[0i128; CLASS_GRID_SIZE]; CLASS_GRID_SIZE];
    for i in 0..CLASS_GRID_SIZE {
        for j in 0..CLASS_GRID_SIZE {
            if (i as isize - j as isize).abs() as usize <= BAND_WIDTH {
                banded[i][j] = link.linkability[i][j];
            }
        }
    }

    // tridiagonal inversion in linear time via the thomas algorithm (~120 lines omitted)
    let inverted = invert_banded(&banded);
    let weights = compute_class_weights(link);

    let mut set_entropy: i128 = 0;
    for i in 0..CLASS_GRID_SIZE {
        for j in 0..CLASS_GRID_SIZE {
            set_entropy += (weights[i] * inverted[i][j] * weights[j])
                / (FP_SCALE * FP_SCALE);
        }
    }

    let frontier = frontier_entropy_at_target(target_entropy_fp());
    let diff = set_entropy.saturating_sub(frontier);
    isqrt_fp(diff.max(0))
}

the seal

once compiled and tested against simulated holder distributions, the program was deployed through the bpf upgradeable loader and its upgrade authority set to none in the same session, permanently sealing the bytecode. the mint was created with token-2022 and the transfer hook configured at creation to point at the program; the extra-account-metas list (classes, linkability, shield) was published in the same transaction. from that moment the protocol has run without intervention. crucially, the proving lineage it descends from carries no trusted setup. there is no secret ceremony parameter to leak, no toxic waste to dispose of.

# the deployment sequence: one shot, no rollback, no ceremony

# 1. build and verify
anchor build --verifiable
sha256sum target/deploy/ze_gent.so > deployment.hash

# 2. deploy program to mainnet
solana program deploy \
    --url https://api.mainnet-beta.solana.com \
    --keypair ./deployer.json \
    target/deploy/ze_gent.so

# 3. revoke upgrade authority in the same session
solana program set-upgrade-authority \
    <PROGRAM_ID> \
    --new-upgrade-authority none \
    --skip-new-upgrade-authority-signer-check

# 4. create the mint with the transfer hook extension
spl-token --program-2022 create-token \
    --transfer-hook <PROGRAM_ID>

# 5. publish extra account metas for the hook
ze-gent-cli initialize-extra-metas \
    --mint <MINT_ADDRESS> \
    --class-pda <CLASS_PDA> \
    --linkability-pda <LINKABILITY_PDA> \
    --shield-pda <SHIELD_PDA>

# 6. shred the deployer keypair
shred -u ./deployer.json

the steps above were executed once. there is no version two, no patch, no parameter anyone can adjust, and, by lineage, no ceremony anyone has to trust. the program is what runs. the math is what produces the levy. the chain decides whether the holder set sits on the frontier or off it. nothing else is in the path.