@ercworldio/blockchain-shared 1.0.5-dev.7.PROJ-1464.0 → 1.0.5-dev.8

package/build/services/solana/escrow/services/TreasuryWithdrawalSignature.d.ts

@@ -0,0 +1,58 @@
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+/**
+ * Treasury withdrawal approval message + Ed25519 assembly.
+ *
+ * Mirrors the escrow program's `build_withdrawal_message` and its Ed25519SigVerify layout so the
+ * batch-withdraw transaction the funding worker sends carries signatures the program accepts.
+ */
+/** One treasury manager/executive approval over a request's message. */
+export interface TreasurySignatureInput {
+    /** Base58 signer pubkey — a current treasury manager/executive on-chain. */
+    signer: string;
+    /** 64-byte Ed25519 signature (base64/hex/base58). */
+    signature: string;
+}
+/**
+ * Builds the UTF-8 approval message a treasury signer approves. MUST match the program's
+ * `build_withdrawal_message` byte for byte, or verification fails.
+ *
+ *   Withdrawal Approval
+ *   Version: 1
+ *   Chain: <chainId>
+ *   Request: <requestId>
+ *   Recipient: <recipient base58>
+ *   Token: <mint base58>
+ *   Amount: <committed amount, raw base units>
+ *
+ * `Amount` is the committed (approved) amount — the net paid out is chosen later by the backend
+ * and bounded on-chain by TreasuryConfig.max_fee_delta. The title + Version line domain-separate
+ * the signature; bump Version in lockstep with the program on any format change.
+ */
+export declare function buildWithdrawalApprovalMessage(params: {
+    recipient: PublicKey;
+    tokenMint: PublicKey;
+    committedAmount: bigint;
+    chainId: bigint;
+    requestId: bigint;
+}): Buffer;
+/** Decode a 64-byte Ed25519 signature from base64, hex (0x-optional), or base58. */
+export declare function decodeEd25519Signature(s: string): Uint8Array;
+/** One fully-decoded signature entry: pubkey + signature over `message`. */
+export interface Ed25519Entry {
+    publicKey: Uint8Array;
+    signature: Uint8Array;
+    message: Uint8Array;
+}
+/**
+ * Builds a single Ed25519SigVerify instruction carrying `entries` self-contained signatures
+ * (each entry's pubkey, signature and message live in this instruction's own data). This is the
+ * compact layout the program scans in `verify_treasury_threshold`; one instruction for the whole
+ * batch keeps the transaction far smaller than one instruction per signature.
+ *
+ * Identical messages are stored ONCE and shared by every signature over them, since the offsets
+ * table lets multiple entries point at the same message region. This matters: the N signers who
+ * approve one withdrawal all sign the same ~194-byte payload, so without sharing, a 2-of-N
+ * approval would spend an extra ~194 bytes and overflow Solana's 1232-byte transaction limit.
+ */
+export declare function buildTreasuryEd25519Instruction(entries: Ed25519Entry[]): TransactionInstruction;
+//# sourceMappingURL=TreasuryWithdrawalSignature.d.ts.map

package/build/services/solana/escrow/services/TreasuryWithdrawalSignature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreasuryWithdrawalSignature.d.ts","sourceRoot":"","sources":["../../../../../src/services/solana/escrow/services/TreasuryWithdrawalSignature.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,SAAS,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGpF;;;;;GAKG;AAEH,wEAAwE;AACxE,MAAM,WAAW,sBAAsB;IACnC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE;IACnD,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,CAUT;AAED,oFAAoF;AACpF,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAU5D;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IACzB,SAAS,EAAE,UAAU,CAAC;IACtB,SAAS,EAAE,UAAU,CAAC;IACtB,OAAO,EAAE,UAAU,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,sBAAsB,CAoD/F"}

package/build/services/solana/escrow/services/TreasuryWithdrawalSignature.js

@@ -0,0 +1,109 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWithdrawalApprovalMessage = buildWithdrawalApprovalMessage;
+exports.decodeEd25519Signature = decodeEd25519Signature;
+exports.buildTreasuryEd25519Instruction = buildTreasuryEd25519Instruction;
+const web3_js_1 = require("@solana/web3.js");
+const bs58_1 = __importDefault(require("bs58"));
+/**
+ * Builds the UTF-8 approval message a treasury signer approves. MUST match the program's
+ * `build_withdrawal_message` byte for byte, or verification fails.
+ *
+ *   Withdrawal Approval
+ *   Version: 1
+ *   Chain: <chainId>
+ *   Request: <requestId>
+ *   Recipient: <recipient base58>
+ *   Token: <mint base58>
+ *   Amount: <committed amount, raw base units>
+ *
+ * `Amount` is the committed (approved) amount — the net paid out is chosen later by the backend
+ * and bounded on-chain by TreasuryConfig.max_fee_delta. The title + Version line domain-separate
+ * the signature; bump Version in lockstep with the program on any format change.
+ */
+function buildWithdrawalApprovalMessage(params) {
+    const text = "Withdrawal Approval\n" +
+        "Version: 1\n" +
+        `Chain: ${params.chainId}\n` +
+        `Request: ${params.requestId}\n` +
+        `Recipient: ${params.recipient.toBase58()}\n` +
+        `Token: ${params.tokenMint.toBase58()}\n` +
+        `Amount: ${params.committedAmount}`;
+    return Buffer.from(text, "utf8");
+}
+/** Decode a 64-byte Ed25519 signature from base64, hex (0x-optional), or base58. */
+function decodeEd25519Signature(s) {
+    const b64 = Buffer.from(s, "base64");
+    if (b64.length === 64)
+        return b64;
+    const hex = s.startsWith("0x") ? s.slice(2) : s;
+    if (/^[0-9a-fA-F]{128}$/.test(hex))
+        return Buffer.from(hex, "hex");
+    try {
+        const b58 = bs58_1.default.decode(s);
+        if (b58.length === 64)
+            return b58;
+    }
+    catch ( /* fallthrough */_a) { /* fallthrough */ }
+    throw new Error("Invalid Ed25519 signature encoding (expected 64 bytes as base64/hex/base58)");
+}
+/**
+ * Builds a single Ed25519SigVerify instruction carrying `entries` self-contained signatures
+ * (each entry's pubkey, signature and message live in this instruction's own data). This is the
+ * compact layout the program scans in `verify_treasury_threshold`; one instruction for the whole
+ * batch keeps the transaction far smaller than one instruction per signature.
+ *
+ * Identical messages are stored ONCE and shared by every signature over them, since the offsets
+ * table lets multiple entries point at the same message region. This matters: the N signers who
+ * approve one withdrawal all sign the same ~194-byte payload, so without sharing, a 2-of-N
+ * approval would spend an extra ~194 bytes and overflow Solana's 1232-byte transaction limit.
+ */
+function buildTreasuryEd25519Instruction(entries) {
+    const N = entries.length;
+    const OFFSETS_SIZE = 14;
+    const ENTRY_SIZE = 32 + 64; // pubkey + signature
+    const header = 2 + N * OFFSETS_SIZE;
+    const msgStart = header + N * ENTRY_SIZE;
+    // Deduplicate message blobs by content; remember where each unique one lands.
+    const uniqueMessages = [];
+    const messageOffsets = [];
+    const seen = new Map();
+    let cursor = msgStart;
+    for (const entry of entries) {
+        const key = Buffer.from(entry.message).toString("base64");
+        let offset = seen.get(key);
+        if (offset === undefined) {
+            offset = cursor;
+            seen.set(key, offset);
+            uniqueMessages.push(entry.message);
+            cursor += entry.message.length;
+        }
+        messageOffsets.push(offset);
+    }
+    const data = Buffer.alloc(cursor);
+    data[0] = N; // number of signatures
+    data[1] = 0; // padding
+    for (let i = 0; i < N; i++) {
+        const base = 2 + i * OFFSETS_SIZE;
+        const pkOffset = header + i * ENTRY_SIZE;
+        const sigOffset = pkOffset + 32;
+        data.writeUInt16LE(sigOffset, base + 0); // signature_offset
+        data.writeUInt16LE(0xffff, base + 2); // signature_instruction_index (self)
+        data.writeUInt16LE(pkOffset, base + 4); // public_key_offset
+        data.writeUInt16LE(0xffff, base + 6); // public_key_instruction_index (self)
+        data.writeUInt16LE(messageOffsets[i], base + 8); // message_data_offset (may be shared)
+        data.writeUInt16LE(entries[i].message.length, base + 10); // message_data_size
+        data.writeUInt16LE(0xffff, base + 12); // message_instruction_index (self)
+        data.set(entries[i].publicKey, pkOffset);
+        data.set(entries[i].signature, sigOffset);
+    }
+    // Write each unique message once, at the offset its first referrer recorded.
+    for (let i = 0, offset = msgStart; i < uniqueMessages.length; i++) {
+        data.set(uniqueMessages[i], offset);
+        offset += uniqueMessages[i].length;
+    }
+    return new web3_js_1.TransactionInstruction({ keys: [], programId: web3_js_1.Ed25519Program.programId, data });
+}