@somnia-chain/contracts-sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,32 +1,87 @@
 import { registry } from "./gen/registry.js";
 export * from "./gen/registry.js";
+export { registryVersion } from "./gen/meta.js";
 export type Registry = typeof registry;
 export type NetworkSlug = keyof Registry & string;
 export type ProjectSlug<N extends NetworkSlug> = keyof Registry[N]["contracts"] & string;
 export type ContractName<N extends NetworkSlug, P extends ProjectSlug<N>> = keyof Registry[N]["contracts"][P] & string;
 export type Address = `0x${string}`;
-/** One deployment's record; narrow it by passing slugs and a name. */
+export type AbiDigest = `sha256:${string}`;
+/** 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;
 /** One network's chain information, without the address book. */
-export type NetworkInfo<N extends NetworkSlug = NetworkSlug> = DistributedOmit<Registry[N], "contracts">;
+export type NetworkInfo<N extends NetworkSlug = NetworkSlug> = DistributedOmit<Registry[N] & {
+    slug: N;
+}, "contracts">;
 /** Every network's chain information, retired ones included. */
 export declare const networks: readonly NetworkInfo[];
-/** One network's chain information, without the address book. */
-export declare function getNetwork<N extends NetworkSlug>(network: N): Omit<Registry[N], "contracts">;
+/** One network's chain information, without the address book. Throws on an unknown slug. */
+export declare function network<N extends NetworkSlug>(slug: N): NetworkInfo<N>;
+/** @deprecated alias kept from 0.1.x — use `network`. */
+export declare function getNetwork<N extends NetworkSlug>(slug: N): NetworkInfo<N>;
 /**
  * All networks that answer at a chain id. Plural on purpose: chain ids are
  * not unique across Somnia networks (a regenesis reuses the id with none of
- * the state), so an id can name a retired and a live network at once. Filter
- * on `status` if only the live one matters.
+ * the state), so an id can name a retired and a live network at once. The
+ * array is what forces callers to disambiguate instead of guessing.
+ */
+export declare function networksByChainId(chainId: number): NetworkInfo[];
+/** @deprecated alias kept from 0.1.x — use `networksByChainId`. */
+export declare const getNetworksByChainId: typeof networksByChainId;
+export declare function liveNetworks(): NetworkInfo[];
+/** One deployment: address, kind, version, status and the ABI digest. Throws on unknown names. */
+export declare function getContract<N extends NetworkSlug, P extends ProjectSlug<N>, C extends ContractName<N, P>>(net: N, project: P, name: C): Registry[N]["contracts"][P][C];
+/** The deployed address. Throws on unknown names — the "this must exist" form. */
+export declare function address<N extends NetworkSlug, P extends ProjectSlug<N>, C extends ContractName<N, P>>(net: N, project: P, name: C): Registry[N]["contracts"][P][C] extends {
+    address: infer A;
+} ? A : never;
+/** @deprecated alias kept from 0.1.x — use `address`. */
+export declare const getAddress: typeof address;
+/**
+ * The deployed address, or null — the "is it deployed here?" form. Projects
+ * do not span every network, so absence is an answer, not an error.
  */
-export declare function getNetworksByChainId(chainId: number): NetworkInfo[];
+export declare function tryAddress(net: NetworkSlug, project: string, name: string): Address | null;
+export interface ListedContract {
+    network: NetworkSlug;
+    project: string;
+    name: string;
+    address: Address;
+    kind: string;
+    status: string;
+    version: 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 ContractIdentity {
+    network: NetworkSlug;
+    project: string;
+    name: string;
+    kind: string;
+    status: string;
+    address: Address;
+    implementation?: Address;
+    abi?: AbiDigest;
+    /** "address" — the queried address is the deployment; "implementation" — it is the implementation behind one. */
+    matchedBy: "address" | "implementation";
+}
+/**
+ * Reverse lookup: which recorded deployment answers at this address? Proxy
+ * implementations resolve to their proxy's identity, marked `matchedBy:
+ * "implementation"`. Null for anything the registry has never seen — which on
+ * a permissionless chain is normal, not an error.
+ */
+export declare function identify(net: NetworkSlug, addr: string): ContractIdentity | null;
 /**
  * A viem-`Chain`-shaped object for a network, structurally compatible with
  * `viem`'s `Chain` without depending on it. The registry records no public
  * RPC endpoint — deliberately — so you bring your own.
  */
-export declare function toChain<N extends NetworkSlug>(network: N, opts: {
+export declare function toChain<N extends NetworkSlug>(net: N, opts: {
     rpcUrl: string;
     wsUrl?: string;
 }): {
@@ -46,11 +101,3 @@ export declare function toChain<N extends NetworkSlug>(network: N, opts: {
         };
     };
 };
-/** One deployment: address, kind, version, status and — where recorded — the ABI. */
-export declare function getContract<N extends NetworkSlug, P extends ProjectSlug<N>, C extends ContractName<N, P>>(network: N, project: P, name: C): Registry[N]["contracts"][P][C];
-export declare function getAddress<N extends NetworkSlug, P extends ProjectSlug<N>, C extends ContractName<N, P>>(network: N, project: P, name: C): Registry[N]["contracts"][P][C] extends {
-    address: infer A;
-} ? A : never;
-export declare function getAbi<N extends NetworkSlug, P extends ProjectSlug<N>, C extends ContractName<N, P>>(network: N, project: P, name: C): Registry[N]["contracts"][P][C] extends {
-    abi: infer A;
-} ? A : undefined;

package/dist/index.js

@@ -1,38 +1,112 @@
 import { registry } from "./gen/registry.js";
 export * from "./gen/registry.js";
+export { registryVersion } from "./gen/meta.js";
+function info(slug) {
+    const { contracts: _contracts, ...rest } = registry[slug];
+    return { slug, ...rest };
+}
 /** Every network's chain information, retired ones included. */
-export const networks = Object.keys(registry).map((slug) => getNetwork(slug));
-/** One network's chain information, without the address book. */
-export function getNetwork(network) {
-    const entry = registry[network];
-    if (!entry)
-        throw new Error(`unknown network: ${String(network)}`);
-    const { contracts: _contracts, ...info } = entry;
-    return info;
+export const networks = Object.keys(registry).map(info);
+/** One network's chain information, without the address book. Throws on an unknown slug. */
+export function network(slug) {
+    if (!(slug in registry))
+        throw new Error(`unknown network: ${String(slug)}`);
+    return info(slug);
+}
+/** @deprecated alias kept from 0.1.x — use `network`. */
+export function getNetwork(slug) {
+    return network(slug);
 }
 /**
  * All networks that answer at a chain id. Plural on purpose: chain ids are
  * not unique across Somnia networks (a regenesis reuses the id with none of
- * the state), so an id can name a retired and a live network at once. Filter
- * on `status` if only the live one matters.
+ * the state), so an id can name a retired and a live network at once. The
+ * array is what forces callers to disambiguate instead of guessing.
  */
-export function getNetworksByChainId(chainId) {
-    return Object.keys(registry)
-        .filter((slug) => registry[slug].chainId === chainId)
-        .map((slug) => getNetwork(slug));
+export function networksByChainId(chainId) {
+    return networks.filter((n) => n.chainId === chainId);
+}
+/** @deprecated alias kept from 0.1.x — use `networksByChainId`. */
+export const getNetworksByChainId = networksByChainId;
+export function liveNetworks() {
+    return networks.filter((n) => n.status === "live");
+}
+/** One deployment: address, kind, version, status and the ABI digest. Throws on unknown names. */
+export function getContract(net, project, name) {
+    const book = registry[net]?.contracts;
+    if (!book)
+        throw new Error(`unknown network: ${String(net)}`);
+    const entry = book[project]?.[name];
+    if (!entry)
+        throw new Error(`unknown contract: ${String(project)}/${String(name)} on ${String(net)}`);
+    return entry;
+}
+/** The deployed address. Throws on unknown names — the "this must exist" form. */
+export function address(net, project, name) {
+    return getContract(net, project, name)
+        .address;
+}
+/** @deprecated alias kept from 0.1.x — use `address`. */
+export const getAddress = address;
+/**
+ * The deployed address, or null — the "is it deployed here?" form. Projects
+ * do not span every network, so absence is an answer, not an error.
+ */
+export function tryAddress(net, project, name) {
+    const book = registry[net]?.contracts;
+    return book?.[project]?.[name]?.address ?? null;
+}
+/** 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;
+}
+const identityIndex = new Map();
+/**
+ * Reverse lookup: which recorded deployment answers at this address? Proxy
+ * implementations resolve to their proxy's identity, marked `matchedBy:
+ * "implementation"`. Null for anything the registry has never seen — which on
+ * a permissionless chain is normal, not an error.
+ */
+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" });
+            }
+        }
+        identityIndex.set(net, index);
+    }
+    return index.get(addr.toLowerCase()) ?? null;
 }
 /**
  * A viem-`Chain`-shaped object for a network, structurally compatible with
  * `viem`'s `Chain` without depending on it. The registry records no public
  * RPC endpoint — deliberately — so you bring your own.
  */
-export function toChain(network, opts) {
-    const info = getNetwork(network);
-    const explorer = info.explorerUrls?.[0];
+export function toChain(net, opts) {
+    const n = network(net);
+    const explorer = n.explorerUrls?.[0];
     return {
-        id: registry[network].chainId,
-        name: registry[network].name,
-        nativeCurrency: registry[network].nativeCurrency,
+        id: registry[net].chainId,
+        name: registry[net].name,
+        nativeCurrency: registry[net].nativeCurrency,
         rpcUrls: {
             default: {
                 http: [opts.rpcUrl],
@@ -42,20 +116,3 @@ export function toChain(network, opts) {
         ...(explorer ? { blockExplorers: { default: { name: "Explorer", url: explorer } } } : {}),
     };
 }
-/** One deployment: address, kind, version, status and — where recorded — the ABI. */
-export function getContract(network, project, name) {
-    const book = registry[network]?.contracts;
-    if (!book)
-        throw new Error(`unknown network: ${String(network)}`);
-    const entry = book[project]?.[name];
-    if (!entry)
-        throw new Error(`unknown contract: ${String(project)}/${String(name)} on ${String(network)}`);
-    return entry;
-}
-export function getAddress(network, project, name) {
-    return getContract(network, project, name)
-        .address;
-}
-export function getAbi(network, project, name) {
-    return getContract(network, project, name).abi;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@somnia-chain/contracts-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Somnia contract addresses, ABIs and chain information, typed. Generated from the Somnia contract registry.",
   "license": "MIT",
   "type": "module",
@@ -11,6 +11,18 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./abis": {
+      "types": "./dist/abis.d.ts",
+      "default": "./dist/abis.js"
+    },
+    "./decode": {
+      "types": "./dist/decode.d.ts",
+      "default": "./dist/decode.js"
+    },
+    "./abi/*": {
+      "types": "./dist/gen/abi/*.d.ts",
+      "default": "./dist/gen/abi/*.js"
     }
   },
   "files": [
@@ -20,6 +32,17 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@noble/hashes": "^1.7.1"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "viem": {
+      "optional": true
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/somnia-chain/contract-registry.git",