@blossm/contract-addresses-trusted-forwarder 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Blossm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# @blossm/contract-addresses-trusted-forwarder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Static Juicebox V6 `ERC2771Forwarder` deployment lookup. Source records are
+pinned to `Bananapus/deploy-all-v6` commit
+`c62b3ac81bfc5603b6771e8ad801eb2236022947`. Lookup performs no network requests.
+
+```js
+import contracts from "@blossm/contract-addresses-trusted-forwarder";
+
+const address = contracts.erc2771ForwarderContract(1);
+```
+
+## erc2771ForwarderContract(chainId)
+
+Accepts a positive safe-integer JavaScript number from the supported-chain
+table. Returns the lowercase V6 address string. Numeric strings, arrays,
+objects, fractions, zero and other invalid values are rejected without coercion.
+
+Invalid input throws the shared `@blossm/errors` internal-server error with
+`chainId must be a positive safe integer`. Unsupported numeric IDs throw the
+same error type with `Unsupported chainId: <id>`. These report unsupported
+configuration; no fallback address is selected. Only own table entries count.
+
+## Supported V6 deployment records
+
+All eight records point to `0x3ba60b60933916a7c87d0860dcee62a0ce34e3e2`.
+Polygon is not supported by this pinned table.
+
+| Chain            |       ID | Deployment directory | Artifact SHA256                                                    |
+| ---------------- | -------: | -------------------- | ------------------------------------------------------------------ |
+| Ethereum         |        1 | `ethereum`           | `fe4b86b2945907e5e8e467c894e1dc5653a116a51a4c561bd536c2e5bc47d1c8` |
+| Optimism         |       10 | `optimism`           | `22b2afda37e1e21fd37ab00e12cc6512d824d083ca193dd30a207378e83e988d` |
+| Base             |     8453 | `base`               | `2d445573481b9afa3555e6e5fa12dea53fad7a7283f5acb742c97274c0f352fd` |
+| Arbitrum         |    42161 | `arbitrum`           | `5e466bce4fc88915038ec59c0136d9764aa627755d2fa14a995900ef51cb0f95` |
+| Ethereum Sepolia | 11155111 | `sepolia`            | `4acf67e1b2fd496fcdfe0af8ad351e9f10449714617b26055cfa56f9a04b7991` |
+| Base Sepolia     |    84532 | `base_sepolia`       | `cec05b9232236b937fd5715372517c32f97f11cefdd6c685e52100aff7684b14` |
+| Optimism Sepolia | 11155420 | `optimism_sepolia`   | `b26a655cb20d7c111568b84b19d5f3d551d20fe21754f2d11a1667a112482268` |
+| Arbitrum Sepolia |   421614 | `arbitrum_sepolia`   | `cf7a8d6da3a7a5c79d5a460ca6c9895ac72081921c3d0b81ff6720aab80351fa` |
+
+This lookup explicitly selects the Juicebox V6 deployment family. It does not
+fall back to historical V4/V5 forwarders, discover arbitrary ERC-2771
+contracts, verify an RPC endpoint's chain, or prove that a target trusts the
+forwarder. Callers own those checks and the contract's EIP-712 domain/signing
+configuration. The pinned artifacts record constructor name `Juicebox`;
+callers must verify the actual signing domain instead of assuming an app name.
+
+## Provenance
+
+- Repository: `Bananapus/deploy-all-v6`.
+- [Pinned deployment-source revision](https://github.com/Bananapus/deploy-all-v6/tree/c62b3ac81bfc5603b6771e8ad801eb2236022947).
+- [Ethereum deployment artifact](https://github.com/Bananapus/deploy-all-v6/blob/c62b3ac81bfc5603b6771e8ad801eb2236022947/deployments/ethereum/ERC2771Forwarder.json).
+- Artifact paths: `deployments/<directory>/ERC2771Forwarder.json`, with directory/hash pairs above.
+- Sorted `[chainId, lowercaseAddress]` projection SHA256: `2529ebbf4c7a7855d1d91e210fa75630ba451aa0185790d54cd17e2778703932`.
+
+Verified 2026-10-22 from the local deployment repository: all eight artifact
+bytes match the pinned commit, chain IDs match the table, and each recorded
+receipt has successful status. All eight artifact ABIs match the retained
+`@blossm/contract-abis-trusted-forwarder` interface. The old WIP selected V5;
+the user explicitly selected V6 before this package was committed.
+
+No fresh chain RPC, canonical receipt or deployed-bytecode check was performed.
+The successful receipts are committed source evidence, not a live-state claim.
+These artifact hashes and source revision allow the data comparison to be
+repeated from another checkout without access to this machine's paths.
+
+The address checksum hashes JSON-serialized pairs sorted numerically by chain
+ID. An update needs reviewed V6 deployment records and a deliberate update of
+the table, provenance and test checksum. Normal tests are offline.
+
+## Dependencies and tests
+
+Runtime dependency: `@blossm/errors`, provided through `deps.js` in the standard
+Toolbox pattern. Package-local tests use Mocha/Chai and Node's built-in crypto;
+no mocks or additional runtime dependencies are required.
+
+From this directory with workspace dependencies installed:
+
+```sh
+node ../../../../../node_modules/mocha/bin/mocha.js --recursive
+```
+
+Tests pin all eight returned V6 addresses to the source-derived checksum and
+cover malformed/coercing inputs, unsupported chains, shared error semantics
+and inherited numeric properties.

package/deps.js

@@ -0,0 +1,5 @@
+import { internalServer } from "@blossm/errors";
+
+export default {
+  internalServer,
+};

package/index.js

@@ -0,0 +1,31 @@
+import deps from "./deps.js";
+
+// Juicebox V6 deployments, pinned to deploy-all-v6 in README.md.
+const erc2771ForwarderContract = (chainId) => {
+  if (!Number.isSafeInteger(chainId) || chainId <= 0) {
+    throw deps.internalServer.message(
+      "chainId must be a positive safe integer"
+    );
+  }
+
+  const forwarders = {
+    1: "0x3ba60b60933916a7c87d0860dcee62a0ce34e3e2", // Ethereum Mainnet
+    10: "0x3ba60b60933916a7c87d0860dcee62a0ce34e3e2", // Optimism
+    8453: "0x3ba60b60933916a7c87d0860dcee62a0ce34e3e2", // Base
+    42161: "0x3ba60b60933916a7c87d0860dcee62a0ce34e3e2", // Arbitrum
+    11155111: "0x3ba60b60933916a7c87d0860dcee62a0ce34e3e2", // Ethereum Sepolia
+    84532: "0x3ba60b60933916a7c87d0860dcee62a0ce34e3e2", // Base Sepolia
+    11155420: "0x3ba60b60933916a7c87d0860dcee62a0ce34e3e2", // Optimism Sepolia
+    421614: "0x3ba60b60933916a7c87d0860dcee62a0ce34e3e2", // Arbitrum Sepolia
+  };
+
+  if (!Object.hasOwn(forwarders, chainId)) {
+    throw deps.internalServer.message(`Unsupported chainId: ${chainId}`);
+  }
+
+  return forwarders[chainId];
+};
+
+export default {
+  erc2771ForwarderContract,
+};

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@blossm/contract-addresses-trusted-forwarder",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Pinned Juicebox V6 ERC2771Forwarder deployment addresses",
+  "main": "index.js",
+  "type": "module",
+  "author": "blossm.network",
+  "engines": {
+    "node": ">= 20.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "mocha --recursive"
+  },
+  "dependencies": {
+    "@blossm/errors": "*"
+  },
+  "devDependencies": {
+    "mocha": "^11.7.0",
+    "chai": "^5.2.0"
+  }
+}

package/test/index.js

@@ -0,0 +1,84 @@
+import { expect } from "chai";
+import { createHash } from "crypto";
+
+import contracts from "../index.js";
+
+const { erc2771ForwarderContract } = contracts;
+
+describe("Juicebox V6 forwarder addresses", () => {
+  it("should match the pinned V6 deployment's eight chain/address records", () => {
+    const chainIds = [1, 10, 8453, 42161, 84532, 421614, 11155111, 11155420];
+    const records = chainIds.map((chainId) => [
+      chainId,
+      erc2771ForwarderContract(chainId),
+    ]);
+
+    for (const [, address] of records) {
+      expect(address).to.match(/^0x[0-9a-f]{40}$/);
+    }
+
+    // Hash of source-derived, numerically sorted [chainId, lowercaseAddress] pairs.
+    const hash = createHash("sha256")
+      .update(JSON.stringify(records))
+      .digest("hex");
+    expect(hash).to.equal(
+      "2529ebbf4c7a7855d1d91e210fa75630ba451aa0185790d54cd17e2778703932"
+    );
+  });
+
+  it("should reject malformed chain IDs without coercing them", () => {
+    for (const chainId of [
+      undefined,
+      null,
+      "1",
+      "toString",
+      "constructor",
+      "__proto__",
+      [1],
+      {},
+      { valueOf: () => 1 },
+      { toString: () => "1" },
+      Symbol("chain"),
+      true,
+      false,
+      0,
+      -1,
+      1.5,
+      NaN,
+      Infinity,
+      Number.MAX_SAFE_INTEGER + 1,
+    ]) {
+      expect(() => erc2771ForwarderContract(chainId))
+        .to.throw("chainId must be a positive safe integer")
+        .with.property("statusCode", 500);
+    }
+  });
+
+  it("should reject unsupported numeric chain IDs with the shared error", () => {
+    for (const chainId of [137, 999, Number.MAX_SAFE_INTEGER]) {
+      expect(() => erc2771ForwarderContract(chainId))
+        .to.throw(`Unsupported chainId: ${chainId}`)
+        .with.property("statusCode", 500);
+    }
+  });
+
+  it("should reject numeric entries inherited from Object.prototype", () => {
+    const previous = Object.getOwnPropertyDescriptor(Object.prototype, "999");
+    Object.defineProperty(Object.prototype, "999", {
+      value: "0x1111111111111111111111111111111111111111",
+      configurable: true,
+    });
+
+    try {
+      expect(() => erc2771ForwarderContract(999))
+        .to.throw("Unsupported chainId: 999")
+        .with.property("statusCode", 500);
+    } finally {
+      if (previous) {
+        Object.defineProperty(Object.prototype, "999", previous);
+      } else {
+        delete Object.prototype[999];
+      }
+    }
+  });
+});