@somnia-chain/contracts-sdk 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,32 +1,137 @@
 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}`;
+/**
+ * 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;
 /** 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 getNetworksByChainId(chainId: number): NetworkInfo[];
+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 tryAddress(net: NetworkSlug, project: string, name: string): Address | null;
+export interface ListedContract {
+    network: NetworkSlug;
+    project: string;
+    /** The registry's name for this deployment — a role, like `BTC_reader`. */
+    name: string;
+    address: Address;
+    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: 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. */
+    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 +151,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,106 @@
 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) {
+    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;
+}
+const books = registry;
+/** Enumerate a network's deployments, optionally one project's. */
+export function contracts(net, project) {
+    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();
+/**
+ * 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 = buildIdentityIndex(books, net);
+        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 +110,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.3.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",