Derive counterfactual Starknet stealth addresses

Add computeStarknetStealthAccount to stealth-chain-starknet: the CSAP
Starknet stealth address is the deploy-account address of the pinned
StealthAccount class whose signer is the one-time P_stealth. Salt is
sn_keccak(R) over the ephemeral key, so sender and recipient derive the
same address from the announcement; per-payment unlinkability holds for
any salt because P_stealth is itself the constructor calldata. Pedersen
comes from @scure/starknet; the formula and the [x.low, x.high, y.low,
y.high] calldata layout are cross-validated against starknet.js and the
on-chain account Serde.

Author: collinsadi

CHANGELOG.md

@@ -31,6 +31,13 @@ All notable changes to the Opaque SDK packages.
   `{ ethereum, solana }` shape, so a new scan chain can't break the type.
 
 ### Added
+- **`@opaquecash/stealth-chain-starknet` — counterfactual stealth address
+  derivation.** `computeStarknetStealthAccount(pStealthUncompressed,
+  ephemeralPubKey)` returns the CSAP Starknet stealth address (the
+  deploy-account address of the pinned `StealthAccount` class), its salt
+  (`sn_keccak(R)`), and the `[x.low, x.high, y.low, y.high]` constructor
+  calldata. Pedersen from `@scure/starknet`; the formula and calldata layout
+  are cross-validated against `starknet.js` and the on-chain account Serde.
 - **`@opaquecash/stealth-chain-starknet` 0.1.0 (new package).** Starknet
   `ChainAdapter` (Opaque-assigned chain id `0x534e` "SN"): announcement
   fetching via `starknet_getEvents` with a Cairo `ByteArray` codec and

package-lock.json

@@ -20,7 +20,8 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.5.0",
-    "@opaquecash/adapter": "0.2.0"
+    "@opaquecash/adapter": "0.2.0",
+    "@scure/starknet": "^2.2.0"
   },
   "sideEffects": false,
   "license": "Apache-2.0",

packages/stealth-chain-starknet/package.json

@@ -0,0 +1,119 @@
+import { pedersen } from "@scure/starknet";
+import { starknetKeccak } from "./bytearray.js";
+import { STARKNET_SEPOLIA } from "./deployment.js";
+
+function asBigInt(hexOrValue: string): bigint {
+  return BigInt(hexOrValue.startsWith("0x") ? hexOrValue : `0x${hexOrValue}`);
+}
+
+/**
+ * Starknet's array-hash `H(...H(H(0, a0), a1)..., n)` over Pedersen, as used
+ * for contract-address computation and constructor-calldata hashing.
+ */
+function pedersenOnElements(data: bigint[]): bigint {
+  let acc = 0n;
+  for (const x of data) acc = asBigInt(pedersen(acc, x));
+  return asBigInt(pedersen(acc, BigInt(data.length)));
+}
+
+/**
+ * Counterfactual Starknet stealth address derivation (CSAP custody,
+ * spec/starknet-integration.md §7.1).
+ *
+ * The address is the deploy-account address of the pinned `StealthAccount`
+ * class whose sole signer is the one-time secp256k1 key `P_stealth`. Because
+ * the constructor calldata IS `P_stealth` — fresh per payment via CSAP's
+ * per-payment ephemeral key — the address is unlinkable across payments
+ * regardless of salt. The salt is nonetheless derived deterministically from
+ * the announced ephemeral key so the sender (computing where to pay) and the
+ * recipient (deploying to spend) arrive at the identical address from public
+ * data alone.
+ */
+
+// felt("STARKNET_CONTRACT_ADDRESS") — the address-hash domain prefix.
+const CONTRACT_ADDRESS_PREFIX =
+  0x535441524b4e45545f434f4e54524143545f41444452455353n;
+// Starknet addresses live in [0, 2^251 - 256).
+const L2_ADDRESS_UPPER_BOUND = 2n ** 251n - 256n;
+
+const U128_MASK = (1n << 128n) - 1n;
+
+function bytesToBigInt(bytes: Uint8Array): bigint {
+  let v = 0n;
+  for (const b of bytes) v = (v << 8n) | BigInt(b);
+  return v;
+}
+
+/**
+ * Serialise a secp256k1 point as the Cairo `Secp256k1Point` (EthPublicKey)
+ * constructor calldata: `[x.low, x.high, y.low, y.high]` (each `u256` as
+ * little-endian 128-bit limbs).
+ */
+export function ethPublicKeyCalldata(uncompressedPubKey: Uint8Array): bigint[] {
+  if (uncompressedPubKey.length !== 65 || uncompressedPubKey[0] !== 0x04) {
+    throw new Error("Expected a 65-byte uncompressed secp256k1 public key (0x04 ‖ x ‖ y)");
+  }
+  const x = bytesToBigInt(uncompressedPubKey.subarray(1, 33));
+  const y = bytesToBigInt(uncompressedPubKey.subarray(33, 65));
+  return [x & U128_MASK, x >> 128n, y & U128_MASK, y >> 128n];
+}
+
+/**
+ * The per-payment salt: `sn_keccak(ephemeral_pubkey)`. Derivable by anyone
+ * from the announcement, so sender and recipient agree without interaction.
+ */
+export function stealthAccountSalt(ephemeralPubKey: Uint8Array): bigint {
+  if (ephemeralPubKey.length !== 33) {
+    throw new Error("Ephemeral public key must be 33 bytes (compressed secp256k1)");
+  }
+  let hex = "";
+  for (const b of ephemeralPubKey) hex += b.toString(16).padStart(2, "0");
+  return starknetKeccak(hex);
+}
+
+export interface StarknetStealthAccount {
+  /** The counterfactual account address, `0x`-hex felt. */
+  address: `0x${string}`;
+  /** The salt used (a function of the ephemeral key). */
+  salt: bigint;
+  /** Constructor calldata: `P_stealth` as `[x.low, x.high, y.low, y.high]`. */
+  constructorCalldata: bigint[];
+  /** The account class the address is a counterfactual deployment of. */
+  classHash: `0x${string}`;
+}
+
+/**
+ * Compute the Starknet stealth account for a payment.
+ *
+ * @param stealthPubKeyUncompressed - `P_stealth` (65-byte uncompressed
+ *   secp256k1), from `prepareStealthSend(...).stealthPubKey`.
+ * @param ephemeralPubKey - the 33-byte compressed ephemeral key `R` from the
+ *   same send (drives the salt).
+ * @param classHash - the pinned `StealthAccount` class hash (defaults to the
+ *   Sepolia deployment).
+ */
+export function computeStarknetStealthAccount(
+  stealthPubKeyUncompressed: Uint8Array,
+  ephemeralPubKey: Uint8Array,
+  classHash: string = STARKNET_SEPOLIA.stealthAccountClassHash,
+): StarknetStealthAccount {
+  const constructorCalldata = ethPublicKeyCalldata(stealthPubKeyUncompressed);
+  const salt = stealthAccountSalt(ephemeralPubKey);
+  const classHashFelt = BigInt(classHash);
+
+  const address =
+    pedersenOnElements([
+      CONTRACT_ADDRESS_PREFIX,
+      0n, // deployer address: 0 for a self-deploying (deploy_account) account
+      salt,
+      classHashFelt,
+      pedersenOnElements(constructorCalldata),
+    ]) % L2_ADDRESS_UPPER_BOUND;
+
+  return {
+    address: `0x${address.toString(16)}`,
+    salt,
+    constructorCalldata,
+    classHash: `0x${classHashFelt.toString(16)}`,
+  };
+}

packages/stealth-chain-starknet/src/address.ts

@@ -5,6 +5,12 @@ export {
   starknetKeccak,
   toFeltHex,
 } from "./bytearray.js";
+export {
+  computeStarknetStealthAccount,
+  ethPublicKeyCalldata,
+  stealthAccountSalt,
+  type StarknetStealthAccount,
+} from "./address.js";
 export {
   buildAnnounceCall,
   buildRegisterKeysCall,

packages/stealth-chain-starknet/src/index.ts

@@ -0,0 +1,75 @@
+/**
+ * Counterfactual Starknet stealth address derivation.
+ *
+ * The golden address below was cross-validated three ways for CSAP canonical
+ * vector 1's one-time key (`0x9d1fcbe…1e2e`):
+ *   1. `starknet.js` `hash.calculateContractAddressFromHash` — the ecosystem
+ *      reference used by every wallet — produced the identical address.
+ *   2. `starknet.js` `EthSigner.getPubKey()` produced the identical (x, y),
+ *      confirming the `[x.low, x.high, y.low, y.high]` constructor calldata.
+ *   3. The on-chain `StealthAccount` Serde round-trips that same layout
+ *      (starknet repo `test_account_reports_its_stealth_public_key`).
+ * The computation here is dependency-light (Pedersen from `@scure/starknet`).
+ */
+import { describe, expect, it } from "vitest";
+import { secp256k1 } from "@noble/curves/secp256k1";
+import {
+  computeStarknetStealthAccount,
+  ethPublicKeyCalldata,
+  STARKNET_SEPOLIA,
+  stealthAccountSalt,
+} from "@opaquecash/stealth-chain-starknet";
+
+const ONE_TIME_KEY =
+  0x9d1fcbe17267729a88091556cadd19b3c11e33029883163d1d7118bc21a61e2en;
+const EPHEMERAL = Uint8Array.from(
+  Buffer.from(
+    "02b95c249d84f417e3e395a127425428b540671cc15881eb828c17b722a53fc599",
+    "hex",
+  ),
+);
+
+function pStealthUncompressed(): Uint8Array {
+  return secp256k1.getPublicKey(ONE_TIME_KEY, false);
+}
+
+describe("computeStarknetStealthAccount", () => {
+  it("matches the starknet.js-validated golden address", () => {
+    const acct = computeStarknetStealthAccount(pStealthUncompressed(), EPHEMERAL);
+    expect(acct.address).toBe(
+      "0x5c12134bc82dc4cf9f56ae036a0ba5ec85948c73304a3a6c1e08aa11e806ca2",
+    );
+    expect(acct.classHash).toBe(
+      `0x${BigInt(STARKNET_SEPOLIA.stealthAccountClassHash).toString(16)}`,
+    );
+  });
+
+  it("lays out the constructor calldata as [x.low, x.high, y.low, y.high]", () => {
+    // The (x, y) starknet.js EthSigner derives for this key.
+    const x =
+      0xdce27b82cd1ed4232b569e14121f4825a2ef189d14807d43c8d093fa8354f61bn;
+    const y =
+      0xbe8434ee5844371e291dcd5d93c072ea6e6f3eeab87a5bf42b3c08c52b66f2bcn;
+    const mask = (1n << 128n) - 1n;
+    expect(ethPublicKeyCalldata(pStealthUncompressed())).toEqual([
+      x & mask,
+      x >> 128n,
+      y & mask,
+      y >> 128n,
+    ]);
+  });
+
+  it("derives the salt from the ephemeral key (announcement-derivable)", () => {
+    const acct = computeStarknetStealthAccount(pStealthUncompressed(), EPHEMERAL);
+    expect(acct.salt).toBe(stealthAccountSalt(EPHEMERAL));
+    // A different ephemeral key gives a different salt (and address).
+    const other = Uint8Array.from(EPHEMERAL);
+    other[1] ^= 0x01;
+    expect(stealthAccountSalt(other)).not.toBe(acct.salt);
+  });
+
+  it("rejects malformed inputs", () => {
+    expect(() => ethPublicKeyCalldata(new Uint8Array(64))).toThrow(/uncompressed/);
+    expect(() => stealthAccountSalt(new Uint8Array(32))).toThrow(/33 bytes/);
+  });
+});