@effectstream/precompile 0.100.14 → 0.100.16

package/README.md

@@ -0,0 +1,63 @@
+# @effectstream/precompile
+
+Generate deterministic EVM-sized (20-byte) addresses from string names
+by hashing with keccak256. The intended use is "precompile" addresses —
+synthetic 0x-addresses reserved by an EffectStream node for non-user
+logic (intrinsic primitives, timers, internal accounts).
+
+- Deterministic 20-byte addresses from string names via keccak256.
+- Pure functions; same name in, same address out.
+- Used by intrinsic primitives, timers, and internal accounts.
+- Result is an EVM-shaped `0x[40 hex chars]` string, usable wherever viem/ethers expects an `Address`.
+
+## Install
+
+```bash
+bun add @effectstream/precompile
+# or
+npm install @effectstream/precompile
+```
+
+## Standalone usage
+
+Pure functions. Given a name, get an address. Same name, same address —
+always.
+
+```typescript
+import { generatePrecompile, generatePrecompiles } from "@effectstream/precompile";
+
+const addr = generatePrecompile("MY_FEATURE");
+// addr === "0x<first-20-bytes-of-keccak256-of-MY_FEATURE>"
+
+// Bulk-derive a typed map from a string enum.
+enum MyNames {
+  A = "feature-a",
+  B = "feature-b",
+}
+const map = generatePrecompiles(MyNames);
+// map["feature-a"] === generatePrecompile("feature-a")
+// map["feature-b"] === generatePrecompile("feature-b")
+```
+
+The result is an EVM-shaped `0x[40 hex chars]` string, usable wherever
+viem/ethers expects an `Address`.
+
+## Inside EffectStream
+
+Exported through `@effectstream/node-sdk/precompile`. Names are stable
+across versions, so an address generated today matches one generated by
+a future build of the same name.
+
+## Key exports
+
+- `generatePrecompile(name: string): HexString0x` — `0x` + first 40 hex chars of `keccak256(name)`.
+- `generatePrecompiles(names: Record<string, string>)` — bulk variant. Returns `{ [value]: address }`.
+
+## Examples
+
+Runnable: [`test/examples.test.ts`](./test/examples.test.ts).
+
+## Links
+
+- Docs: https://effectstream.github.io/docs/packages/sdk/precompile
+- Source: https://github.com/effectstream/effectstream/tree/main/packages/effectstream-sdk/precompile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/precompile",
-  "version": "0.100.14",
+  "version": "0.100.16",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {

package/test/examples.test.ts

@@ -0,0 +1,34 @@
+// Examples for the README.
+
+import { test, expect } from "bun:test";
+import { generatePrecompile, generatePrecompiles } from "../src/mod.ts";
+
+test("README: generatePrecompile returns a 0x-prefixed 40-hex-char address", () => {
+  const addr = generatePrecompile("MY_FEATURE");
+  expect(addr).toMatch(/^0x[0-9a-f]{40}$/);
+});
+
+test("README: same name always produces the same address", () => {
+  expect(generatePrecompile("MY_FEATURE")).toBe(
+    generatePrecompile("MY_FEATURE"),
+  );
+});
+
+test("README: different names produce different addresses", () => {
+  expect(generatePrecompile("a")).not.toBe(generatePrecompile("b"));
+});
+
+test("README: generatePrecompiles bulk-derives a typed map from a string enum", () => {
+  enum MyNames {
+    A = "feature-a",
+    B = "feature-b",
+  }
+  const map = generatePrecompiles(MyNames);
+  expect(map["feature-a"]).toBe(generatePrecompile("feature-a"));
+  expect(map["feature-b"]).toBe(generatePrecompile("feature-b"));
+});
+
+test("README: empty enum produces empty map (no throw)", () => {
+  const map = generatePrecompiles({} as Record<string, string>);
+  expect(Object.keys(map).length).toBe(0);
+});