Add admin.utils to verify protocol payments and ERC-20 transfers

[ManulParihar]

What this does

Adds admin.utils, so the backend can check what a mined transaction actually paid, and whether it's final, before issuing an eSIM. Nothing is signed or sent. Prices come back as bigint cents, the same format the contracts use (123456n is $1234.56).

• verifyProtocolPayment(tx, symbol, eSIMWallet): for protocol purchases. It returns each purchase's paymentReference, price in cents, amount and vault, taken from the contracts' own events. It handles several purchases in one transaction. The symbol is passed as text ("USDC").
• verifyERC20Transfer(tx, token, sender, destination): for any ERC-20. It adds up direct transfers from sender to destination and returns the raw amount and cents (1 token counted as $1).

Finality

A mined block on Base can still be reorged out, so both functions also return finality, blockNumber and blockHash:

• latest: mined, but can still be reverted
• safe: its batch is posted to L1 (about 1 min on mainnet)
• finalized: can't be reverted (about 19 min on mainnet)

Issue eSIMs only on finalized. Store the block hash and check again later if it's not final yet. A receipt passed in from a block that was reorged out throws ReceiptNotCanonicalError.

Details

• tx can be a hash or a receipt. Pass the hash when it came from a user.
• All reads go out at once, so a check is one round trip.
• Bad input, unknown or reverted transactions, unknown symbols, non-protocol wallets and non-ERC-20 addresses each throw their own error, exported from kokio-sdk/admin.
• Events from look-alike contracts, and other users' purchases in the same transaction, are ignored.

Tests

• Unit: 468 passed.
• The fork user flow checks every real purchase the way the backend would. On the fork it also covers latest changing to finalized, and a real reorg.

Also

• Docs: docs/admin/utils.md
• Version 3.2.1 to 3.3.0