@wonderland/interop 0.0.0 → 0.1.0

package/README.md

@@ -1,3 +1,131 @@
-# Package Placeholder
+# @wonderland/interop
 
-Reserved package name. Actual code will be published in a later version.
+A TypeScript library for handling interoperable blockchain addresses and cross-chain operations across different networks.
+
+This package combines two powerful functionalities:
+
+1. **Interoperable Addresses**: Provides methods to convert between human-readable addresses and their binary string representation, following the [ERC-7930](https://ethereum-magicians.org/t/erc-7930-interoperable-addresses/23365) standard. For backward compatibility with existing smart contracts, the package includes utilities to extract individual components (chainId and address) from the binary representation.
+
+2. **Cross-Chain Operations**: Enables seamless token transfers and swaps between different blockchain networks through a unified API, supporting various bridge protocols.
+
+```mermaid
+graph LR
+    A[humanReadable]
+    C[binaryRepresentation]
+    D[chainId]
+    E[address]
+    F[Cross-Chain Operations]
+    G[Token Transfers]
+
+    A -->|humanReadableToBinary| C
+    C -->|binaryToHumanReadable| A
+    C -->|getChainId| D
+    C -->|getAddress| E
+    F -->|Transfer| G
+```
+
+## Setup
+
+1. Install dependencies running `pnpm install`
+
+## Available Scripts
+
+Available scripts that can be run using `pnpm`:
+
+| Script        | Description                                             |
+| ------------- | ------------------------------------------------------- |
+| `build`       | Build library using tsc                                 |
+| `check-types` | Check types issues using tsc                            |
+| `clean`       | Remove `dist` folder                                    |
+| `lint`        | Run ESLint to check for coding standards                |
+| `lint:fix`    | Run linter and automatically fix code formatting issues |
+| `format`      | Check code formatting and style using Prettier          |
+| `format:fix`  | Run formatter and automatically fix issues              |
+| `test`        | Run tests using vitest                                  |
+| `test:cov`    | Run tests with coverage report                          |
+
+## Usage
+
+### Interoperable Addresses
+
+```typescript
+// Using the Provider
+import { InteropAddressProvider } from '@wonderland/interop';
+
+const humanReadableAddress = "alice.eth@eip155:1#ABCD1234"
+const binaryAddress = InteropAddressProvider.humanReadableToBinary(humanReadableAddress)
+
+// Or just importing the method
+import { humanReadableToBinary } from '@wonderland/interop';
+const binaryAddress = humanReadableToBinary(humanReadableAddress)
+```
+
+### Cross-Chain Operations
+
+```typescript
+import { createCrossChainProvider } from "@wonderland/interop";
+
+// Create a provider for a specific protocol (e.g., Across)
+const provider = createCrossChainProvider("across");
+
+// Get a quote for a cross-chain transfer
+const quote = await provider.getQuote("crossChainTransfer", {
+    inputTokenAddress: "0x...",
+    outputTokenAddress: "0x...",
+    inputAmount: "1000000000000000000",
+    inputChainId: 1,
+    outputChainId: 137,
+    sender: "0x...",
+    recipient: "0x...",
+});
+
+// Simulate the transaction
+const transactions = await provider.simulateOpen(quote.openParams);
+```
+
+## API
+
+### Interoperable Addresses
+
+#### [InteropAddressProvider](./src/providers/InteropAddressProvider.ts)
+
+Available methods:
+
+-   `humanReadableToBinary(humanReadableAddress: string)`
+-   `binaryToHumanReadable(binaryAddress: Hex)`
+-   `getChainId(binaryAddress: Hex)`
+-   `getAddress(binaryAddress: Hex)`
+-   `buildFromPayload(payload: InteropAddressFields)`
+-   `computeChecksum(humanReadableAddress: string)`
+
+### Cross-Chain Operations
+
+#### [CrossChainProviderFactory](./src/services/crossChainProviderFactory.ts)
+
+The factory provides a standardized way to create and manage cross-chain providers for different protocols.
+
+Available methods:
+
+-   `build<Protocol>(protocolName: Protocol, config?: Config, dependencies?: Dependencies)`: Creates a new provider instance for the specified protocol
+-   `createCrossChainProvider<Protocol>(protocolName: Protocol, config?: Config, dependencies?: Dependencies)`: Helper function to create a provider instance
+
+#### [CrossChainExecutor](./src/services/crossChainExecutor.ts)
+
+The executor handles the execution of cross-chain operations, providing a unified interface for different protocols.
+
+Available methods:
+
+-   `execute(params: ExecutionParams)`: Executes a cross-chain operation
+-   `getQuotes(params: QuoteParams)`: Gets a quote for a cross-chain operation
+
+Supported protocols:
+
+-   Across Protocol
+-   More protocols coming soon...
+
+## References
+
+-   [ERC 7930: Interoperable Addresses](https://ethereum-magicians.org/t/erc-7930-interoperable-addresses/23365)
+-   [Viem Documentation](https://viem.sh/) - Low-level Ethereum interface used for transaction handling
+-   [Zod Documentation](https://zod.dev/) - TypeScript-first schema validation used for input validation
+-   [Cross-Chain Interoperability Standards](https://ethereum.org/en/developers/docs/bridges/) - Overview of cross-chain bridge concepts

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from "@wonderland/interop-addresses";
+export * from "@wonderland/interop-cross-chain";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,3 @@
+export * from "@wonderland/interop-addresses";
+export * from "@wonderland/interop-cross-chain";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC"}

package/package.json

@@ -1,14 +1,38 @@
 {
-  "name": "@wonderland/interop",
-  "version": "0.0.0",
-  "description": "Placeholder package. Real code coming soon.",
-  "license": "MIT",
-  "main": "index.js",
-  "types": "index.d.ts",
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "publish:park": "npm publish --tag snapshot --access public"
-  }
+    "name": "@wonderland/interop",
+    "version": "0.1.0",
+    "description": "Complete SDK for blockchain interoperability with cross-chain operations and address utilities",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/defi-wonderland/interop-sdk.git",
+        "directory": "apps/sdk"
+    },
+    "license": "MIT",
+    "author": "Wonderland",
+    "type": "module",
+    "main": "./dist/src/index.js",
+    "types": "./dist/src/index.d.ts",
+    "directories": {
+        "src": "src"
+    },
+    "files": [
+        "dist/*",
+        "package.json",
+        "!**/*.tsbuildinfo"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "check-types": "tsc --noEmit -p ./tsconfig.json",
+        "clean": "rm -rf dist/",
+        "format": "prettier --check \"{src,test}/**/*.{js,ts,json}\"",
+        "format:fix": "prettier --write \"{src,test}/**/*.{js,ts,json}\"",
+        "lint": "eslint \"{src,test}/**/*.{js,ts,json}\"",
+        "lint:fix": "pnpm lint --fix",
+        "test": "vitest run --config vitest.config.ts --passWithNoTests",
+        "test:cov": "vitest run --config vitest.config.ts --coverage"
+    },
+    "dependencies": {
+        "@wonderland/interop-addresses": "0.1.0",
+        "@wonderland/interop-cross-chain": "0.1.0"
+    }
 }

package/LICENSE

@@ -1,6 +0,0 @@
-MIT License
-
-Copyright (c) 2025
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction...

package/index.d.ts

@@ -1 +0,0 @@
-export {};

package/index.js

@@ -1 +0,0 @@
-export {};