@somnia-chain/contracts-sdk 0.2.0 → 0.3.0

package/README.md

@@ -28,8 +28,18 @@ tryAddress("hideki-testnet", "somnia-markets", "MarketsCore"); // Address | null
 
 contracts("somnia-mainnet", "somnia-markets"); // enumerate, for admin screens
 identify("somnia-mainnet", "0x1a47…");         // reverse lookup: project, name, kind
+
+allContracts();
+// every current deployment across every live network — the dashboard form.
+// Retired networks and superseded deployments are excluded by default, so a
+// wiped testnet's addresses cannot be rendered as current by forgetting to
+// filter: { includeRetiredNetworks, includeSuperseded, project } to widen it.
 ```
 
+Entries carry `address`, `kind`, `status`, `version`, and `contract` — the
+Solidity contract name, where a source stated one. `kind` and `status` are
+unions (`DeploymentKind`, `ContractStatus`), not `string`.
+
 Networks: `networks` (all, retired included), `network(slug)`,
 `liveNetworks()`, and `toChain(slug, { rpcUrl })` for a viem-`Chain`-shaped
 object — you supply the RPC URL, the registry deliberately records no public
@@ -60,8 +70,23 @@ abiByHash("sha256:…");        // historical ABIs too — decode an old tx corr
 verifyAbi("sha256:…", abi);   // sha256 over key-sorted compact JSON — verify, don't trust filenames
 writeFunctions("somnia-mainnet", "somnia-markets", "MarketsCore");
 // all state-changing functions — allowlists are application policy, not deployment facts
+
+allContractsWithAbi();
+// allContracts() with each ABI resolved to `abiJson` — addresses, networks and
+// ABIs in one call. Costs the whole corpus, which is why it lives here.
 ```
 
+### Not every deployment has an ABI
+
+`abiFor` returns `null`, and `abiJson` is `null`, for a real share of what the
+registry holds — around half, concentrated in the testnets. That is a fact
+about the records, not a gap in the package: the registry records a contract
+name only where a broadcast log stated it or the repo declared one, and an ABI
+is looked up by that name. Deployments created from a shared script as
+per-asset instances — `BTC_reader`, `ADA_oracle` — name a role rather than a
+contract, so they carry an address and no ABI. `contract` is set on exactly
+the entries that have one, so it is the field to branch on.
+
 ## Decoding calldata
 
 Requires `viem` (optional peer dependency; only this entry needs it).
@@ -82,6 +107,12 @@ decodeBySelector(data); // 4-byte fallback across every ABI the registry holds
 
 ## Versioning
 
-The package is a snapshot of the registry, published when its data moves.
+The package is a snapshot of the registry, and it is published when that
+snapshot changes rather than when someone remembers to publish it. The
+reconciliation lane compares the surface it would generate against the one the
+last release shipped, and cuts a patch version whenever addresses, ABIs or
+chain information moved — so a contract deployed today reaches npm on the next
+lane run. Minor and major versions are cut by hand, for API changes.
+
 Update the dependency to pick up newly deployed contracts — nothing is fetched
 at runtime.

package/dist/abis.d.ts

@@ -1,5 +1,5 @@
 import { abisByHash } from "./gen/abis-index.js";
-import { type NetworkSlug } from "./index.js";
+import { type AllContractsOptions, type ListedContract, type NetworkSlug } from "./index.js";
 export { abisByHash };
 export { abiDigest, verifyAbi } from "./digest.js";
 /**
@@ -24,6 +24,26 @@ export type AbiFunction = AbiItem & {
 export declare function abiFor(net: NetworkSlug, project: string, name: string): readonly AbiItem[] | null;
 /** Resolve a digest — including a historical one no current deployment points at — to its ABI. */
 export declare function abiByHash(digest: string): readonly AbiItem[] | null;
+export interface ResolvedContract extends ListedContract {
+    /**
+     * The recorded ABI, or null where the registry has none. Null is common and
+     * is a fact about the registry, not an error: an ABI is recorded only where
+     * a source named the contract, so per-asset instances deployed from a shared
+     * script — `BTC_reader`, `ADA_router` — usually carry an address and no ABI.
+     */
+    abiJson: readonly AbiItem[] | null;
+}
+/**
+ * Every current deployment with its ABI already resolved — addresses,
+ * networks and ABIs in one call.
+ *
+ * This is the whole-corpus convenience, and it costs the whole corpus: it
+ * lives here rather than in the root entry so that importing it is a decision.
+ * A server or admin surface rendering every contract wants exactly this; a
+ * client bundle wants `allContracts()` from the root and a per-contract
+ * `./abi/*` module for the one ABI it actually needs.
+ */
+export declare function allContractsWithAbi(opts?: AllContractsOptions): ResolvedContract[];
 /**
  * The state-changing functions of one deployment's ABI. Deliberately the
  * whole set: trimming it to an allowlist is operational policy, and policy

package/dist/abis.js

@@ -1,5 +1,5 @@
 import { abisByHash } from "./gen/abis-index.js";
-import { registry } from "./index.js";
+import { allContracts, registry, } from "./index.js";
 export { abisByHash };
 export { abiDigest, verifyAbi } from "./digest.js";
 /** The recorded ABI for one deployment, or null where the registry has none — including an unknown name, because the decoder path treats absence as an answer. For literal types, import the contract's `./abi/*` module. */
@@ -12,6 +12,22 @@ export function abiFor(net, project, name) {
 export function abiByHash(digest) {
     return abisByHash[digest] ?? null;
 }
+/**
+ * Every current deployment with its ABI already resolved — addresses,
+ * networks and ABIs in one call.
+ *
+ * This is the whole-corpus convenience, and it costs the whole corpus: it
+ * lives here rather than in the root entry so that importing it is a decision.
+ * A server or admin surface rendering every contract wants exactly this; a
+ * client bundle wants `allContracts()` from the root and a per-contract
+ * `./abi/*` module for the one ABI it actually needs.
+ */
+export function allContractsWithAbi(opts = {}) {
+    return allContracts(opts).map((entry) => ({
+        ...entry,
+        abiJson: entry.abi ? abiByHash(entry.abi) : null,
+    }));
+}
 /**
  * The state-changing functions of one deployment's ABI. Deliberately the
  * whole set: trimming it to an allowlist is operational policy, and policy

package/dist/enumerate.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Enumeration over the address books, with no generated data in sight.
+ *
+ * Split out for the same reason `decode-core.ts` is: the generated modules are
+ * a build product, so anything that imports them cannot be tested until they
+ * exist — and the filtering here is precisely what a dashboard relies on to
+ * not render a wiped testnet's addresses as current. Structural types rather
+ * than the package's public ones, so this file depends on nothing.
+ */
+export interface BookEntry {
+    address: string;
+    kind: string;
+    status: string;
+    version: string;
+    contract?: string;
+    implementation?: string;
+    startBlock?: number;
+    abi?: string;
+}
+export interface NetworkBook {
+    status: string;
+    contracts: Record<string, Record<string, BookEntry>>;
+}
+export type Books = Record<string, NetworkBook>;
+export interface Listed extends BookEntry {
+    network: string;
+    project: string;
+    name: string;
+}
+export interface EnumerateOptions {
+    includeRetiredNetworks?: boolean;
+    includeSuperseded?: boolean;
+    project?: string;
+}
+/** One network's deployments, optionally one project's. Throws on an unknown slug. */
+export declare function listContracts(books: Books, net: string, project?: string): Listed[];
+/**
+ * Every current deployment across every live network.
+ *
+ * Both exclusions are defaults rather than the caller's job on purpose: a
+ * retired network's addresses answer on a chain that was wiped, and a
+ * superseded deployment is one a later release replaced. Requiring each call
+ * site to remember that is how one of them forgets.
+ */
+export declare function listAll(books: Books, opts?: EnumerateOptions): Listed[];
+/**
+ * Address -> deployment, for one network.
+ *
+ * Proxy implementations resolve to their proxy's identity so that a signer
+ * looking at an implementation address learns which proxy it serves. The
+ * proxy's own entry always wins: `set` runs for every deployment first, and
+ * an implementation only claims an address nothing has claimed already.
+ */
+export declare function buildIdentityIndex(books: Books, net: string): Map<string, Listed & {
+    matchedBy: "address" | "implementation";
+}>;

package/dist/enumerate.js

@@ -0,0 +1,70 @@
+/**
+ * Enumeration over the address books, with no generated data in sight.
+ *
+ * Split out for the same reason `decode-core.ts` is: the generated modules are
+ * a build product, so anything that imports them cannot be tested until they
+ * exist — and the filtering here is precisely what a dashboard relies on to
+ * not render a wiped testnet's addresses as current. Structural types rather
+ * than the package's public ones, so this file depends on nothing.
+ */
+/** One network's deployments, optionally one project's. Throws on an unknown slug. */
+export function listContracts(books, net, project) {
+    const book = books[net];
+    if (!book)
+        throw new Error(`unknown network: ${net}`);
+    const out = [];
+    for (const [proj, entries] of Object.entries(book.contracts)) {
+        if (project !== undefined && proj !== project)
+            continue;
+        for (const [name, entry] of Object.entries(entries)) {
+            out.push({ network: net, project: proj, name, ...entry });
+        }
+    }
+    return out;
+}
+/**
+ * Every current deployment across every live network.
+ *
+ * Both exclusions are defaults rather than the caller's job on purpose: a
+ * retired network's addresses answer on a chain that was wiped, and a
+ * superseded deployment is one a later release replaced. Requiring each call
+ * site to remember that is how one of them forgets.
+ */
+export function listAll(books, opts = {}) {
+    const out = [];
+    for (const net of Object.keys(books).sort()) {
+        if (!opts.includeRetiredNetworks && books[net].status !== "live")
+            continue;
+        for (const entry of listContracts(books, net, opts.project)) {
+            if (!opts.includeSuperseded && entry.status !== "active")
+                continue;
+            out.push(entry);
+        }
+    }
+    return out.sort((a, b) => a.network.localeCompare(b.network) ||
+        a.project.localeCompare(b.project) ||
+        a.name.localeCompare(b.name));
+}
+/**
+ * Address -> deployment, for one network.
+ *
+ * Proxy implementations resolve to their proxy's identity so that a signer
+ * looking at an implementation address learns which proxy it serves. The
+ * proxy's own entry always wins: `set` runs for every deployment first, and
+ * an implementation only claims an address nothing has claimed already.
+ */
+export function buildIdentityIndex(books, net) {
+    const index = new Map();
+    const entries = listContracts(books, net);
+    for (const entry of entries) {
+        index.set(entry.address.toLowerCase(), { ...entry, matchedBy: "address" });
+    }
+    for (const entry of entries) {
+        if (!entry.implementation)
+            continue;
+        const key = entry.implementation.toLowerCase();
+        if (!index.has(key))
+            index.set(key, { ...entry, matchedBy: "implementation" });
+    }
+    return index;
+}

package/dist/gen/meta.d.ts

@@ -1,5 +1,5 @@
 export declare const registryVersion: {
-    readonly commit: "1bb7205d19ebffbb91872517da633c90dac40991";
-    readonly generatedAt: "2026-09-29T06:09:44.003Z";
+    readonly commit: "316af61c453e611840fea61e5ff3450c9fd58f3c";
+    readonly generatedAt: "2026-09-29T12:20:25.060Z";
     readonly schemaVersion: 1;
 };

package/dist/gen/meta.js

@@ -1,6 +1,6 @@
 // Generated by `registry sdk` from dist-public/ — do not edit.
 export const registryVersion = {
-    commit: "1bb7205d19ebffbb91872517da633c90dac40991",
-    generatedAt: "2026-09-29T06:09:44.003Z",
+    commit: "316af61c453e611840fea61e5ff3450c9fd58f3c",
+    generatedAt: "2026-09-29T12:20:25.060Z",
     schemaVersion: 1,
 };

package/dist/gen/registry.d.ts

@@ -1057,6 +1057,15 @@ export declare const hideki2Testnet: {
                 readonly status: "active";
                 readonly version: "addr:0x1a483b48";
             };
+            readonly "prophecy-oracle": {
+                readonly abi: "sha256:ecc4ba1d4404f9487b4d5d3e2b34ef1b7a1d9d188dbc94925ee07cd57d02943e";
+                readonly address: "0xc09b648aDf093808A0478eb12Bc4eBa709413463";
+                readonly contract: "ERC1967Proxy";
+                readonly kind: "singleton";
+                readonly startBlock: 3567925;
+                readonly status: "active";
+                readonly version: "addr:0xc09b648a";
+            };
             readonly "settlement-scheduler": {
                 readonly abi: "sha256:ecc4ba1d4404f9487b4d5d3e2b34ef1b7a1d9d188dbc94925ee07cd57d02943e";
                 readonly address: "0x9345df09F70EFe1F7d5608cD4e9f4a9871647E52";

package/dist/gen/registry.js

@@ -1063,6 +1063,15 @@ export const hideki2Testnet = {
                 "status": "active",
                 "version": "addr:0x1a483b48"
             },
+            "prophecy-oracle": {
+                "abi": "sha256:ecc4ba1d4404f9487b4d5d3e2b34ef1b7a1d9d188dbc94925ee07cd57d02943e",
+                "address": "0xc09b648aDf093808A0478eb12Bc4eBa709413463",
+                "contract": "ERC1967Proxy",
+                "kind": "singleton",
+                "startBlock": 3567925,
+                "status": "active",
+                "version": "addr:0xc09b648a"
+            },
             "settlement-scheduler": {
                 "abi": "sha256:ecc4ba1d4404f9487b4d5d3e2b34ef1b7a1d9d188dbc94925ee07cd57d02943e",
                 "address": "0x9345df09F70EFe1F7d5608cD4e9f4a9871647E52",

package/dist/index.d.ts

@@ -7,6 +7,19 @@ export type ProjectSlug<N extends NetworkSlug> = keyof Registry[N]["contracts"]
 export type ContractName<N extends NetworkSlug, P extends ProjectSlug<N>> = keyof Registry[N]["contracts"][P] & string;
 export type Address = `0x${string}`;
 export type AbiDigest = `sha256:${string}`;
+/**
+ * What a deployment is, structurally. `proxy` and `beacon-proxy` carry an
+ * `implementation`; `implementation` and `beacon` are the targets behind one
+ * and are recorded in their own right so an upgrade has something to point at;
+ * `external` is a contract Somnia depends on but did not deploy.
+ */
+export type DeploymentKind = "singleton" | "proxy" | "beacon" | "beacon-proxy" | "implementation" | "external";
+/**
+ * Whether a deployment is the one to use. `superseded` and `retired` records
+ * are kept rather than deleted — decoding an old transaction needs the address
+ * that was current when it was sent.
+ */
+export type ContractStatus = "active" | "superseded" | "retired";
 /** One deployment's record; narrow it by passing slugs and a name. The `abi` field is a digest — resolve it via the `./abis` entry point or a per-contract `./abi/*` module. */
 export type ContractEntry<N extends NetworkSlug = NetworkSlug, P extends ProjectSlug<N> = ProjectSlug<N>, C extends ContractName<N, P> = ContractName<N, P>> = Registry[N]["contracts"][P][C];
 type DistributedOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
@@ -46,24 +59,61 @@ export declare function tryAddress(net: NetworkSlug, project: string, name: stri
 export interface ListedContract {
     network: NetworkSlug;
     project: string;
+    /** The registry's name for this deployment — a role, like `BTC_reader`. */
     name: string;
     address: Address;
-    kind: string;
-    status: string;
+    kind: DeploymentKind;
+    status: ContractStatus;
     version: string;
+    /**
+     * The Solidity contract name, where a source states it. Absent where no
+     * source did: the registry records a name only from a broadcast log or a
+     * repo declaration, never a guess. This is also the key the per-contract
+     * `./abi/<project>/<contract>` modules are published under, so an
+     * enumerated deployment can reach its typed ABI only when this is set —
+     * and it is set on exactly the deployments that have an `abi` digest.
+     */
+    contract?: string;
     implementation?: Address;
     startBlock?: number;
     abi?: AbiDigest;
 }
 /** Enumerate a network's deployments, optionally one project's. */
 export declare function contracts(net: NetworkSlug, project?: string): ListedContract[];
+export interface AllContractsOptions {
+    /**
+     * Include networks the registry has retired. Off by default: a retired
+     * network's addresses still exist but answer on a chain that was wiped, so
+     * showing them beside live ones is how a dashboard displays a balance that
+     * is not there.
+     */
+    includeRetiredNetworks?: boolean;
+    /**
+     * Include deployments superseded by a later one. Off by default — the
+     * registry publishes only each deployment's current release, so this
+     * changes nothing today and keeps meaning the same thing if that changes.
+     */
+    includeSuperseded?: boolean;
+    project?: string;
+}
+/**
+ * Every current deployment, across every live network.
+ *
+ * The one call a dashboard wants: enumerating per network means knowing the
+ * slugs, remembering that retired ones exist, and filtering status by hand at
+ * every call site — three chances to show a wiped testnet's addresses as
+ * current. Ordered by network slug, then project, then name, so a rendered
+ * list is stable between releases.
+ */
+export declare function allContracts(opts?: AllContractsOptions): ListedContract[];
 export interface ContractIdentity {
     network: NetworkSlug;
     project: string;
     name: string;
-    kind: string;
-    status: string;
+    kind: DeploymentKind;
+    status: ContractStatus;
     address: Address;
+    contract?: string;
     implementation?: Address;
     abi?: AbiDigest;
     /** "address" — the queried address is the deployment; "implementation" — it is the implementation behind one. */

package/dist/index.js

@@ -1,4 +1,5 @@
 import { registry } from "./gen/registry.js";
+import { buildIdentityIndex, listAll, listContracts } from "./enumerate.js";
 export * from "./gen/registry.js";
 export { registryVersion } from "./gen/meta.js";
 function info(slug) {
@@ -56,20 +57,22 @@ export function tryAddress(net, project, name) {
     const book = registry[net]?.contracts;
     return book?.[project]?.[name]?.address ?? null;
 }
+const books = registry;
 /** Enumerate a network's deployments, optionally one project's. */
 export function contracts(net, project) {
-    const book = registry[net]?.contracts;
-    if (!book)
-        throw new Error(`unknown network: ${String(net)}`);
-    const out = [];
-    for (const [proj, entries] of Object.entries(book)) {
-        if (project !== undefined && proj !== project)
-            continue;
-        for (const [name, entry] of Object.entries(entries)) {
-            out.push({ network: net, project: proj, name, ...entry });
-        }
-    }
-    return out;
+    return listContracts(books, net, project);
+}
+/**
+ * Every current deployment, across every live network.
+ *
+ * The one call a dashboard wants: enumerating per network means knowing the
+ * slugs, remembering that retired ones exist, and filtering status by hand at
+ * every call site — three chances to show a wiped testnet's addresses as
+ * current. Ordered by network slug, then project, then name, so a rendered
+ * list is stable between releases.
+ */
+export function allContracts(opts = {}) {
+    return listAll(books, opts);
 }
 const identityIndex = new Map();
 /**
@@ -81,16 +84,7 @@ const identityIndex = new Map();
 export function identify(net, addr) {
     let index = identityIndex.get(net);
     if (!index) {
-        index = new Map();
-        for (const entry of contracts(net)) {
-            const identity = { ...entry, matchedBy: "address" };
-            index.set(entry.address.toLowerCase(), identity);
-            if (entry.implementation) {
-                const viaImpl = entry.implementation.toLowerCase();
-                if (!index.has(viaImpl))
-                    index.set(viaImpl, { ...identity, matchedBy: "implementation" });
-            }
-        }
+        index = buildIdentityIndex(books, net);
         identityIndex.set(net, index);
     }
     return index.get(addr.toLowerCase()) ?? null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@somnia-chain/contracts-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Somnia contract addresses, ABIs and chain information, typed. Generated from the Somnia contract registry.",
   "license": "MIT",
   "type": "module",