mathematically perfect

overview

mathematically perfect is a Solana program that executes a trade in one coin only when the trade is accompanied by a certificate of optimality that the program can verify exactly. The proposer is an off chain model. The judge is the program. This document gives the full specification needed to produce accepted certificates, read the accounts, and reproduce the arithmetic.

objective and constraints

The objective is U(x) = ln(R − c(x)) + ln(I + x) with R the vault's lamports, I the vault's token balance, and c the exact cost on the constant product curve with reserves s and t. The constraints are g₁(x) = c(x) − (3/4)R ≤ 0, g₂(x) = |p(x) − p₀| / p₀ − 1/20 ≤ 0 and g₃(x) = −(I + x) ≤ 0. All three constants are stored in the config account and cannot be changed after initialisation.

certificate format

A certificate is four Q64.64 values in the submit instruction data, in order: x_star (signed, sign in the top bit), lambda_1, lambda_2, lambda_3. Total 64 bytes after the 8 byte instruction discriminator. The program ignores any trailing bytes.

verification

On submit the program reads s and t from the curve account, R from the vault lamports, and I from the vault token account. It computes c(x*), c′(x*), p(x*), every gᵢ(x*) and gᵢ′(x*), and U′(x*). It forms r_stat, r_prim, r_dual and r_slack as defined on the home page and sums them. If the sum is zero it issues a cross program invocation to the curve for exactly x* tokens, re reads R and I, checks the invariants, and writes an accepted entry. Otherwise it writes a rejected entry. In both cases it increments the matching count and advances the ring head.

arithmetic

Q64.64 on u128 with a 256 bit intermediate for multiply and divide. Logarithm by the series ln(y) = 2 Σ_{n=0}^{23} (1/(2n+1)) ((y−1)/(y+1))^{2n+1} after reducing y into [1, 2) by powers of two and adding the matching multiple of ln 2, where ln 2 is the fixed constant 0xB17217F7D1CF79AB in Q64.64 fraction bits. Any implementation producing identical bits for these operations will produce accepted certificates.

solving

Determine the feasible interval by solving each gᵢ(x) = 0 on the buy side and sell side by bisection. Take the intersection. Find the root of U′(x) = 0 by bisection over the interval, 128 iterations. If the root is interior, the certificate is (root, 0, 0, 0). If U′ is positive at the upper edge, the certificate is (upper edge, λ for the binding constraint computed as U′(x*)/g′(x*), zeros elsewhere). If U′ is negative at the lower edge, the symmetric case holds. Submit immediately; any trade in between invalidates the solve.

accounts

config at seeds ["config", mint], 144 bytes. vault at seeds ["vault", mint], a system account holding sol and owning an associated token account for the coin. record at seeds ["record", mint], 8 + 16 + 64 × 160 bytes. Layouts are on the pda page.

instructions

initialize creates the accounts and stores constants, once. claim moves accrued creator fees into the vault; anyone may call it. submit verifies and executes. There are no others. The upgrade authority is set to none after deployment.

explorer name

The program is deployed with its IDL uploaded under the name mathematically_perfect using anchor idl init, so block explorers render the program account as mathematically perfect. The IDL address is derived from the program id and can be read by anyone.

site data

The site reads the price from Birdeye once per second through a server function and multiplies it by the on chain supply to show value in usd. The six hour chart is one minute closes fetched once when a page opens. Program accounts are read by subscription. Nothing on the site is editable by visitors.

glossary