docs(cryptography): reviewer-suggested README intros and kit codecs in tests

Adopt amilz's beginner-friendly curve intros with links to the merged
SIMD-0302/0388 specs and EIP-197, and switch the TypeScript tests to
kit codecs: getBase16Codec for hex vectors and a struct codec spelling
out the aggregate-verify wire layout.

Author: dev-jodee

cryptography/bls12-381/pinocchio/README.md

@@ -1,6 +1,10 @@
 # BLS12-381 curve operations (Pinocchio)
 
-A stateless program that wraps the BLS12-381 group operations of the `sol_curve_group_op` syscall. Results come back as transaction return data. Points are big-endian: G1 = 96 bytes, G2 = 192 bytes; scalars are 32 bytes big-endian and go first in the instruction data.
+BLS12-381 is a modern elliptic curve designed for _pairings_ — a special operation that powers short aggregate signatures (many signers, one small signature to check) and zero-knowledge proofs, and it's the curve Ethereum and Solana's upcoming consensus both rely on. The underlying point math (adding two points, subtracting, or multiplying a point by a number) is far too expensive to run in ordinary program code without exhausting Solana's compute budget, so the runtime exposes it as a native building block: the `sol_curve_group_op` syscall. This example is a thin, stateless wrapper over that syscall — you pass in points and scalars, it returns the result as transaction return data — so you can see the raw curve operations by themselves before combining them into something like signature verification.
+
+Learn more: [Solana's BLS12-381 syscall spec (SIMD-0388)](https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0388-bls12-381-syscalls.md) · [BLS12-381 for the rest of us (a beginner-friendly explainer)](https://hackmd.io/@benjaminion/bls12-381)
+
+Points are big-endian: G1 = 96 bytes, G2 = 192 bytes; scalars are 32 bytes big-endian and go first in the instruction data.
 
 | Discriminator | Instruction | Input          |
 | ------------- | ----------- | -------------- |

cryptography/bls12-381/pinocchio/tests/bls12-381.test.ts

@@ -1,10 +1,11 @@
-import { Buffer } from 'node:buffer';
 import {
     type Address,
     appendTransactionMessageInstruction,
     createTransactionMessage,
     generateKeyPairSigner,
+    getBase16Codec,
     type KeyPairSigner,
+    type ReadonlyUint8Array,
     lamports,
     pipe,
     setTransactionMessageFeePayerSigner,
@@ -36,7 +37,8 @@ const IX_G2_ADD = 3;
 const IX_G2_SUB = 4;
 const IX_G2_MUL = 5;
 
-const hex = (s: string) => Uint8Array.from(Buffer.from(s, 'hex'));
+const base16 = getBase16Codec();
+const hex = (s: string) => base16.encode(s);
 
 const scalarThree = () => {
     const scalar = new Uint8Array(32);
@@ -57,7 +59,7 @@ describe('bls12-381', () => {
         svm.airdrop(payer.address, lamports(1_000_000_000n));
     });
 
-    async function send(discriminator: number, left: Uint8Array, right: Uint8Array) {
+    async function send(discriminator: number, left: ReadonlyUint8Array, right: ReadonlyUint8Array) {
         const data = new Uint8Array([discriminator, ...left, ...right]);
 
         const transactionMessage = pipe(
@@ -73,10 +75,15 @@ describe('bls12-381', () => {
         return result;
     }
 
-    async function expectReturnData(discriminator: number, left: Uint8Array, right: Uint8Array, expected: Uint8Array) {
+    async function expectReturnData(
+        discriminator: number,
+        left: ReadonlyUint8Array,
+        right: ReadonlyUint8Array,
+        expected: ReadonlyUint8Array,
+    ) {
         const result = await send(discriminator, left, right);
         assert(result instanceof TransactionMetadata, `transaction failed: ${result.toString()}`);
-        assert.deepEqual(result.returnData().data(), expected);
+        assert.deepEqual<ReadonlyUint8Array>(result.returnData().data(), expected);
     }
 
     it('G1 add: G + 2G == 3G', async () => {

cryptography/bn254/pinocchio/README.md

@@ -1,6 +1,8 @@
 # BN254 (alt_bn128) operations (Pinocchio)
 
-A stateless program that wraps the BN254 (alt_bn128) G2 group operations added by [SIMD-0302](https://github.com/solana-foundation/solana-improvement-documents/pull/302) and the pairing operation, via the `sol_alt_bn128_group_op` syscall. Results come back as transaction return data.
+BN254 is an elliptic curve — a set of points you can "add" and "multiply" using special math. What makes it useful is its _pairing_: an operation that relates points in a way ordinary addition can't, and that's the engine behind things like zero-knowledge proofs and BLS signatures (many signers collapse into one tiny signature that verifies in a single check). This curve math is far too expensive to run in normal program code without blowing past Solana's compute budget, so the runtime provides it as a native building block — the `sol_alt_bn128_group_op` syscall. This example is a thin, stateless wrapper over that syscall: it hands your points and scalars to the runtime and returns the result as transaction return data, so you can see exactly what goes in and comes out before building anything larger on top.
+
+Learn more: [Solana's BN254 G2 syscall spec (SIMD-0302)](https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0302-bn254-g2-syscalls.md) · [the alt_bn128/BN254 pairing encoding these ops follow (Ethereum EIP-197)](https://eips.ethereum.org/EIPS/eip-197)
 
 | Discriminator | Instruction      | Input                                                                          |
 | ------------- | ---------------- | ------------------------------------------------------------------------------ |

cryptography/bn254/pinocchio/tests/bn254.test.ts

@@ -1,12 +1,16 @@
-import { Buffer } from 'node:buffer';
 import {
     type Address,
     appendTransactionMessageInstruction,
     createTransactionMessage,
+    fixCodecSize,
     generateKeyPairSigner,
+    getBase16Codec,
+    getBytesCodec,
+    getStructCodec,
     type KeyPairSigner,
     lamports,
     pipe,
+    type ReadonlyUint8Array,
     setTransactionMessageFeePayerSigner,
     signTransactionMessageWithSigners,
 } from '@solana/kit';
@@ -41,7 +45,20 @@ const IX_AGGREGATE_VERIFY = 2;
 const ERR_INVALID_INPUT_LENGTH = 'InstructionErrorCustom { code: 0 }';
 const ERR_AGGREGATE_VERIFY_FAILED = 'InstructionErrorCustom { code: 3 }';
 
-const hex = (s: string) => Uint8Array.from(Buffer.from(s, 'hex'));
+const base16 = getBase16Codec();
+const hex = (s: string) => base16.encode(s);
+
+const g1 = fixCodecSize(getBytesCodec(), 64);
+const g2 = fixCodecSize(getBytesCodec(), 128);
+
+// Wire layout of the AggregateVerify instruction data (after the discriminator).
+const aggregateVerifyCodec = getStructCodec([
+    ['signature', g1],
+    ['negatedMessageHash', g1],
+    ['pubkey1', g2],
+    ['pubkey2', g2],
+    ['pubkey3', g2],
+]);
 
 describe('bn254', () => {
     const svm = new LiteSVM();
@@ -56,7 +73,7 @@ describe('bn254', () => {
         svm.airdrop(payer.address, lamports(1_000_000_000n));
     });
 
-    async function send(discriminator: number, input: Uint8Array) {
+    async function send(discriminator: number, input: ReadonlyUint8Array) {
         const data = new Uint8Array(1 + input.length);
         data[0] = discriminator;
         data.set(input, 1);
@@ -75,19 +92,19 @@ describe('bn254', () => {
     }
 
     const verifyInput = (aggSig: string) =>
-        new Uint8Array([
-            ...hex(aggSig),
-            ...hex(NEGATED_MESSAGE_HASH),
-            ...hex(G2_GENERATOR),
-            ...hex(G2_TWO_GENERATOR),
-            ...hex(G2_THREE_GENERATOR),
-        ]);
+        aggregateVerifyCodec.encode({
+            negatedMessageHash: hex(NEGATED_MESSAGE_HASH),
+            pubkey1: hex(G2_GENERATOR),
+            pubkey2: hex(G2_TWO_GENERATOR),
+            pubkey3: hex(G2_THREE_GENERATOR),
+            signature: hex(aggSig),
+        });
 
     it('adds two G2 points: G + 2G == 3G', async () => {
         const result = await send(IX_G2_ADD, new Uint8Array([...hex(G2_GENERATOR), ...hex(G2_TWO_GENERATOR)]));
 
         assert(result instanceof TransactionMetadata, `transaction failed: ${result.toString()}`);
-        assert.deepEqual(result.returnData().data(), hex(G2_THREE_GENERATOR));
+        assert.deepEqual<ReadonlyUint8Array>(result.returnData().data(), hex(G2_THREE_GENERATOR));
     });
 
     it('multiplies a G2 point by a scalar: G * 3 == 3G', async () => {
@@ -96,7 +113,7 @@ describe('bn254', () => {
         const result = await send(IX_G2_MUL, new Uint8Array([...hex(G2_GENERATOR), ...scalar]));
 
         assert(result instanceof TransactionMetadata, `transaction failed: ${result.toString()}`);
-        assert.deepEqual(result.returnData().data(), hex(G2_THREE_GENERATOR));
+        assert.deepEqual<ReadonlyUint8Array>(result.returnData().data(), hex(G2_THREE_GENERATOR));
     });
 
     it('verifies an aggregate signature from all signers with one pairing check', async () => {