feat(sdk): sdk exports and initial types (#2624)

Initial SDK exports / defining export strategy and initial types

issue: none

sdk/README.md

@@ -3,3 +3,40 @@
 ## Overview
 
 The Omni SDK is a TypeScript library for interfacing with the Omni network.
+
+## Code Architecture
+
+### Named Exports
+
+We should always use named exports, as they're more friendly to tree-shaking, thus reducing bundle sizes. The alternative, `export *` may make it difficult for a bundler to identify what can be discarded.
+
+### Barrel Files
+
+Where possible, we use barrel files to re-export functionality from subdirectories. For example:
+
+- `src/utils/index.ts` - re-exports utilOne and utilTwo
+- `src/utils/utilOne.ts`
+- `src/utils/utilTwo.ts`
+
+Reasons for this are:
+
+1. This allows us to simplify import statements for consumers:
+   Instead of: `import { mainnet } from "@package/chains/mainnet"`
+   We get: `import { mainnet } from "@package/chains"`
+2. We can rename exports without changing consumer code
+3. Internal file structures can evolve over time without affecting consumers
+4. Reduces the number of import statements required by consumers
+
+The top level barrel file (`src/index.ts`) re-exports functionality, that can be imported from the root:
+
+`import { util } from "@package/sdk"`
+
+Where logic is not exported here, it would be exported from a barrel file in the relevant subdirectory, imported as:
+
+`import { util } from "@package/sdk/utils"`
+
+The only exception to this is types, which we export directly from their modules, since:
+
+1. Typescript handles `type` imports differently from value imports
+2. Types are erased at runtime
+3. Exporting types from an `index.ts` will avoid potential circular dependency issues

sdk/package.json

@@ -18,5 +18,8 @@
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
     "typescript": "5.7.2"
+  },
+  "dependencies": {
+    "viem": "^2.21.53"
   }
 }

sdk/src/abi/index.ts

@@ -0,0 +1 @@
+export { omniPortalAbi } from "./omniPortal.js"

sdk/src/chains/index.ts

@@ -0,0 +1,58 @@
+import type { Chain } from "../types/chain.js"
+
+/**
+ * @summary We will want to eventually define chains in submodules, and re-export from here,
+ * to allow for lazy loading for consumers. But this is fine for now while we work
+ * with a small number of chains.
+ */
+
+export const mainnet: Chain = {
+  name: "Ethereum Mainnet",
+  id: 1,
+  testnet: false,
+  portalContract: "0x0000000000000000000000000000000000000000",
+  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+}
+
+////////////////////////////////////////////////////////////
+/// TESTNETS
+////////////////////////////////////////////////////////////
+export const omniOmega: Chain = {
+  name: "Omni Omega",
+  id: 164,
+  testnet: true,
+  portalContract: "0xcB60A0451831E4865bC49f41F9C67665Fc9b75C3",
+  nativeCurrency: { name: "Omni", symbol: "OMNI", decimals: 18 },
+}
+
+export const holesky: Chain = {
+  name: "Ethereum Holesky",
+  id: 17000,
+  testnet: true,
+  portalContract: "0xcB60A0451831E4865bC49f41F9C67665Fc9b75C3",
+  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+}
+
+export const baseSepolia: Chain = {
+  name: "Base Sepolia",
+  id: 84532,
+  testnet: true,
+  portalContract: "0xcB60A0451831E4865bC49f41F9C67665Fc9b75C3",
+  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+}
+
+export const arbitrumSepolia: Chain = {
+  name: "Arbitrum Sepolia",
+  id: 421614,
+  testnet: true,
+  portalContract: "0xcB60A0451831E4865bC49f41F9C67665Fc9b75C3",
+  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+}
+
+export const optimismSepolia: Chain = {
+  name: "Optimism Sepolia",
+  id: 11155420,
+  testnet: true,
+  portalContract: "0xcB60A0451831E4865bC49f41F9C67665Fc9b75C3",
+  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+}

sdk/src/config.ts

@@ -0,0 +1,7 @@
+import { http, createPublicClient } from "viem"
+import { mainnet } from "viem/chains"
+
+export const publicClient = createPublicClient({
+  chain: mainnet,
+  transport: http(),
+})

sdk/src/index.ts

@@ -1 +1,5 @@
-export * from "./types/index.js"
+export { omniPortalAbi } from "./abi/omniPortal.js"
+export type { Chain } from "./types/chain.js"
+export type { NativeCurrency } from "./types/nativeCurrency.js"
+export type { XMsg } from "./types/xMsg.js"
+export type { XReceipt } from "./types/xReceipt.js"

sdk/src/types/chain.ts

@@ -0,0 +1,9 @@
+import type { NativeCurrency } from "./nativeCurrency.js"
+
+export type Chain = {
+  name: string
+  id: number
+  testnet: boolean
+  portalContract: string
+  nativeCurrency: NativeCurrency
+}

sdk/src/types/nativeCurrency.ts

@@ -0,0 +1,5 @@
+export type NativeCurrency = {
+  name: string
+  symbol: string
+  decimals: number
+}

sdk/src/types/xMsg.ts

@@ -0,0 +1,12 @@
+/**
+ * Represents an xMsg event - emitted when an xcall is made to the OmniPortal
+ *
+ * @param destinationChainId - The destination chain ID the xcall is aimed at
+ * @param shardId - The shard ID - TODO
+ * @param offset - The xMsg offset - unique identifier for this XMsg in the source -> destination XStream
+ */
+export type XMsg = {
+  destinationChainId: number
+  shardId: number
+  offset: number
+}

sdk/src/types/xReceipt.ts

@@ -0,0 +1,12 @@
+/**
+ * Represents an XReceipt event - emitted when an XMsg is executed on its destination chain
+ *
+ * @param sourceChainId - The source chain ID the XMsg was sent
+ * @param shardId - The shard ID - TODO
+ * @param offset - The xMsg offset - unique identifier for this XMsg in the source -> destination XStream
+ */
+export type XReceipt = {
+  sourceChainId: number
+  shardId: number
+  offset: number
+}

sdk/src/utils/checkXMsgStatus.ts

@@ -0,0 +1,14 @@
+/**
+ * Checks the status of an xMsg.
+ *
+ * @param sourceChain - The source chain
+ * @param destinationChain - The destination chain
+ * @param offset - The xMsg offset - unique identifier for this XMsg in the source -> destination XStream
+ *
+ * @returns TODO
+ *
+ * @example TODO
+ */
+export function checkXMsgStatus() {
+  // TODO
+}

sdk/src/utils/index.ts

@@ -1 +1 @@
-// TODO export
+export { checkXMsgStatus } from "./checkXMsgStatus.js"