@oaknetwork/contracts v1.0.0#85
Merged
mahabubAlahi merged 39 commits intomainfrom Mar 31, 2026
Merged
Conversation
Merge main into develop
- Updated `package.json` to use `tsup` for building and added module exports. - Changed TypeScript module resolution to `bundler` and updated module target to `ES2022`. - Introduced `tsup.config.ts` for build configuration.
- Introduced a new constant `CHAIN_IDS` to define common chain IDs for various Celo networks, including CELO_SEPOLIA and ALFAJORES, to facilitate contract client creation.
- Added a new `index.ts` file to define the `createOakContractsClient` function, which supports both simple and full configuration for creating a client instance. - Included utility functions for client configuration and chain resolution, along with type guards for better type safety. - The client allows interaction with various contract entities such as global parameters, campaign info, and treasury factories.
- Expanded `client.ts` with new interfaces for campaign data, payment structures, and treasury configurations to improve type safety and clarity. - Consolidated protocol types in `index.ts` to streamline exports and reduce circular dependencies. - Introduced `SimpleOakContractsClientConfig` and `FullOakContractsClientConfig` for flexible client configuration options.
- Introduced Celo Sepolia testnet to the chain registry, enhancing support for Celo networks. - Updated import paths for `defineChain`, `mainnet`, `sepolia`, and `goerli` to use the new structure from the `viem` package. - Re-exported `CHAIN_IDS` from constants for simplified client configuration.
- Removed the `client.ts` file as part of the restructuring. - Added multiple new contract entities including `AllOrNothing`, `CampaignInfoFactory`, `CampaignInfo`, `GlobalParams`, `ItemRegistry`, `KeepWhatsRaised`, `PaymentTreasury`, and `TreasuryFactory` to enhance functionality and modularity. - Updated `index.ts` to export the new contract entities for easier access. - Improved type safety and clarity in contract interactions by defining specific entity functions for read/write operations.
- Introduced a comprehensive README.md file for the @oaknetwork/contracts package. - Documented installation instructions, quick start guide, client configuration options, supported chain IDs, and detailed contract functionalities. - Enhanced clarity and usability for developers interacting with Oak Network smart contracts.
Merge main into develop
- Enhanced `AllOrNothing` ABI by adding new functions `cancelTreasury` and `cancelled`, and modified event names and input types for better clarity. - Updated `CampaignInfo` ABI to include the `_cancelCampaign` function and removed outdated ownership transfer events. - Refined `KeepWhatsRaised` ABI by adding `cancelTreasury` and `cancelled` functions, and corrected event names for consistency. - Adjusted `PaymentTreasury` ABI to include an `initialize` function for contract setup. - Cleaned up `GlobalParams` ABI by removing redundant input parameters for error handling functions.
- Updated `getplatformFeePercent` to `getPlatformFeePercent` in both `AllOrNothing` and `KeepWhatsRaised` contracts for consistency and adherence to naming conventions.
- Added multiple error classes for `AllOrNothing`, `CampaignInfo`, `KeepWhatsRaised`, `ItemRegistry`, `PaymentTreasury`, `Shared`, and `TreasuryFactory` to enhance error handling and provide clearer recovery hints. - Updated `index.ts` to export the new error types for better accessibility across the contracts. - Improved type safety and clarity in error management for contract interactions.
- Updated `getplatformFeePercent` to `getPlatformFeePercent` in `AllOrNothingTreasuryEntity` and `KeepWhatsRaisedTreasuryEntity` interfaces for consistency and adherence to naming conventions.
…74) * fix: add missing function implementations to contract entities - Introduced `cancelled` and `cancelTreasury` functions in `AllOrNothing` and `KeepWhatsRaised` contracts. - Added `cancelCampaign` function in `CampaignInfo` contract. - Updated corresponding types in `client.ts` to reflect the new functionalities. * fix: update account handling in wallet client creation - Refactored the account assignment in the `createWallet` function to utilize `privateKeyToAccount` for improved clarity and correctness. - Removed redundant account extraction from the wallet client, streamlining the wallet creation process. * fix: standardize function name casing in PaymentTreasuryEntity - Updated function names from `getplatformHash` and `getplatformFeePercent` to `getPlatformHash` and `getPlatformFeePercent` for consistency and adherence to naming conventions in both the contract and type definitions. * refactor: remove ResolvedOakContractsClientConfig interface - Eliminated the `ResolvedOakContractsClientConfig` interface from `client.ts` to streamline the type definitions and improve clarity in client configuration handling. * refactor: enhance client configuration with timeout options - Updated the `buildClients` function to accept a new `options` parameter, allowing for customizable request timeouts in HTTP transport calls and transaction receipt waits. - Adjusted the default timeout value in `OakContractsClientOptions` from 3000ms to 30000ms for improved reliability in client operations. * feat: add error module to contract package - Introduced a new module for error handling in the contracts package by adding `errors` to the package.json and tsup.config.ts files. - Updated the build configuration to include the new `errors/index.ts` entry point for better organization and accessibility of error-related functionalities. * refactor: remove keccak256 export from contracts index - Eliminated the `keccak256` export from the `index.ts` file in the contracts package to streamline the module exports and improve clarity. * refactor: improve type definitions in wallet client functions - Updated the `createBrowserProvider` and `getSigner` functions to use `EIP1193Provider` instead of `any` for the `ethereum` parameter, enhancing type safety and clarity in the wallet client implementation. - Adjusted the transport handling in `createWallet` to utilize the `custom` transport method for better compatibility with various providers. * feat: keep Jest config loadable after switching package to ESM * refactor: update chain ID naming and usage in client configuration - Changed the chain ID from `CHAIN_IDS.CELO_SEPOLIA` to `CHAIN_IDS.CELO_TESTNET_SEPOLIA` in the client example for clarity. - Updated the chain ID constants to follow a new naming convention, distinguishing between mainnet and testnet. - Added `Celo Mainnet` definition to the chain registry for improved clarity and organization. * refactor: update chain ID references in README for clarity - Changed all instances of `CHAIN_IDS.CELO_SEPOLIA` to `CHAIN_IDS.CELO_TESTNET_SEPOLIA` in the README to reflect the correct testnet configuration. - Updated chain ID constants to better differentiate between mainnet and testnet environments, enhancing documentation accuracy. * refactor: remove deprecated entities files - It's unreferenced dead code and its functionality is already covered by `contracts/` * refactor: simplify transport handling in createWallet function * refactor: streamline transport initialization in createWallet function * refactor: enhance configuration validation in isSimpleConfig function - Improved type checks for the `chainId`, `rpcUrl`, and `privateKey` properties in the `isSimpleConfig` function to ensure they meet specific criteria, enhancing type safety and configuration reliability. * refactor: remove legacy Celo testnet constant from chain IDs - Deleted the `CELO_TESTNET_ALFAJORES` constant from the `CHAIN_IDS` to eliminate outdated references and encourage the use of `CELO_TESTNET_SEPOLIA` for new development.
- Revised chain ID documentation in README to include new mainnet and testnet identifiers for Ethereum and Celo. - Updated contract method calls to improve clarity, including renaming parameters for consistency and adding message handling for campaign and treasury functions. - Enhanced item registry methods to accept structured item data for better usability.
* feat: introduce new client structure and utility functions - Added `create.ts` to implement the `createOakContractsClient` function, enabling the creation of a new Oak Contracts SDK client instance with configuration options. - Introduced `guard.ts` for type guarding simple client configurations, ensuring proper structure validation. - Created `resolve.ts` to handle client construction, including resolving chain identifiers and building public and wallet clients. - Established `types.ts` to define various client configuration types and options, enhancing type safety and clarity in client interactions. - Updated `index.ts` to export the new client functionalities and types, streamlining access for SDK consumers. * feat: add constants for chain IDs, encoding, and fees - Introduced `chains.ts` to define a registry of chain IDs for Ethereum and Celo networks. - Added `encoding.ts` with a sentinel value for zero bytes32. - Created `fees.ts` to establish a basis-points denominator for fee calculations. - Updated `index.ts` to re-export the new constants and registry helpers for streamlined access. * feat: implement AllOrNothing treasury contract functionalities - Added `abi.ts` to define the ABI for the AllOrNothing treasury contract, including error types and event definitions. - Created `events.ts` for event filter factories and log decoding stubs. - Developed `reads.ts` to implement read methods for the treasury contract, allowing access to raised amounts, rewards, and NFT ownership. - Introduced `writes.ts` to handle write operations such as pausing the treasury, adding rewards, and processing pledges. - Implemented `simulate.ts` for simulating write calls, enhancing error handling during contract interactions. - Defined types in `types.ts` for structured access to read/write methods and event helpers, ensuring type safety and clarity in contract interactions. - Updated `index.ts` to export the new functionalities, providing a comprehensive interface for the AllOrNothing treasury entity. * feat: implement CampaignInfo contract functionalities - Added `abi.ts` to define the ABI for the CampaignInfo contract, including error types and event definitions. - Created `events.ts` for event helper functions related to the CampaignInfo contract. - Developed `reads.ts` to implement read methods for accessing campaign data such as launch time, deadline, and goal amount. - Introduced `writes.ts` to handle write operations like updating deadlines and goal amounts. - Implemented `simulate.ts` for simulating write calls, enhancing error handling during contract interactions. - Defined types in `types.ts` for structured access to read/write methods and event helpers, ensuring type safety. - Updated `index.ts` to export the new functionalities, providing a comprehensive interface for the CampaignInfo entity. * feat: implement CampaignInfoFactory contract functionalities - Added `abi.ts` to define the ABI for the CampaignInfoFactory contract, including error types and event definitions. - Created `events.ts` for event helper functions related to the CampaignInfoFactory contract. - Developed `reads.ts` to implement read methods for accessing campaign data. - Introduced `writes.ts` to handle write operations for creating campaigns and updating implementations. - Implemented `simulate.ts` for simulating write calls, enhancing error handling during contract interactions. - Defined types in `types.ts` for structured access to read/write methods and event helpers, ensuring type safety. - Updated `index.ts` to export the new functionalities, providing a comprehensive interface for the CampaignInfoFactory entity. * feat: implement GlobalParams contract functionalities - Added `abi.ts` to define the ABI for the GlobalParams contract, including error types and event definitions. - Created `events.ts` for event helper functions related to the GlobalParams contract. - Developed `reads.ts` to implement read methods for accessing global parameters. - Introduced `writes.ts` to handle write operations for managing platforms and their data. - Implemented `simulate.ts` for simulating write calls, enhancing error handling during contract interactions. - Defined types in `types.ts` for structured access to read/write methods and event helpers, ensuring type safety. - Updated `index.ts` to export the new functionalities, providing a comprehensive interface for the GlobalParams entity. * refactor: enhance documentation and clarity in AllOrNothing contract methods - Updated parameter descriptions in `events.ts`, `reads.ts`, `writes.ts`, `simulate.ts`, and `index.ts` to specify that the contract address is the deployed AllOrNothing contract address. - Improved clarity in method descriptions to better reflect their functionalities and usage, ensuring consistency across the contract interface. * refactor: enhance documentation for CampaignInfo contract methods - Updated parameter descriptions in `events.ts`, `reads.ts`, `writes.ts`, `simulate.ts`, and `index.ts` to clarify that the contract address refers to the deployed CampaignInfo contract address. - Improved method descriptions to better reflect their functionalities and ensure consistency across the contract interface. * refactor: improve documentation for CampaignInfoFactory contract methods - Updated parameter descriptions in `events.ts`, `reads.ts`, `writes.ts`, `simulate.ts`, and `index.ts` to clarify that the contract address refers to the deployed CampaignInfoFactory contract address. - Enhanced method descriptions to provide clearer insights into their functionalities and ensure consistency across the contract interface. * refactor: improve documentation for GlobalParams contract methods - Enhanced parameter descriptions in `events.ts`, `reads.ts`, `writes.ts`, `simulate.ts`, and `index.ts` to clarify that the contract address refers to the deployed GlobalParams contract address. - Updated method descriptions to provide clearer insights into their functionalities and ensure consistency across the contract interface. * feat: implement ItemRegistry contract functionalities - Added `abi.ts` to define the ABI for the ItemRegistry contract, including error types and event definitions. - Created `events.ts` for event helper functions related to the ItemRegistry contract. - Developed `reads.ts` to implement read methods for accessing item data. - Introduced `writes.ts` to handle write operations for registering items. - Implemented `simulate.ts` for simulating write calls, enhancing error handling during contract interactions. - Defined types in `types.ts` for structured access to read/write methods and event helpers, ensuring type safety. - Updated `index.ts` to export the new functionalities, providing a comprehensive interface for the ItemRegistry entity. * feat: implement KeepWhatsRaised treasury contract functionalities - Added `abi.ts` to define the ABI for the KeepWhatsRaised contract, including error types and event definitions. - Created `events.ts` for event helper functions related to the KeepWhatsRaised contract. - Developed `reads.ts` to implement read methods for accessing treasury data. - Introduced `writes.ts` to handle write operations for managing pledges and rewards. - Implemented `simulate.ts` for simulating write calls, enhancing error handling during contract interactions. - Defined types in `types.ts` for structured access to read/write methods and event helpers, ensuring type safety. - Updated `index.ts` to export the new functionalities, providing a comprehensive interface for the KeepWhatsRaised entity. * feat: implement PaymentTreasury contract functionalities - Added `abi.ts` to define the ABI for the PaymentTreasury contract, including error types and event definitions. - Created `events.ts` for event helper functions related to the PaymentTreasury contract. - Developed `reads.ts` to implement read methods for accessing treasury data. - Introduced `writes.ts` to handle write operations for managing payments and refunds. - Implemented `simulate.ts` for simulating write calls, enhancing error handling during contract interactions. - Defined types in `types.ts` for structured access to read/write methods and event helpers, ensuring type safety. - Updated `index.ts` to export the new functionalities, providing a comprehensive interface for the PaymentTreasury entity. * feat: implement TreasuryFactory contract functionalities - Added `abi.ts` to define the ABI for the TreasuryFactory contract, including error types and event definitions. - Created `events.ts` for event helper functions related to the TreasuryFactory contract. - Developed `reads.ts` to implement read methods for accessing treasury data, returning an empty object as there are no public read functions in the ABI. - Introduced `writes.ts` to handle write operations for managing treasury implementations. - Implemented `simulate.ts` for simulating write calls, enhancing error handling during contract interactions. - Defined types in `types.ts` for structured access to read/write methods and event helpers, ensuring type safety. - Updated `index.ts` to export the new functionalities, providing a comprehensive interface for the TreasuryFactory entity. * refactor: enhance documentation for isSimpleConfig type guard - Updated the JSDoc comment for the isSimpleConfig function to clarify its purpose and parameters, specifying that it narrows an OakContractsClientConfig to a SimpleOakContractsClientConfig and detailing the expected structure of the config object. * feat: introduce error handling for contract operations - Added a base interface for contract errors to standardize error handling across contracts. - Implemented specific error classes for AllOrNothing, CampaignInfoFactory, CampaignInfo, GlobalParams, ItemRegistry, KeepWhatsRaised, PaymentTreasury, and shared errors, enhancing clarity and consistency in error reporting. - Updated index files to export new error types, ensuring comprehensive access to error handling functionalities across the contract suite. * feat: add initial metrics functionality for campaign, platform, and treasury - Introduced new files for campaign, platform, and treasury metrics, each providing stubs for future implementation. - Added type definitions for PlatformStats, CampaignSummary, and TreasuryReport to facilitate cross-contract aggregation. - Updated index file to export new metrics functions and types, establishing a public interface for the metrics module. * refactor: streamline error handling in parse-contract-error.ts - Removed redundant error imports and functions to simplify the error handling structure. - Consolidated error handling logic, enhancing maintainability and readability of the code. - Updated the file to focus on essential error types, improving clarity in contract error management. * feat: add scripts for ABI management - Introduced `check-abis.ts` to implement a CI check for detecting ABI drift between compiled artifacts and SDK source. - Added `generate-abis.ts` to extract ABIs from compiled Solidity artifacts into the appropriate SDK structure. - Both scripts currently contain stubs for future implementation, ensuring a framework for maintaining ABI consistency. * feat: update type definitions for campaign and treasury contracts - Refactored type exports in index.ts to focus on cross-contract type definitions, removing client dependencies. - Introduced new params.ts file containing input parameter interfaces for campaign creation and treasury configuration. - Added structs.ts file with detailed on-chain struct mirrors for campaign data, rewards, and payment items, enhancing type safety and clarity in contract interactions. * feat: add utility functions for account management, hashing, and time operations - Introduced `requireAccount` to ensure a wallet client has an attached account, throwing an error if not. - Added `keccak256` and `id` functions for hashing strings and generating event topics using keccak256. - Implemented `isHex` and `toHex` functions for hex string validation and encoding. - Created time utility functions `getCurrentTimestamp` and `addDays` for timestamp manipulation. - Updated `index.ts` to export new utility functions, enhancing the utility module's functionality. * refactor: remove deprecated contract files and associated functionalities - Deleted multiple contract files including AllOrNothing, CampaignInfoFactory, CampaignInfo, GlobalParams, ItemRegistry, KeepWhatsRaised, PaymentTreasury, TreasuryFactory, and their error handling counterparts. - This cleanup is part of a broader effort to streamline the codebase and remove unused or outdated components, enhancing maintainability and clarity. * refactor: update index.ts to streamline exports and enhance modularity - Modified exports in index.ts to include new types and functions from the lib module, improving the organization of contract-related functionalities. - Removed direct imports from viem, consolidating dependencies and enhancing maintainability of the codebase. * chore: add metrics and constants modules to contract package - Updated package.json to include new metrics and constants modules, enhancing the modular structure of the contract package. - Modified tsup.config.ts to add entry points for the new metrics and constants modules, facilitating their inclusion in the build process.
…ractions - Added `index.ts` and `provider.ts` in the `packages/contracts/src/lib/viem` directory to facilitate interaction with viem's public and wallet clients. - Introduced `createJsonRpcProvider`, `createWallet`, and `createBrowserProvider` functions for creating various provider instances. - Implemented `getSigner` function to retrieve a wallet client from a browser provider. - Created a new `privy` module with a placeholder for future implementation of a Privy wallet adapter. - Updated `.gitignore` to exclude specific directories while allowing the new contracts library to be tracked.
- Deleted multiple contract files including AllOrNothing, CampaignInfoFactory, CampaignInfo, GlobalParams, ItemRegistry, KeepWhatsRaised, PaymentTreasury, TreasuryFactory, and their error handling counterparts.
* Enhance error handling in contract operations - Updated `getRevertData` function in `parse-contract-error.ts` to include support for retrieving raw error data from contract errors. - Modified `decodeErrorArgs` function in `shared.ts` to ensure that decoded arguments are converted to strings when they are of type bigint, improving usability and consistency in error handling. * Fix test file error - add initial contract test structure and placeholder for future tests * Update README and enhance error handling in contract operations - Renamed `getAvailableRaisedAmount` to `getTotalAvailableRaisedAmount` for clarity in the README. - Improved error handling in the `handleError` function by checking for typed SDK errors before extracting raw revert data, enhancing the robustness of error reporting. * Enhance validation in isSimpleConfig and improve documentation - Updated the isSimpleConfig function to include additional validation for the privateKey, ensuring it is a valid 66-character hex string. - Enhanced JSDoc comments in the scopedToPlatform function to provide usage examples and clarify its parameters. - Marked the generateAbis function as internal in the documentation to indicate its intended usage. * Add read-only client support and per-entity signer override (#81) * Refactor isSimpleConfig for improved validation and error handling - Enhanced the isSimpleConfig function to include more robust validation for the privateKey, ensuring it is a valid 66-character hex string. - Updated JSDoc comments to clarify the function's purpose, parameters, and error handling behavior, providing better documentation for users. * Enhance OakContractsClient with read-only configuration support and entity signer options - Introduced `SimpleReadOnlyOakContractsClientConfig` to support read-only clients with chainId and rpcUrl. - Updated `OakContractsClient` methods to accept optional `EntitySignerOptions`, allowing per-entity signer overrides. - Enhanced `buildClients` function to handle read-only clients, returning a null walletClient. - Added `requireSigner` utility to ensure a non-null WalletClient is provided for write operations, improving error handling. * Refactor contract functions to support nullable walletClient - Updated multiple contract functions across various modules to accept `walletClient` as `WalletClient | null`, enhancing flexibility in client usage. - Replaced instances of `requireAccount` with `requireSigner` to ensure proper handling of nullable wallet clients, improving error management during contract interactions. - Adjusted simulation and write functions to accommodate the new wallet client structure, ensuring consistent behavior across contract operations. * Update README to reflect new client configuration patterns - Revised the README to include three new client configuration patterns for the OakContractsClient: Simple, Read-only, and Per-entity signer override. - Enhanced documentation with code examples for each pattern, clarifying usage and expected behavior. * Enhance isReadOnlySimpleConfig validation and error handling - Improved the isReadOnlySimpleConfig function to validate that chainId is a number and rpcUrl is a non-empty string, throwing errors for invalid inputs. * Refactor isReadOnlySimpleConfig for improved field validation - Updated the isReadOnlySimpleConfig function to use type casting for better validation of read-only fields, ensuring that privateKey, chain, provider, and signer are explicitly checked for null values. - Add read-only client support and per-entity signer override #81
* Add CallSignerOptions interface for per-call signer overrides - Introduced a new `CallSignerOptions` interface in `types.ts` to allow optional signer overrides for individual contract calls, enhancing flexibility in client interactions. * Enhance contract methods with optional signer overrides - Updated various contract methods across AllOrNothing, CampaignInfo, CampaignInfoFactory, and GlobalParams to accept an optional `CallSignerOptions` parameter, allowing for per-call signer customization. - This change improves flexibility in contract interactions, enabling users to specify different signers for individual operations. * Update README to reflect new signer configuration patterns - Revised the README to include four distinct signer configuration patterns for the OakContractsClient, enhancing clarity on how to mix and match configurations for different use cases. - Added detailed examples for each pattern, including per-entity and per-call signer overrides, to improve user understanding and facilitate better contract interactions.
test(contracts): add comprehensive unit and integration test suite for @oaknetwork/contracts
…rerequisites, and detailed contract entity descriptions
…reasury variants - In README and code comments. Clarified SDK method compatibility and added detailed descriptions for both treasury types, ensuring users understand time constraints and usage. Updated relevant interfaces and methods to reflect these changes.
* feat: enhance contract simulations - Added new simulation methods for AllOrNothing contract: pauseTreasury, unpauseTreasury, cancelTreasury, addRewards, removeReward, burn, approve, setApprovalForAll, safeTransferFrom, and transferFrom. - Expanded CampaignInfo contract simulations with setImageURI, updateContractURI, unpauseCampaign, setPlatformInfo, transferOwnership, and renounceOwnership methods. - Updated corresponding types to reflect the new simulation methods in AllOrNothing and CampaignInfo contracts. - Introduced similar ownership transfer and renouncement methods in GlobalParams and CampaignInfoFactory contracts. * test: add ownership transfer and new simulation methods - Introduced tests for ownership transfer and renouncement in GlobalParams, CampaignInfoFactory, and CampaignInfo contracts. - Added new simulation methods for CampaignInfo: setImageURI, updateContractURI, unpauseCampaign, and setPlatformInfo. - Enhanced AllOrNothing contract tests with pauseTreasury, unpauseTreasury, cancelTreasury, addRewards, removeReward, burn, approve, setApprovalForAll, safeTransferFrom, and transferFrom methods. - Updated existing tests to ensure comprehensive coverage of new functionalities. * Refactor streamline simulation methods and imports - Consolidated import statements in various simulation files to enhance clarity and reduce redundancy. - Updated simulation methods across multiple contracts to utilize `simulateWithErrorDecode` for error handling, replacing `parseContractError`. - Renamed and reorganized methods in the CampaignInfo contract to improve consistency and readability, including updates to `setImageURI`, `updateContractURI`, and `pauseCampaign`. - Adjusted types in the CampaignInfo and KeepWhatsRaised contracts to reflect the new method signatures and ensure type safety. * Update event test description for clarity - Renamed the test description for the GlobalParams entity to clarify that the events object is expected to be empty.
Oak Contracts SDK
tahseen-ccprotocol
requested review from
devmahmud,
mahabubAlahi and
rayedsikder
Add MIT license information to README
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a9506c982f
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
mahabubAlahi
approved these changes
Mar 31, 2026
devmahmud
approved these changes
Mar 31, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Oak Contracts SDK (
@oaknetwork/contracts)A fully typed TypeScript SDK for interacting with Oak Network on-chain smart contracts via viem. Provides read/write/simulate access to all Oak protocol contracts with structured error handling, chain support, and a composable entity architecture.
What's included
Package & build
viemonly (^2.23.0) — minimal footprintdts: true, no splitting, clean);tsup.config.tswith multi-entry pointsmoduleResolution: "bundler", targetES2022"type": "module"), published files:dist/only.,./client,./contracts,./utils,./errors,./metricsClient & configuration
createOakContractsClient(config)— single entry point supporting three modes:{ chainId, rpcUrl }— writes/simulations throw{ chainId, rpcUrl, privateKey }— standard usage{ chain, provider, signer }— BYO viem clientsEntitySignerOptions) → per-call (CallSignerOptions)CHAIN_IDSfor Ethereum Mainnet, Celo Mainnet, Ethereum Sepolia, Ethereum Goerli, and Celo Sepolia;getChainFromId()with fallback for unknown chain IDswaitForReceipt(txHash)— convenience method on the client for transaction confirmationisSimpleConfig(),isReadOnlySimpleConfig()with strict validationContract entities (8 contracts)
Each entity follows the composition pattern with
abi.ts,reads.ts,writes.ts,simulate.ts,events.ts,types.ts, andindex.ts:createGlobalParamsEntitycreateCampaignInfoFactoryEntitycreateCampaignInfoEntitycreateTreasuryFactoryEntitycreatePaymentTreasuryEntitycreateAllOrNothingEntitycreateKeepWhatsRaisedEntitycreateItemRegistryEntityTypes
SimpleOakContractsClientConfig,SimpleReadOnlyOakContractsClientConfig,FullOakContractsClientConfig,EntitySignerOptions,CallSignerOptions,OakContractsClientCampaignData,TieredReward,LineItem,Item,PaymentLineItem,ExternalFees,PaymentData,PermitParams,LineItemTypeInfo,CampaignConfigCreateCampaignData,CreateCampaignParams,KeepWhatsRaisedConfig,KeepWhatsRaisedFeeKeys,KeepWhatsRaisedFeeValuesError handling (82+ typed error classes)
ContractErrorBaseinterface:parseContractError(error)— decodes on-chain revert data into typed error classes via per-contract parsersgetRevertData(error)— extracts raw revert bytes, walks cause chainssimulateWithErrorDecode(...)— simulates a transaction and decodes any revert into a typed errorgetRecoveryHint(error)— returns human-readable recovery suggestionsConstants
CHAIN_IDS— supported chain ID mappingBPS_DENOMINATOR(10_000n) — basis points mathBYTES32_ZERO— zero-value bytes32DATA_REGISTRY_KEYS— protocol registry key hashes (BUFFER_TIME,MAX_PAYMENT_EXPIRATION,CAMPAIGN_LAUNCH_BUFFER,MINIMUM_CAMPAIGN_DURATION)scopedToPlatform()— deterministic platform-scoped key hashingUtilities
requireSigner/requireAccount— guards for write/simulate operationsgetChainFromId— chain resolution with fallbackkeccak256,id— hashing helpersisHex,toHex— hex encoding/validationgetCurrentTimestamp,addDays— time utilities for on-chain timestampsViem re-exports (
@oaknetwork/contracts)Thin re-exports for common viem utilities so consumers don't need a separate
viemimport for basic operations:createPublicClient,createWalletClient,http,parseEther,formatEther,isAddress,getAddress,defineChain,privateKeyToAccount, and more.Provider helpers:
createJsonRpcProvider,createWallet,createBrowserProvider,getSigner.Metrics (stub —
@oaknetwork/contracts/metrics)getPlatformStats,getCampaignSummary,getTreasuryReport— placeholder implementations (return{})PlatformStats,CampaignSummary,TreasuryReport@oaknetwork/contracts/metricsTesting
.envwithRPC_URL,PRIVATE_KEY, deployed addresses)pnpm testruns unit tests only (safe for CI);pnpm test:integrationfor live chain testingindex.tsexcluded from coverage collectionCI integration
Documentation