@somnia-chain/contracts-sdk 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# @somnia-chain/contracts-sdk
+
+Somnia contract addresses, ABIs and chain information, typed. Generated from
+the Somnia contract registry — the same records every Somnia deploy is
+reconciled against.
+
+```bash
+npm install @somnia-chain/contracts-sdk
+```
+
+```ts
+import { getAddress, getAbi, getContract, registry } from "@somnia-chain/contracts-sdk";
+
+getAddress("somnia-mainnet", "somnia-markets", "MarketsCore");
+// -> "0x…", typed as the literal, with every slug and name autocompleted
+
+const { address, abi } = getContract("somnia-mainnet", "somnia-markets", "MarketsCore");
+// abi is `as const` — viem infers function names and argument types from it
+```
+
+The whole tree is also there as one constant, `registry`, keyed
+network → project → contract, plus one exported constant per network
+(`somniaMainnet`, …) and `networks` with every network's chain information.
+
+For viem, `toChain` builds a `Chain`-shaped object — the registry records no
+public RPC endpoint, so you bring your own:
+
+```ts
+import { createPublicClient, http } from "viem";
+import { toChain } from "@somnia-chain/contracts-sdk";
+
+const chain = toChain("somnia-mainnet", { rpcUrl: "https://your-rpc" });
+const client = createPublicClient({ chain, transport: http() });
+```
+
+Exported types: `Registry`, `NetworkSlug`, `ProjectSlug`, `ContractName`,
+`ContractEntry`, `NetworkInfo`, `Address`.
+
+## Chain IDs are not unique
+
+Somnia networks are keyed by **slug**, never by chain id: a testnet regenesis
+reuses the chain id with none of the state, so one id can name two networks
+with different contracts at identical addresses. If an id is all you have:
+
+```ts
+import { getNetworksByChainId } from "@somnia-chain/contracts-sdk";
+
+getNetworksByChainId(50383); // -> both hideki testnets; filter on `status`
+```
+
+## Versioning
+
+The package is a snapshot of the registry, published when its data moves.
+Update the dependency to pick up newly deployed contracts — nothing is fetched
+at runtime.