@sovereign-sdk/web3 0.13.0 → 0.14.0

package/dist/index.mjs

@@ -430,21 +430,40 @@ async function createStandardRollup(rollupConfig, typeBuilderOverrides) {
 
 // src/rollup/solana-signable-rollup.ts
 import { isLedgerSolanaSigner } from "@sovereign-sdk/signers";
+import { bytesToHex as bytesToHex3, hexToBytes as hexToBytes2 } from "@sovereign-sdk/utils";
+import bs58 from "bs58";
 import { Base64 as Base642 } from "js-base64";
+var MULTISIG_SIMPLE_DISCRIMINATOR = 128;
 var VEC_LENGTH_PREFIX_SIZE = 4;
 var CHAIN_HASH_SIZE = 32;
 var PUBKEY_SIZE = 32;
 var SIGNATURE_SIZE = 64;
-var PREAMBLE_LENGTH = 85;
+var MULTISIG_PREAMBLE_FIXED_LENGTH = 53;
+var MAX_MULTISIG_SIGNERS = 21;
 var SIGNING_DOMAIN = new Uint8Array([
   255,
   ...new TextEncoder().encode("solana offchain")
 ]);
 var HEADER_VERSION = 0;
 var MESSAGE_FORMAT = 0;
-var SINGLE_SIGNER_COUNT = 1;
-function createSolanaPreamble(pubkey, chainHash, messageLength) {
-  const preamble = new Uint8Array(PREAMBLE_LENGTH);
+function compareByteArrays(left, right) {
+  const minLength = Math.min(left.length, right.length);
+  for (let i = 0; i < minLength; i++) {
+    if (left[i] !== right[i]) {
+      return left[i] - right[i];
+    }
+  }
+  return left.length - right.length;
+}
+function createSolanaPreamble(pubkeys, chainHash, messageLength) {
+  if (pubkeys.length < 1 || pubkeys.length > MAX_MULTISIG_SIGNERS) {
+    throw new Error(
+      `Invalid signer count: expected 1-${MAX_MULTISIG_SIGNERS} signers, got ${pubkeys.length}`
+    );
+  }
+  const preamble = new Uint8Array(
+    MULTISIG_PREAMBLE_FIXED_LENGTH + pubkeys.length * PUBKEY_SIZE
+  );
   let offset = 0;
   preamble.set(SIGNING_DOMAIN, offset);
   offset += 16;
@@ -454,10 +473,17 @@ function createSolanaPreamble(pubkey, chainHash, messageLength) {
   offset += 32;
   preamble[offset] = MESSAGE_FORMAT;
   offset += 1;
-  preamble[offset] = SINGLE_SIGNER_COUNT;
+  preamble[offset] = pubkeys.length;
   offset += 1;
-  preamble.set(pubkey, offset);
-  offset += 32;
+  for (const pubkey of pubkeys) {
+    if (pubkey.length !== PUBKEY_SIZE) {
+      throw new Error(
+        `Invalid public key length: expected ${PUBKEY_SIZE} bytes, got ${pubkey.length}`
+      );
+    }
+    preamble.set(pubkey, offset);
+    offset += PUBKEY_SIZE;
+  }
   new DataView(preamble.buffer, offset).setUint16(0, messageLength, true);
   return preamble;
 }
@@ -501,6 +527,13 @@ var SolanaSignableRollup = class {
     const serializedMessage = this.serializeSolanaSpecMessage(solanaMessage);
     return this.submitSerializedMessage(serializedMessage);
   }
+  /**
+   * Submits a Solana spec-compliant multisig message to the rollup.
+   */
+  async submitSolanaSpecMultisigMessage(solanaMessage) {
+    const serializedMessage = this.serializeSolanaSpecMultisigMessage(solanaMessage);
+    return this.submitSerializedMessage(serializedMessage);
+  }
   /**
    * Helper to build an unsigned transaction using the standard type builder.
    */
@@ -523,6 +556,45 @@ var SolanaSignableRollup = class {
     });
     return { response, transaction };
   }
+  /**
+   * Concatenates a Solana preamble with the message bytes it signs.
+   */
+  combinePreambleAndMessage(preamble, message) {
+    const signedMessage = new Uint8Array(preamble.length + message.length);
+    signedMessage.set(preamble, 0);
+    signedMessage.set(message, preamble.length);
+    return signedMessage;
+  }
+  /**
+   * Validates and canonicalizes the multisig pubkey list.
+   * The canonical order is lexicographic by raw pubkey bytes.
+   */
+  canonicalizeMultisigPubkeys(multisigPubkeys) {
+    if (!multisigPubkeys) {
+      throw new Error(
+        "multisigPubkeys is required for Solana multisig transactions"
+      );
+    }
+    if (multisigPubkeys.length < 2 || multisigPubkeys.length > MAX_MULTISIG_SIGNERS) {
+      throw new Error(
+        `Invalid multisig signer count: expected 2-${MAX_MULTISIG_SIGNERS} signers, got ${multisigPubkeys.length}`
+      );
+    }
+    const seenPubkeys = /* @__PURE__ */ new Set();
+    for (const pubkey of multisigPubkeys) {
+      if (pubkey.length !== PUBKEY_SIZE) {
+        throw new Error(
+          `Invalid public key length: expected ${PUBKEY_SIZE} bytes, got ${pubkey.length}`
+        );
+      }
+      const pubkeyHex = bytesToHex3(pubkey);
+      if (seenPubkeys.has(pubkeyHex)) {
+        throw new Error(`Duplicate multisig public key provided: ${pubkeyHex}`);
+      }
+      seenPubkeys.add(pubkeyHex);
+    }
+    return [...multisigPubkeys].sort(compareByteArrays);
+  }
   /**
    * Helper to create and serialize a SolanaOffchainUnsignedTransaction to JSON bytes.
    */
@@ -564,12 +636,15 @@ var SolanaSignableRollup = class {
     const jsonBytes = await this.createSolanaJsonBytes(unsignedTx);
     const pubkey = await signer.publicKey();
     const chainHash = await this.inner.chainHash();
-    const preamble = createSolanaPreamble(pubkey, chainHash, jsonBytes.length);
-    const signedMessageWithPreamble = new Uint8Array(
-      preamble.length + jsonBytes.length
+    const preamble = createSolanaPreamble(
+      [pubkey],
+      chainHash,
+      jsonBytes.length
+    );
+    const signedMessageWithPreamble = this.combinePreambleAndMessage(
+      preamble,
+      jsonBytes
     );
-    signedMessageWithPreamble.set(preamble, 0);
-    signedMessageWithPreamble.set(jsonBytes, preamble.length);
     const signature = await signer.sign(signedMessageWithPreamble);
     const solanaMessage = {
       signed_message_with_preamble: signedMessageWithPreamble,
@@ -643,6 +718,235 @@ var SolanaSignableRollup = class {
         throw new Error(`Unsupported authenticator: ${authenticator}`);
     }
   }
+  /**
+   * Creates V1 JSON bytes for a multisig transaction, including multisig_id and version.
+   * The resulting JSON is what each signer signs directly (no discriminator prefix).
+   */
+  async createMultisigJsonBytes(unsignedTx, multisigAddress) {
+    const serializer = await this.inner.serializer();
+    const schema = serializer.schema;
+    const chainName = schema.chain_data.chain_name || "";
+    const solanaUnsignedTx = {
+      runtime_call: unsignedTx.runtime_call,
+      uniqueness: unsignedTx.uniqueness,
+      details: unsignedTx.details,
+      chain_name: chainName,
+      // Hardcoded to base58 encoding, only correct for rollups using Base58Address as their
+      // primary address type. Will be replaced with rollup-aware address formatting once the
+      // SDK supports flexible address encoding (see #2673).
+      multisig_id: bs58.encode(multisigAddress),
+      version: 1
+    };
+    return new TextEncoder().encode(JSON.stringify(solanaUnsignedTx));
+  }
+  /**
+   * Creates the preamble+JSON bytes signed by every signer in a spec-compliant multisig flow.
+   */
+  async createSpecCompliantMultisigSignedMessage(unsignedTx, multisigAddress, multisigPubkeys) {
+    const jsonBytes = await this.createMultisigJsonBytes(
+      unsignedTx,
+      multisigAddress
+    );
+    const chainHash = await this.inner.chainHash();
+    const preamble = createSolanaPreamble(
+      multisigPubkeys,
+      chainHash,
+      jsonBytes.length
+    );
+    return this.combinePreambleAndMessage(preamble, jsonBytes);
+  }
+  /**
+   * Signs an unsigned transaction using Solana offchain simple multisig signing.
+   */
+  async signForSolanaSimpleMultisig(unsignedTx, signer, multisigAddress, multisigPubkeys) {
+    const pubkey = await signer.publicKey();
+    const signerPubkeyHex = bytesToHex3(pubkey);
+    const multisigPubkeyHexes = multisigPubkeys.map(bytesToHex3);
+    if (!multisigPubkeyHexes.includes(signerPubkeyHex)) {
+      throw new Error(
+        `Signer public key ${signerPubkeyHex} is not present in multisigPubkeys`
+      );
+    }
+    const jsonBytes = await this.createMultisigJsonBytes(
+      unsignedTx,
+      multisigAddress
+    );
+    const signature = await signer.sign(jsonBytes);
+    return this.typeBuilder.transaction({
+      unsignedTx,
+      sender: pubkey,
+      signature,
+      rollup: this.inner
+    });
+  }
+  /**
+   * Signs an unsigned transaction using the spec-compliant multisig preamble.
+   */
+  async signForSolanaSpecMultisig(unsignedTx, signer, multisigAddress, multisigPubkeys) {
+    const pubkey = await signer.publicKey();
+    const signerPubkeyHex = bytesToHex3(pubkey);
+    const multisigPubkeyHexes = multisigPubkeys.map(bytesToHex3);
+    if (!multisigPubkeyHexes.includes(signerPubkeyHex)) {
+      throw new Error(
+        `Signer public key ${signerPubkeyHex} is not present in multisigPubkeys`
+      );
+    }
+    const signedMessageWithPreamble = await this.createSpecCompliantMultisigSignedMessage(
+      unsignedTx,
+      multisigAddress,
+      multisigPubkeys
+    );
+    const signature = await signer.sign(signedMessageWithPreamble);
+    return this.typeBuilder.transaction({
+      unsignedTx,
+      sender: pubkey,
+      signature,
+      rollup: this.inner
+    });
+  }
+  /**
+   * Signs an unsigned transaction for use in a Solana offchain multisig.
+   *
+   * `authenticator: "standard"` delegates directly to the wrapped standard rollup.
+   * `authenticator: "solanaSimple"` signs the V1 JSON payload directly.
+   * `authenticator: "solana"` signs the spec-compliant preamble+JSON bytes.
+   * Solana multisig authenticators treat `multisigPubkeys` as an unordered set and
+   * canonicalize it before signing.
+   */
+  async signTransactionForMultisig(unsignedTx, params) {
+    switch (params.authenticator) {
+      case "standard":
+        return this.inner.signTransaction(unsignedTx, params.signer);
+      case "solanaSimple":
+        return this.signForSolanaSimpleMultisig(
+          unsignedTx,
+          params.signer,
+          params.multisigAddress,
+          this.canonicalizeMultisigPubkeys(params.multisigPubkeys)
+        );
+      case "solana":
+        return this.signForSolanaSpecMultisig(
+          unsignedTx,
+          params.signer,
+          params.multisigAddress,
+          this.canonicalizeMultisigPubkeys(params.multisigPubkeys)
+        );
+    }
+  }
+  /**
+   * Builds a spec-compliant multisig envelope from a V1 transaction and ordered multisig pubkeys.
+   */
+  buildSpecCompliantMultisigEnvelope(tx, signedMessageWithPreamble, multisigPubkeys) {
+    const multisigPubkeyHexes = multisigPubkeys.map(bytesToHex3);
+    const indexByPubkey = /* @__PURE__ */ new Map();
+    multisigPubkeyHexes.forEach((pubkeyHex, index) => {
+      indexByPubkey.set(pubkeyHex, index);
+    });
+    const accountedPubkeys = /* @__PURE__ */ new Set();
+    const signaturesByIndex = /* @__PURE__ */ new Map();
+    let signerBitfield = 0;
+    for (const signer of tx.signatures) {
+      const signerIndex = indexByPubkey.get(signer.pub_key);
+      if (signerIndex === void 0) {
+        throw new Error(
+          `Signed pubkey ${signer.pub_key} is not present in multisigPubkeys`
+        );
+      }
+      if (accountedPubkeys.has(signer.pub_key)) {
+        throw new Error(
+          `Duplicate signed pubkey in multisig transaction: ${signer.pub_key}`
+        );
+      }
+      accountedPubkeys.add(signer.pub_key);
+      signaturesByIndex.set(signerIndex, hexToBytes2(signer.signature));
+      signerBitfield = (signerBitfield | 1 << signerIndex) >>> 0;
+    }
+    for (const unusedPubkey of tx.unused_pub_keys) {
+      if (!indexByPubkey.has(unusedPubkey)) {
+        throw new Error(
+          `Unused pubkey ${unusedPubkey} is not present in multisigPubkeys`
+        );
+      }
+      if (accountedPubkeys.has(unusedPubkey)) {
+        throw new Error(
+          `Duplicate pubkey in multisig transaction payload: ${unusedPubkey}`
+        );
+      }
+      accountedPubkeys.add(unusedPubkey);
+    }
+    if (accountedPubkeys.size !== multisigPubkeys.length) {
+      throw new Error(
+        "multisigPubkeys must contain every signer and unused pubkey exactly once"
+      );
+    }
+    const orderedSignatures = Array.from(signaturesByIndex.entries()).sort(([leftIndex], [rightIndex]) => leftIndex - rightIndex).map(([, signature]) => signature);
+    return {
+      signed_message_with_preamble: signedMessageWithPreamble,
+      signatures: orderedSignatures,
+      signer_bitfield: signerBitfield,
+      min_signers: tx.min_signers
+    };
+  }
+  /**
+   * Submits a multisig transaction using the Solana offchain simple multisig format.
+   *
+   * Accepts the V1 transaction produced by `MultisigTransaction.asTransaction()`.
+   * `authenticator: "standard"` delegates directly to the wrapped standard rollup.
+   * Solana authenticators rebuild the appropriate Solana multisig envelope and
+   * submit it to the Solana offchain endpoint.
+   */
+  async submitMultisigTransaction(multisigTx, params) {
+    const { V1: tx } = multisigTx;
+    const unsignedTx = {
+      runtime_call: tx.runtime_call,
+      uniqueness: tx.uniqueness,
+      details: tx.details
+    };
+    switch (params.authenticator) {
+      case "standard":
+        return this.inner.submitTransaction(
+          multisigTx
+        );
+      case "solanaSimple": {
+        this.canonicalizeMultisigPubkeys(params.multisigPubkeys);
+        const jsonBytes = await this.createMultisigJsonBytes(
+          unsignedTx,
+          params.multisigAddress
+        );
+        const wireBytes = new Uint8Array(1 + jsonBytes.length);
+        wireBytes[0] = MULTISIG_SIMPLE_DISCRIMINATOR;
+        wireBytes.set(jsonBytes, 1);
+        const chainHash = await this.inner.chainHash();
+        const serialized = this.serializeSolanaMultisigMessage({
+          wire_bytes: wireBytes,
+          chain_hash: chainHash,
+          signatures: tx.signatures.map((s) => ({
+            signature: hexToBytes2(s.signature),
+            pub_key: hexToBytes2(s.pub_key)
+          })),
+          unused_pub_keys: tx.unused_pub_keys.map((pk) => hexToBytes2(pk)),
+          min_signers: tx.min_signers
+        });
+        return this.submitSerializedMessage(serialized);
+      }
+      case "solana": {
+        const multisigPubkeys = this.canonicalizeMultisigPubkeys(
+          params.multisigPubkeys
+        );
+        const signedMessageWithPreamble = await this.createSpecCompliantMultisigSignedMessage(
+          unsignedTx,
+          params.multisigAddress,
+          multisigPubkeys
+        );
+        const message = this.buildSpecCompliantMultisigEnvelope(
+          tx,
+          signedMessageWithPreamble,
+          multisigPubkeys
+        );
+        return this.submitSolanaSpecMultisigMessage(message);
+      }
+    }
+  }
   /**
    * Submits a transaction with the specified authenticator.
    *
@@ -682,6 +986,13 @@ var SolanaSignableRollup = class {
   async chainHash() {
     return this.inner.chainHash();
   }
+  /**
+   * Pre-fetches the rollup schema, populating the serializer and chain hash caches.
+   * Call this during initialization to avoid the latency of lazy-loading on the first transaction.
+   */
+  hydrate() {
+    return this.inner.hydrate();
+  }
   async healthcheck(timeout) {
     return this.inner.healthcheck(timeout);
   }
@@ -757,6 +1068,102 @@ var SolanaSignableRollup = class {
     buffer.set(message.signature, offset);
     return buffer;
   }
+  /**
+   * Serializes a SolanaOffchainSimpleMultisigMessage using borsh encoding.
+   * Layout matches the Rust struct:
+   *   [u32 LE: wire_bytes.len][wire_bytes]
+   *   [32 bytes: chain_hash]
+   *   [u32 LE: signatures.len]
+   *     for each: [64 bytes: signature][32 bytes: pub_key]
+   *   [u32 LE: unused_pub_keys.len]
+   *     for each: [32 bytes: pub_key]
+   *   [u8: min_signers]
+   */
+  serializeSolanaMultisigMessage(message) {
+    if (message.chain_hash.length !== CHAIN_HASH_SIZE) {
+      throw new Error(
+        `Invalid chain hash length: expected ${CHAIN_HASH_SIZE} bytes, got ${message.chain_hash.length}`
+      );
+    }
+    const sigCount = message.signatures.length;
+    const unusedCount = message.unused_pub_keys.length;
+    const totalSize = VEC_LENGTH_PREFIX_SIZE + message.wire_bytes.length + CHAIN_HASH_SIZE + VEC_LENGTH_PREFIX_SIZE + sigCount * (SIGNATURE_SIZE + PUBKEY_SIZE) + VEC_LENGTH_PREFIX_SIZE + unusedCount * PUBKEY_SIZE + 1;
+    const buffer = new Uint8Array(totalSize);
+    const view = new DataView(buffer.buffer);
+    let offset = 0;
+    view.setUint32(offset, message.wire_bytes.length, true);
+    offset += VEC_LENGTH_PREFIX_SIZE;
+    buffer.set(message.wire_bytes, offset);
+    offset += message.wire_bytes.length;
+    buffer.set(message.chain_hash, offset);
+    offset += CHAIN_HASH_SIZE;
+    view.setUint32(offset, sigCount, true);
+    offset += VEC_LENGTH_PREFIX_SIZE;
+    for (const sig of message.signatures) {
+      if (sig.signature.length !== SIGNATURE_SIZE) {
+        throw new Error(
+          `Invalid signature length: expected ${SIGNATURE_SIZE} bytes, got ${sig.signature.length}`
+        );
+      }
+      if (sig.pub_key.length !== PUBKEY_SIZE) {
+        throw new Error(
+          `Invalid public key length: expected ${PUBKEY_SIZE} bytes, got ${sig.pub_key.length}`
+        );
+      }
+      buffer.set(sig.signature, offset);
+      offset += SIGNATURE_SIZE;
+      buffer.set(sig.pub_key, offset);
+      offset += PUBKEY_SIZE;
+    }
+    view.setUint32(offset, unusedCount, true);
+    offset += VEC_LENGTH_PREFIX_SIZE;
+    for (const pk of message.unused_pub_keys) {
+      if (pk.length !== PUBKEY_SIZE) {
+        throw new Error(
+          `Invalid public key length: expected ${PUBKEY_SIZE} bytes, got ${pk.length}`
+        );
+      }
+      buffer.set(pk, offset);
+      offset += PUBKEY_SIZE;
+    }
+    buffer[offset] = message.min_signers;
+    return buffer;
+  }
+  /**
+   * Serializes a SolanaOffchainSpecCompliantMultisigMessage using borsh encoding.
+   * Layout matches the Rust struct:
+   *   [u32 LE: signed_message_with_preamble.len][signed_message_with_preamble]
+   *   [u32 LE: signatures.len]
+   *     for each: [64 bytes: signature]
+   *   [u32 LE: signer_bitfield]
+   *   [u8: min_signers]
+   */
+  serializeSolanaSpecMultisigMessage(message) {
+    const sigCount = message.signatures.length;
+    const totalSize = VEC_LENGTH_PREFIX_SIZE + message.signed_message_with_preamble.length + VEC_LENGTH_PREFIX_SIZE + sigCount * SIGNATURE_SIZE + 4 + 1;
+    const buffer = new Uint8Array(totalSize);
+    const view = new DataView(buffer.buffer);
+    let offset = 0;
+    view.setUint32(offset, message.signed_message_with_preamble.length, true);
+    offset += VEC_LENGTH_PREFIX_SIZE;
+    buffer.set(message.signed_message_with_preamble, offset);
+    offset += message.signed_message_with_preamble.length;
+    view.setUint32(offset, sigCount, true);
+    offset += VEC_LENGTH_PREFIX_SIZE;
+    for (const signature of message.signatures) {
+      if (signature.length !== SIGNATURE_SIZE) {
+        throw new Error(
+          `Invalid signature length: expected ${SIGNATURE_SIZE} bytes, got ${signature.length}`
+        );
+      }
+      buffer.set(signature, offset);
+      offset += SIGNATURE_SIZE;
+    }
+    view.setUint32(offset, message.signer_bitfield >>> 0, true);
+    offset += 4;
+    buffer[offset] = message.min_signers;
+    return buffer;
+  }
 };
 async function createSolanaSignableRollup(rollupConfig, solanaEndpoint = "/sequencer/accept-solana-offchain-tx") {
   const standardRollup = await createStandardRollup(rollupConfig);
@@ -776,7 +1183,6 @@ export {
   StandardRollup,
   VersionMismatchError,
   addressFromPublicKey,
-  createSolanaPreamble,
   createSolanaSignableRollup,
   createStandardRollup,
   standardTypeBuilder