algosdk 3.5.2 → 3.7.0-beta.1

package/src/ed25519-signer.ts

@@ -0,0 +1,125 @@
+import { Address } from './encoding/address.js';
+import { encodeMsgpack } from './encoding/encoding.js';
+import {
+  MSIG_PROGRAM_TAG,
+  PROGRAM_TAG,
+  SIGN_PROGRAM_DATA_PREFIX,
+} from './logicsig.js';
+import { addressFromMultisigPreImg, pksFromAddresses } from './multisig.js';
+import { SignedTransaction } from './signedTransaction.js';
+import {
+  AddressWithDelegatedLsigSigner,
+  AddressWithMxBytesSigner,
+  AddressWithProgramDataSigner,
+  AddressWithTransactionSigner,
+  DelegatedLsigSigner,
+  MxBytesSigner,
+  ProgramDataSigner,
+  TransactionSigner,
+} from './signer.js';
+import { SIGN_BYTES_PREFIX } from './signing.js';
+import { Transaction } from './transaction.js';
+import {
+  EncodedMultisig,
+  EncodedSubsig,
+} from './types/transactions/encoded.js';
+import { arrayEqual, concatArrays } from './utils/utils.js';
+
+export interface Ed25519SigningKey {
+  ed25519PublicKey: Uint8Array;
+  ed25519Signer: (bytesToSign: Uint8Array) => Promise<Uint8Array>;
+}
+
+export function addressWithSignersFromRawEd25519Signer(
+  ed25519SigningKey: Ed25519SigningKey,
+  sendingAddress: Address = new Address(ed25519SigningKey.ed25519PublicKey)
+): AddressWithTransactionSigner &
+  AddressWithDelegatedLsigSigner &
+  AddressWithMxBytesSigner &
+  AddressWithProgramDataSigner {
+  const authAddress = new Address(ed25519SigningKey.ed25519PublicKey);
+  const { ed25519Signer: rawSigner } = ed25519SigningKey;
+
+  const txnSigner: TransactionSigner = async (
+    txnGroup: Transaction[],
+    indexesToSign: number[]
+  ) => {
+    const stxns: SignedTransaction[] = [];
+    for (const index of indexesToSign) {
+      const txn = txnGroup[index];
+      // eslint-disable-next-line no-await-in-loop
+      const sig = await rawSigner(txn.bytesToSign());
+      const stxn = new SignedTransaction({
+        txn,
+        sig,
+        sgnr: txn.sender.equals(authAddress) ? undefined : authAddress,
+      });
+
+      stxns.push(stxn);
+    }
+
+    return stxns.map((stxn) => encodeMsgpack(stxn));
+  };
+
+  const delegatedLsigSigner: DelegatedLsigSigner = async (lsig, msig) => {
+    if (msig) {
+      const pks = pksFromAddresses(msig.addrs);
+
+      const multisigAddr = addressFromMultisigPreImg({
+        version: msig.version,
+        threshold: msig.threshold,
+        pks,
+      });
+
+      const toBeSigned = concatArrays(
+        MSIG_PROGRAM_TAG,
+        multisigAddr.publicKey,
+        lsig.logic
+      );
+
+      const subsigs: EncodedSubsig[] = pks.map((pk) => ({ pk }));
+      const ourSubsig = subsigs.find((subsig) =>
+        arrayEqual(subsig.pk, authAddress.publicKey)
+      );
+      if (ourSubsig === undefined) {
+        throw Error(
+          `DelegatedLsigSigner could not find ${authAddress} as a signer in the multisig`
+        );
+      }
+
+      const sig = await rawSigner(toBeSigned);
+      ourSubsig.s = sig;
+      return {
+        address: authAddress,
+        lmsig: {
+          v: msig.version,
+          thr: msig.threshold,
+          subsig: subsigs,
+        } satisfies EncodedMultisig,
+      };
+    }
+
+    const toBeSigned = concatArrays(PROGRAM_TAG, lsig.logic);
+    const sig = await rawSigner(toBeSigned);
+    return { address: authAddress, sig };
+  };
+
+  const mxBytesSigner: MxBytesSigner = async (bytes: Uint8Array) => {
+    const bytesToSign = concatArrays(SIGN_BYTES_PREFIX, bytes);
+    return rawSigner(bytesToSign);
+  };
+
+  const programDataSigner: ProgramDataSigner = async (data, lsig) => {
+    const parts = concatArrays(lsig.address().publicKey, data);
+    const toBeSigned = concatArrays(SIGN_PROGRAM_DATA_PREFIX, parts);
+    return rawSigner(toBeSigned);
+  };
+
+  return {
+    address: sendingAddress,
+    programDataSigner,
+    txnSigner,
+    delegatedLsigSigner,
+    mxBytesSigner,
+  };
+}

package/src/encoding/address.ts

@@ -3,6 +3,10 @@ import * as nacl from '../nacl/naclWrappers.js';
 import * as utils from '../utils/utils.js';
 import { encodeUint64 } from './uint64.js';
 import { bytesToHex } from './binarydata.js';
+import { couldBeCurvePoint } from '../utils/ed25519-check.js';
+// Type-only: erased at runtime, so this does not create an import cycle with
+// types/transactions/encoded.ts, which imports this module transitively.
+import type { EncodedPQSig } from '../types/transactions/encoded.js';
 
 export const ALGORAND_ADDRESS_BYTE_LENGTH = 36;
 export const ALGORAND_CHECKSUM_BYTE_LENGTH = 4;
@@ -13,6 +17,23 @@ export const ALGORAND_ZERO_ADDRESS_STRING =
 export const MALFORMED_ADDRESS_ERROR_MSG = 'address seems to be malformed';
 export const CHECKSUM_ADDRESS_ERROR_MSG = 'wrong checksum for address';
 
+/**
+ * The domain-separation prefix prepended to a post-quantum address preimage
+ * before hashing. Matches go-algorand's protocol.PostQuantumAddress HashID.
+ */
+const PQ_ADDRESS_PREFIX = new TextEncoder().encode('PQA');
+
+/**
+ * The required byte length of a post-quantum signature scheme identifier.
+ */
+export const PQ_SCHEME_SIZE = 2;
+
+/**
+ * The largest value a post-quantum address salt may take. The salt occupies a
+ * single byte of the address preimage.
+ */
+export const PQ_SALT_MAX = 0xff;
+
 function checksumFromPublicKey(pk: Uint8Array): Uint8Array {
   return Uint8Array.from(
     nacl
@@ -178,3 +199,62 @@ export function getApplicationAddress(appID: number | bigint): Address {
   const hash = nacl.genericHash(toBeSigned);
   return new Address(Uint8Array.from(hash));
 }
+
+/**
+ * Derive a post-quantum (PQ) account address together with the canonical salt
+ * used to derive it.
+ *
+ * @param schemeBytes - The 2-byte ASCII PQ scheme identifier (e.g. "f1" for Falcon-1024).
+ * @param key - The scheme's canonical public key.
+ * @returns The derived Address and the canonical 1-byte salt.
+ */
+export function addressFromPQKey(
+  schemeBytes: Uint8Array,
+  key: Uint8Array
+): { address: Address; salt: number } {
+  if (schemeBytes.length !== PQ_SCHEME_SIZE)
+    throw new Error(
+      `invalid PQ scheme length: expected ${PQ_SCHEME_SIZE} bytes, got ${schemeBytes.length}`
+    );
+
+  // Rejection-sample the lowest salt that yields a PQ-compliant (non-Ed25519)
+  // address. The probability of exhausting the range is ~2^-256.
+  for (let salt = 0; salt <= PQ_SALT_MAX; salt++) {
+    const toBeHashed = utils.concatArrays(
+      PQ_ADDRESS_PREFIX,
+      schemeBytes,
+      Uint8Array.of(salt),
+      key
+    );
+    const publicKey = Uint8Array.from(nacl.genericHash(toBeHashed));
+    if (!couldBeCurvePoint(publicKey)) {
+      return { address: new Address(publicKey), salt };
+    }
+  }
+
+  throw new Error('no canonical salt exists for this PQ public key and scheme');
+}
+
+/**
+ * Derive the account address that a post-quantum signature authorizes.
+ *
+ * Unlike an Ed25519 signature, a PQ signature carries the scheme, salt and
+ * public key of the signing account, so the address it authorizes is fully
+ * determined by the signature and does not have to be supplied out of band.
+ *
+ * This also validates the signature's self-consistency: the salt must be the
+ * canonical one for the given scheme and public key, which is what the network
+ * requires.
+ *
+ * @param pqsig - The post-quantum signature to derive the address from.
+ * @returns The address of the account the signature authorizes.
+ */
+export function addressFromPQSig(pqsig: EncodedPQSig): Address {
+  const { address, salt } = addressFromPQKey(pqsig.sch, pqsig.pk);
+  if (salt !== pqsig.slt) {
+    throw new Error(
+      `invalid PQ signature salt: expected the canonical salt ${salt}, got ${pqsig.slt}`
+    );
+  }
+  return address;
+}

package/src/falcon-signer.ts

@@ -0,0 +1,30 @@
+import { Address } from './encoding/address.js';
+import {
+  AddressWithDelegatedLsigSigner,
+  AddressWithTransactionSigner,
+} from './signer.js';
+import { addressWithSignersFromRawPQSigner } from './pq-signer.js';
+
+/**
+ * The 2-byte ASCII identifier of the Falcon-1024 post-quantum signature scheme.
+ */
+export const FALCON_1024_SCHEME = new TextEncoder().encode('f1');
+
+export interface Falcon1024SigningKey {
+  falcon1024PublicKey: Uint8Array;
+  falcon1024Signer: (bytesToSign: Uint8Array) => Promise<Uint8Array>;
+}
+
+export function addressWithSignersFromRawFalcon1024Signer(
+  falconSigningKey: Falcon1024SigningKey,
+  sendingAddress?: Address
+): AddressWithTransactionSigner & AddressWithDelegatedLsigSigner {
+  return addressWithSignersFromRawPQSigner(
+    {
+      pqScheme: FALCON_1024_SCHEME,
+      pqPublicKey: falconSigningKey.falcon1024PublicKey,
+      pqSigner: falconSigningKey.falcon1024Signer,
+    },
+    sendingAddress
+  );
+}