@zebec-network/admin-sdk 1.0.0

package/README.md

@@ -0,0 +1,730 @@
+# @zebec-network/admin-sdk
+
+Admin SDK for managing Zebec smart contract operations across Solana, EVM-compatible chains, and Sui.
+
+Provides typed service classes for configuring payment streams, staking/lockup programs, and card payment infrastructure — covering initialization, fee management, token whitelisting, vault setup, and on-chain data reads.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Solana — Stream Admin](#solana--stream-admin)
+  - [Solana — Staking Admin](#solana--staking-admin)
+  - [Solana — Card Admin](#solana--card-admin)
+  - [Solana — Partner Card Admin](#solana--partner-card-admin)
+  - [EVM — Card Admin](#evm--card-admin)
+  - [Sui — Card Admin](#sui--card-admin)
+- [API Reference](#api-reference)
+  - [ZebecStreamAdminService](#zebecstreamadminservice)
+  - [ZebecStakeAdminService](#zebecstakeadminservice)
+  - [ZebecSolanaCardV2AdminService](#zebecsolanacardv2adminservice)
+  - [ZebecSolanaPartnerAdminCardService](#zebecsolanapartneradmincardservice)
+  - [ZebecCardService (EVM)](#zebeccardservice-evm)
+  - [SuiCardAdminService](#suicardadminservice)
+  - [ProxyStreamAdminService](#proxystreamadminservice)
+- [Supported Networks](#supported-networks)
+- [Types](#types)
+- [Utilities](#utilities)
+- [Environment Setup](#environment-setup)
+- [Folder Structure](#folder-structure)
+- [Scripts](#scripts)
+
+---
+
+## Installation
+
+```bash
+npm install @zebec-network/admin-sdk
+# or
+yarn add @zebec-network/admin-sdk
+```
+
+**Peer dependencies** vary by which chains you use:
+
+| Chain    | Required peer dep                                   |
+| -------- | --------------------------------------------------- |
+| Solana   | `@coral-xyz/anchor`, `@solana/web3.js`              |
+| EVM      | `ethers@^6`                                         |
+| Sui      | `@mysten/sui`                                       |
+
+---
+
+## Quick Start
+
+### Solana Quick Start
+
+```typescript
+import { Connection, Keypair } from "@solana/web3.js";
+import { AnchorProvider, Wallet } from "@coral-xyz/anchor";
+import { ZebecStreamAdminService } from "@zebec-network/admin-sdk";
+
+const connection = new Connection(process.env.RPC_URL!);
+const keypair = Keypair.fromSecretKey(/* your key */);
+const provider = new AnchorProvider(connection, new Wallet(keypair), {});
+
+const service = ZebecStreamAdminService.create("my-config", provider, "mainnet-beta");
+
+const tx = await service.initializeStreamConfig({
+  feePercentage: 1, // 100 in basis points
+  feeVault: keypair.publicKey,
+  // ...other params
+});
+console.log(tx.signature);
+```
+
+### EVM Quick Start
+
+```typescript
+import { ethers } from "ethers";
+import { ZebecCardService, SupportedChain } from "@zebec-network/admin-sdk";
+
+const provider = new ethers.JsonRpcProvider(process.env.EVM_RPC_URL!);
+const signer = new ethers.Wallet(process.env.EVM_PRIVATE_KEY!, provider);
+
+const cardService = new ZebecCardService(signer, SupportedChain.Base);
+await cardService.setNativeFee({ feeInPercent: "1" }); // 100 bps
+```
+
+### Sui Quick Start
+
+```typescript
+import { SuiClient } from "@mysten/sui/client";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import {
+  SuiCardAdminService,
+  SuiSilverCardPackageInfo,
+  createSuiSignTransactionMethodFromSigner,
+} from "@zebec-network/admin-sdk";
+
+const suiClient = new SuiClient({ url: "https://fullnode.mainnet.sui.io" });
+const keypair = Ed25519Keypair.fromSecretKey(/* your key */);
+
+const wallet = {
+  address: keypair.toSuiAddress(),
+  signTransaction: createSuiSignTransactionMethodFromSigner(keypair),
+};
+
+const packageInfo = new SuiSilverCardPackageInfo("mainnet");
+const adminService = await SuiCardAdminService.create(packageInfo, suiClient, wallet);
+
+const payload = await adminService.setCardVault({ vaultAddress: "0x..." });
+const result = await payload.execute();
+```
+
+---
+
+## Usage
+
+### Solana — Stream Admin
+
+```typescript
+import { ZebecStreamAdminService } from "@zebec-network/admin-sdk";
+
+const service = ZebecStreamAdminService.create("config-name", provider, "mainnet-beta");
+
+// Initialize a new stream config
+const initTx = await service.initializeStreamConfig({
+  feePercentage: 1,
+  feeVault: adminPublicKey,
+  feeTiers: [{ minAmount: 1, maxAmount: 1000, feePercent: 5 }],
+});
+
+// Update an existing stream config
+const updateTx = await service.updateStreamConfig({
+  feePercentage: 8,
+  feeVault: adminPublicKey,
+});
+
+// Whitelist tokens for streaming
+const whitelistTx = await service.whiteListTokens({
+  tokens: [usdcMint, usdtMint],
+});
+
+// Read on-chain data
+const config = await service.getStreamConfigInfo("config-name");
+const tokens = await service.getWhitelistedTokens("config-name");
+const metadata = await service.getStreamMetadataInfo(streamMetadataAddress);
+```
+
+---
+
+### Solana — Staking Admin
+
+```typescript
+import { ZebecStakeAdminService } from "@zebec-network/admin-sdk";
+
+const stakeService = ZebecStakeAdminService.create(provider, "mainnet-beta");
+
+// Initialize a lockup program
+const lockupTx = await stakeService.initLockup({
+  stakeToken: usdcMint,
+  rewardToken: zbcMint,
+  name: "my-lockup",
+  fee: 5,
+  feeVault: adminPublicKey,
+  rewardSchemes: [
+    { lockupDurationDays: 30, rewardRate: 5 },
+    { lockupDurationDays: 90, rewardRate: 12 },
+  ],
+  minimumStake: "1",
+});
+
+// Update an existing lockup
+const updateTx = await stakeService.updateLockup({
+  lockupName: "my-lockup",
+  fee: 7.5,
+  feeVault: adminPublicKey,
+  rewardSchemes: [],
+  minimumStake: "2",
+});
+
+// Read on-chain data
+const lockupInfo = await stakeService.getLockupInfo(lockupAddress);
+const stakeCount = await stakeService.getAllStakesCount(lockupAddress);
+const allStakes = await stakeService.getAllStakesInfo(lockupAddress);
+```
+
+---
+
+### Solana — Card Admin
+
+```typescript
+import { ZebecSolanaCardV2AdminService } from "@zebec-network/admin-sdk";
+
+const cardService = ZebecSolanaCardV2AdminService.create(provider, "mainnet-beta");
+
+// Initialize card configuration
+await cardService.initCardConfig({
+  nativeFee: 1,
+  nonNativeFee: 1.5,
+  revenueFee: 0.5,
+  cardVault: vaultPublicKey,
+  revenueVault: revenuePublicKey,
+  minCardAmount: "10",
+  maxCardAmount: "1500",
+  dailyLimit: "10000",
+});
+
+// Update card config
+await cardService.setCardConfig({
+  nativeFee: 1.2,
+  nonNativeFee: 1.6,
+  revenueFee: 0.6,
+  cardVault: vaultPublicKey,
+  revenueVault: revenuePublicKey,
+  minCardAmount: "10",
+  maxCardAmount: "1500",
+  dailyLimit: "10000",
+});
+
+// Manage custom token fees
+await cardService.setCustomFees({ token: usdcMint, fee: 80 });
+await cardService.deleteCustomFees({ token: usdcMint });
+
+// Read on-chain data
+const config = await cardService.getCardConfigInfo();
+const purchase = await cardService.getCardPurchaseInfo(purchasePda);
+const userRecord = await cardService.getUserPurchaseRecord(userRecordPda);
+const customFees = await cardService.getCustomTokenFees();
+```
+
+---
+
+### Solana — Partner Card Admin
+
+```typescript
+import { ZebecSolanaPartnerAdminCardService } from "@zebec-network/admin-sdk";
+
+const partnerService = ZebecSolanaPartnerAdminCardService.create(
+  "my-partner",
+  provider,
+  "mainnet-beta"
+);
+
+await partnerService.initPartnerCardConfig({ /* params */ });
+await partnerService.setPartnerCardConfig({ /* params */ });
+await partnerService.setPartnerCustomFees({ token: usdcMint, fee: 0.8 });
+await partnerService.deletePartnerCustomFees({ token: usdcMint });
+
+const partnerConfig = await partnerService.getPartnerCardConfigInfo();
+const partnerFees = await partnerService.getPartnerCustomTokenFees();
+```
+
+---
+
+### EVM — Card Admin
+
+```typescript
+import { ZebecCardService, SupportedChain } from "@zebec-network/admin-sdk";
+
+const cardService = new ZebecCardService(signer, SupportedChain.Base);
+
+// Fee configuration
+await cardService.setNativeFee({ feeInPercent: "1" });       // 1%
+await cardService.setNonNativeFee({ feeInPercent: "1.50" });    // 1.5%
+await cardService.setRevenueFee({ feeInPercent: "0.5" });       // 0.5%
+
+// Card limits
+await cardService.setMinCardLimit({ amount: "10" });
+await cardService.setMaxCardLimit({ amount: "1500" });
+await cardService.setDailyLimit({ amount: "10000" });
+
+// Vault addresses
+await cardService.setCardVault({ vault: "0xYourVaultAddress" });
+await cardService.setRevenueVault({ vault: "0xYourRevenueVault" });
+
+// Read config
+const config = await cardService.getCardConfig();
+console.log(config.nativeFee, config.cardVault);
+```
+
+---
+
+### Sui — Card Admin
+
+All Sui operations return a `SuiTransactionPayload` that must be explicitly executed:
+
+```typescript
+import {
+  SuiCardAdminService,
+  SuiSilverCardPackageInfo,
+  createSuiSignTransactionMethodFromSigner,
+} from "@zebec-network/admin-sdk";
+
+const packageInfo = new SuiSilverCardPackageInfo("mainnet");
+const adminService = await SuiCardAdminService.create(packageInfo, suiClient, wallet);
+
+// Fee settings
+await (await adminService.setNativeFee({ feePercent: 1 })).execute();
+await (await adminService.setNonNativeFee({ feePercent: 1.5 })).execute();
+await (await adminService.setRevenueFee({ feePercent: 0.5 })).execute();
+
+// Vault addresses
+await (await adminService.setCardVault({ vaultAddress: "0x..." })).execute();
+await (await adminService.setRevenueVault({ vaultAddress: "0x..." })).execute();
+
+// Card limits
+await (await adminService.setMinCardAmount({ minCardAmount: "10" })).execute();
+await (await adminService.setMaxCardAmount({ maxCardAmount: "1500" })).execute();
+await (await adminService.setDailyLimit({ dailyLimit: "10000" })).execute();
+
+// Token address
+await (await adminService.setUsdcAddress({ usdcAddress: "0x..." })).execute();
+
+// Fee tiers
+await (await adminService.addFeeTier({ minAmount: "0", maxAmount: "1000", fee: 100 })).execute();
+await (await adminService.updateFeeTier({ minAmount: "0", maxAmount: "1000", fee: 120 })).execute();
+await (await adminService.removeFeeTier({ minAmount: "0", maxAmount: "1000" })).execute();
+
+// Swap fees per token type
+await (await adminService.addSwapFee({ tokenType: "0x2::sui::SUI", fee: 200 })).execute();
+await (await adminService.updateSwapFee({ tokenType: "0x2::sui::SUI", fee: 180 })).execute();
+await (await adminService.removeSwapFee({ tokenType: "0x2::sui::SUI" })).execute();
+
+// Read on-chain data (no execution needed)
+const config = await adminService.getCardConfig();
+const feeTiers = await adminService.getFeeTierList();
+const swapFees = await adminService.getSwapFeeList();
+```
+
+---
+
+## API Reference
+
+### ZebecStreamAdminService
+
+Manages payment stream configurations on Solana.
+
+```typescript
+static create(
+  streamConfigName: string,
+  provider: Provider,
+  network: RpcNetwork
+): ZebecStreamAdminService
+```
+
+| Method | Description |
+| ------ | ----------- |
+| `initializeStreamConfig(params)` | Creates a new stream configuration on-chain |
+| `updateStreamConfig(params)` | Updates fee or vault settings on an existing stream config |
+| `whiteListTokens(params)` | Adds tokens to the stream whitelist |
+| `getStreamConfigInfo(configName, commitment?)` | Fetches stream config account data |
+| `getWhitelistedTokens(configName, commitment?)` | Returns all whitelisted token metadata |
+| `getStreamMetadataInfo(streamMetadata, commitment?)` | Fetches stream payment metadata |
+
+---
+
+### ZebecStakeAdminService
+
+Manages staking/lockup programs on Solana.
+
+```typescript
+static create(provider: Provider, network: RpcNetwork): ZebecStakeAdminService
+```
+
+| Method | Description |
+| ------ | ----------- |
+| `initLockup(params)` | Creates a new lockup program with reward schemes |
+| `updateLockup(params)` | Updates lockup fee, vault, or reward settings |
+| `getLockupInfo(lockupAddress)` | Fetches lockup account data |
+| `getAllStakesCount(lockupAddress, commitment?)` | Returns the total number of stakes |
+| `getAllStakesInfo(lockupAddress)` | Returns all individual stake records |
+| `getStakeSignatureForStake(stakeInfo)` | Returns the creation transaction signature for a stake |
+
+---
+
+### ZebecSolanaCardV2AdminService
+
+Manages card configuration and fees on Solana.
+
+```typescript
+static create(provider: Provider, network: "mainnet-beta" | "devnet"): ZebecSolanaCardV2AdminService
+```
+
+| Method | Description |
+| ------ | ----------- |
+| `initCardConfig(params)` | Initializes card config on-chain |
+| `setCardConfig(params)` | Updates card configuration |
+| `setCustomFees(params)` | Sets a custom fee for a specific token |
+| `deleteCustomFees(params)` | Removes a custom fee for a token |
+| `getCardConfigInfo()` | Fetches card configuration |
+| `getCardPurchaseInfo(cardPurchasePda)` | Fetches a specific card purchase record |
+| `getUserPurchaseRecord(userPurchaseRecordPda)` | Fetches a user's purchase history record |
+| `getCustomTokenFees()` | Returns all custom token fee records |
+
+---
+
+### ZebecSolanaPartnerAdminCardService
+
+Manages partner-specific card configuration on Solana.
+
+```typescript
+static create(
+  partnershipName: string,
+  provider: Provider,
+  network: "mainnet-beta" | "devnet"
+): ZebecSolanaPartnerAdminCardService
+```
+
+Exposes the same surface area as `ZebecSolanaCardV2AdminService` prefixed with `partner`:
+`initPartnerCardConfig`, `setPartnerCardConfig`, `setPartnerCustomFees`, `deletePartnerCustomFees`, `getPartnerCardConfigInfo`, `getPartnerCustomTokenFees`, `getCardPurchaseInfo`, `getPartnerUserPurchaseRecord`.
+
+---
+
+### ZebecCardService (EVM)
+
+Manages card configuration on EVM-compatible chains.
+
+```typescript
+constructor(signer: ethers.Signer, chainId: number)
+```
+
+| Method | Description |
+| ------ | ----------- |
+| `setNativeFee(params)` | Sets the native token fee percentage |
+| `setNonNativeFee(params)` | Sets the non-native token fee percentage |
+| `setRevenueFee(params)` | Sets the revenue fee percentage |
+| `setMaxCardLimit(params)` | Sets the maximum card purchase amount |
+| `setMinCardLimit(params)` | Sets the minimum card purchase amount |
+| `setDailyLimit(params)` | Sets the daily purchase limit |
+| `setCardVault(params)` | Sets the card vault address |
+| `setRevenueVault(params)` | Sets the revenue vault address |
+| `getCardConfig()` | Fetches current card configuration |
+
+---
+
+### SuiCardAdminService
+
+Manages card configuration on Sui.
+
+```typescript
+static async create(
+  packageInfo: SuiSilverCardPackageInfo,
+  suiClient: ClientWithCoreApi,
+  wallet: WalletInterface
+): Promise<SuiCardAdminService>
+```
+
+All mutation methods return `Promise<SuiTransactionPayload>` which exposes an `execute()` method.
+
+| Method | Description |
+| ------ | ----------- |
+| `getCardConfig()` | Fetches card configuration object |
+| `getFeeTierList()` | Fetches all fee tiers |
+| `getSwapFeeList()` | Fetches all swap fees |
+| `setNativeFee(params)` | Sets native token fee percent |
+| `setNonNativeFee(params)` | Sets non-native token fee percent |
+| `setRevenueFee(params)` | Sets revenue fee percent |
+| `setCardVault(params)` | Sets card vault address |
+| `setRevenueVault(params)` | Sets revenue vault address |
+| `setMinCardAmount(params)` | Sets minimum card amount |
+| `setMaxCardAmount(params)` | Sets maximum card amount |
+| `setDailyLimit(params)` | Sets daily transaction limit |
+| `setUsdcAddress(params)` | Sets USDC token address |
+| `addFeeTier(params)` | Adds a new fee tier range |
+| `updateFeeTier(params)` | Updates an existing fee tier |
+| `removeFeeTier(params)` | Removes a fee tier |
+| `addSwapFee(params)` | Adds a swap fee for a token type |
+| `updateSwapFee(params)` | Updates a swap fee |
+| `removeSwapFee(params)` | Removes a swap fee |
+
+---
+
+### ProxyStreamAdminService
+
+Manages proxy stream configurations on Solana.
+
+```typescript
+static create(provider: Provider, network: RpcNetwork): ProxyStreamAdminService
+```
+
+---
+
+## Supported Networks
+
+### Solana
+
+| Network | `RpcNetwork` value |
+| ------- | ----------------- |
+| Mainnet Beta | `"mainnet-beta"` |
+| Devnet | `"devnet"` |
+
+### EVM (`SupportedChain` enum)
+
+| Chain | Chain ID |
+| ----- | -------- |
+| Ethereum Mainnet | `1` |
+| Sepolia Testnet | `11155111` |
+| Base | `8453` |
+| BSC | `56` |
+| BSC Testnet | `97` |
+| Polygon | `137` |
+| Polygon Amoy | `80002` |
+| Odyssey | `153153` |
+| Odyssey Testnet | `131313` |
+
+### Sui
+
+| Network | `SuiNetwork` value |
+| ------- | ----------------- |
+| Mainnet | `"mainnet"` |
+| Devnet | `"devnet"` |
+| Testnet | `"testnet"` |
+
+---
+
+## Types
+
+Key types exported from the package:
+
+```typescript
+// Network
+type RpcNetwork = "mainnet-beta" | "devnet";
+type SuiNetwork = "mainnet" | "devnet" | "testnet";
+
+// Solana stream
+type StreamConfigInfo
+type StreamMetadataInfo
+type TokenMetadata
+type StreamFeeTier
+type InitializeStreamConfigParams
+type UpdateStreamConfigParams
+type WhiteListTokensParams
+
+// Solana staking
+type LockupInfo
+type StakeInfo
+type RewardScheme
+type InitLockupInstructionData
+type UpdateLockupInstructionData
+
+// Solana card
+type CardConfigInfo
+type PartnerCardConfigInfo
+type CardPurchaseInfo
+type UserPurchaseRecordInfo
+type TokenFeeRecord
+type CardFeeTier
+type InitCardConfigParams
+type SetCardConfigParams
+type SetCustomFeesParams
+type DeleteCustomFeesParams
+
+// EVM card
+type EvmCardConfig
+type CardPurchaseOfDay
+
+// Sui card
+type SuiCardConfig
+type SuiFeeTier
+type SuiFeeTierList
+type SuiSwapFee
+type SuiSwapFeeList
+type WalletInterface
+type SuiSignTransactionMethod
+type SuiTransactionPayload
+
+// Shared
+type Numeric = string | number
+type Address          // blockchain address string
+type DecimalString    // decimal value as string
+type Percent          // percentage value
+```
+
+---
+
+## Utilities
+
+### `createSuiSignTransactionMethodFromSigner`
+
+Creates a `SuiSignTransactionMethod` compatible wallet adapter from a Sui keypair or signer.
+
+```typescript
+import { createSuiSignTransactionMethodFromSigner } from "@zebec-network/admin-sdk";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+
+const keypair = Ed25519Keypair.fromSecretKey(secretKey);
+const signTransaction = createSuiSignTransactionMethodFromSigner(keypair);
+// Pass signTransaction into WalletInterface
+```
+
+### `getCoinDecimals`
+
+Fetches decimal precision for a Sui coin type.
+
+```typescript
+import { getCoinDecimals } from "@zebec-network/admin-sdk";
+
+const decimals = await getCoinDecimals(suiClient, "0x2::sui::SUI");
+// => 9
+```
+
+### PDA Derivation (Solana)
+
+Helper functions for deriving Program Derived Addresses:
+
+```typescript
+import {
+  deriveStreamConfigPda,
+  deriveCardConfigPda,
+  deriveLockupAddress,
+  deriveStakeVaultAddress,
+  deriveCardPurchasePda,
+} from "@zebec-network/admin-sdk";
+```
+
+---
+
+## Environment Setup
+
+Copy `.env.example` and fill in your credentials:
+
+```bash
+cp .env.example .env
+```
+
+```dotenv
+# Solana
+MAINNET_SECRET_KEYS=     # Admin keypair secret keys (mainnet)
+DEVNET_SECRET_KEYS=      # Admin keypair secret keys (devnet)
+RPC_URL=                 # Solana mainnet RPC endpoint
+DEVNET_RPC_URL=          # Solana devnet RPC endpoint
+
+# Sui
+SUI_SECRET_KEYS=         # Sui admin keypair secret keys
+HOP_API_KEY=             # Hop bridge API 
+
+# EVM
+EVM_PRIVATE_KEYS=        # Admin private keys
+SEPOLIA_RPC_URL=         # Sepolia rpc url
+BSC_RPC_URL=             # Bsc rpc url   
+BASE_RPC_URL=            # Base rpc url
+ODYSSEY_RPC_URL=         # Odyssey rpc url
+BSC_TESTNET_RPC_URL=     # Bsc testnet rpc url
+ONE_INCH_AUTH_TOKEN=     # 1inch auth token
+ETHEREUM_RPC_URL=        # Ethereum rpc url
+ODYSSEY_TESTNET_RPC_URL= # Odyssey testnet rpc url
+POLYGON_AMOY_RPC_URL=    # Polygon amoy rpc url
+POLYGON_RPC_URL=         # Polygon rpc url
+```
+
+---
+
+## Folder Structure
+
+```text
+zebec-admin-sdk/
+├── src/
+│   ├── artifacts/              # Smart contract definitions
+│   │   ├── abi/                # EVM contract ABIs (JSON)
+│   │   ├── typechain-types/    # Generated TypeChain EVM types
+│   │   ├── zebec_stream.ts     # Solana stream program IDL
+│   │   ├── zebec_stake_v1.ts   # Solana staking program IDL
+│   │   ├── zebec_instant_card.ts  # Solana card program IDL
+│   │   ├── zebec_proxy_stream.ts  # Solana proxy stream IDL
+│   │   └── index.ts
+│   ├── services/
+│   │   ├── streamServices.ts       # ZebecStreamAdminService
+│   │   ├── stakingService.ts       # ZebecStakeAdminService
+│   │   ├── solanaCardV2Service.ts  # Solana card services
+│   │   ├── evmCardService.ts       # ZebecCardService (EVM)
+│   │   ├── suiCardService.ts       # SuiCardAdminService
+│   │   ├── proxyStreamService.ts   # ProxyStreamAdminService
+│   │   └── index.ts
+│   ├── constants.ts            # Network addresses and chain configs
+│   ├── types.ts                # TypeScript type definitions
+│   ├── utils.ts                # Utility functions
+│   ├── pda.ts                  # Solana PDA derivation helpers
+│   └── index.ts                # Public entry point
+├── test/
+│   ├── setup.ts                # Test keypair and client setup
+│   └── sui/                    # Sui integration tests
+├── .env.example
+├── biome.json                  # Linter / formatter config
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+## Scripts
+
+| Script | Command | Description |
+| ------ | ------- | ----------- |
+| Build | `yarn build` | Compiles TypeScript to `dist/` |
+| Clean | `yarn clean` | Removes the `dist/` directory |
+| Test | `yarn test` | Runs all integration tests via Mocha |
+| Generate TypeChain | `yarn gen:typechain` | Regenerates TypeChain types from EVM ABIs in `src/artifacts/abi/` |
+
+### Build
+
+```bash
+yarn build
+```
+
+Runs `clean` then `tsc`. Output goes to `dist/` as ESM modules.
+
+### Test
+
+```bash
+yarn test
+```
+
+Runs `ts-mocha` against `test/**/*.test.ts`. Tests are integration tests that hit live RPC endpoints — ensure your `.env` is configured before running.
+
+### Generate TypeChain Types
+
+```bash
+yarn gen:typechain
+```
+
+Re-generates TypeScript types from ABI JSON files in `src/artifacts/abi/`. Run this after updating any EVM contract ABI.
+
+---
+
+## License
+
+MIT — © Zebec Network