Contracts SDK v1.2#109
Merged
mahabubAlahi merged 94 commits intomainfrom Apr 17, 2026
Merged
Conversation
…code for better simulation handling
…ite and toPreparedTransaction functions
…r error handling and response management
…for improved error handling
…tion utilities for enhanced transaction handling
- Reduce README from ~1,100 lines to ~430 lines by replacing exhaustive API listings with a summary table and doc links. - Add documentation for new client features: getReceipt(), SimulationResult return type, prepareContractWrite/toPreparedTransaction utilities, and ABI exports.
…d improve error handling - Refactor simulateContract response handling to utilize structured request fields (address, abi, functionName, args) instead of raw to/data fields. - Enhance toSimulationResult function to encode calldata from the new request structure. - Update unit tests to reflect changes in request structure and expected results.
- Modify the toPreparedTransaction function to preserve undefined gas values instead of defaulting to 0n. - Update unit tests to reflect the new behavior of gas handling in prepared transactions.
- Add step-by-step examples covering the complete platform onboarding flow: enlistment, verification, treasury implementation registration, and approval. - Include optional configuration steps for line item types, claim delays, platform data keys, and protocol admin functions. - Document the process in a README with roles, responsibilities, and a role reference table from the smart contract.
- Add a comprehensive set of examples demonstrating the all-or-nothing crowdfunding process, including campaign creation, treasury deployment, reward management, backer pledges, and monitoring campaign progress. - Include functionality for fee disbursement, fund withdrawal upon success, and refund claims upon failure. - Document the entire flow in a README, outlining roles, responsibilities, and a reference table for smart contract functions.
- Add a complete set of examples demonstrating the Keep-What's-Raised crowdfunding process, including campaign creation, treasury deployment, reward management, backer pledges, and monitoring campaign progress. - Include functionality for partial and final withdrawals, fee disbursement, and refund claims. - Document the entire flow in a README, outlining roles, responsibilities, and a reference table for smart contract functions.
- Add a complete set of examples demonstrating the e-commerce payment process, including treasury setup, payment creation, crypto payment processing, payment confirmation, and refund handling. - Include functionality for reading payment and treasury data, disbursing fees, withdrawing funds, and claiming expired or non-goal line items. - Document the entire flow in a README, outlining roles, responsibilities, and a reference table for smart contract functions.
- Introduce a series of examples demonstrating event monitoring for an analytics dashboard, including fetching historical campaign events, treasury-specific events, real-time event watchers, decoding raw logs, and aggregating metrics. - Each step is documented in a README, outlining the process and providing a reference table for the implemented functionalities.
- Introduce a series of examples demonstrating error handling and transaction safety in smart contract interactions. - Include steps for simulating transactions, preparing for external signing, catching typed errors, handling read-only clients, and implementing a safe transaction pattern. - Provide a convenience wrapper for simulation and error decoding in a single call. - Document the entire flow in a README, outlining the process and providing a reference table for the implemented functionalities.
- Introduce a series of examples demonstrating advanced patterns in smart contract interactions, including multicall for batch reads, per-entity and per-call signer overrides, item registration in the ItemRegistry, and protocol registry value lookups. - Implement non-blocking receipt lookups and browser wallet integrations for enhanced user experience. - Document the entire flow in a README, outlining the scenarios and providing a reference table for the implemented functionalities.
- Introduce a new setup module for shared client configuration across examples, including environment variable requirements for RPC URL and contract addresses. - Implement functions to create a client instance and validate environment variables, enhancing the usability of example contracts.
- Introduce a new README.md file containing real-world examples that demonstrate the capabilities of the Oak Contracts SDK, including platform onboarding, crowdfunding campaigns, e-commerce checkout, and more. - Each scenario is structured with a detailed explanation, folder organization, and step-by-step TypeScript files to facilitate understanding and implementation. - Provide a clear overview of roles involved in each scenario, enhancing the usability for developers and stakeholders.
- Add comments for additional treasury implementations in the TypeScript example, including PaymentTreasury and TimeConstrainedPaymentTreasury, clarifying their use cases and registration process. - Update README.md to reflect the new treasury implementations, detailing their functionalities and differences, ensuring clarity for developers on the SDK interface and registration requirements.
- Correct the property name from 'treasury' to 'treasuryAddress' in the treasury deployment logs for both all-or-nothing and keep-whats-raised examples, ensuring consistency and accuracy in the code.
… example - Update error message check to use startsWith for better matching of "No signer configured" error, providing clearer guidance for users to connect their wallet before performing actions.
… treasury example - Update the treasury example to wait for transaction mining before allowing withdrawals, preventing potential reverts if fees have not been disbursed yet. This enhances the reliability of the contract interactions.
- Comment out the platformHash definition in the optional configuration example to clarify its usage in subsequent examples. - Remove unused import of keccak256 in the error handling example to streamline the code and improve readability.
- Update the treasury deployment examples to decode the TreasuryDeployed event directly from the transaction receipt, ensuring accurate retrieval of the treasury address and avoiding ambiguity with multiple deploys in the same block.
…xample - Change the refund process to allow NFT owners to claim refunds directly by burning their NFT, enhancing user experience and clarity in the refund flow. - Update comments and variable names for better understanding of the refund mechanism, distinguishing between crypto and off-chain payment scenarios.
- Introduce a new events.ts file containing type-safe constants for event names emitted by various contracts, including GlobalParams, CampaignInfoFactory, CampaignInfo, TreasuryFactory, AllOrNothing, KeepWhatsRaised, PaymentTreasury, and ItemRegistry. - Update index.ts to re-export these event constants for improved accessibility.
…nt functions - Remove tests for token management functions (balanceOf, ownerOf, tokenURI, approve, setApprovalForAll, safeTransferFrom, transferFrom) from AllOrNothing, CampaignInfo, and KeepWhatsRaised contracts to enhance test clarity and maintainability. - Update related test cases to ensure they accurately reflect the current contract functionalities, improving overall test coverage and reliability.
…ised contracts - Eliminate redundant event names (Approval, ApprovalForAll, Transfer) from the AllOrNothing and KeepWhatsRaised contracts to streamline the event definitions. - Update the event constants accordingly to enhance code clarity and maintainability while ensuring the remaining functionalities of the contracts remain intact.
…nInfo contract - Modified the pledge and refund processes in the AllOrNothing, KeepWhatsRaised, and PaymentTreasury examples to reflect that pledge NFTs are managed through the CampaignInfo contract instead of the treasury contracts. - Updated relevant comments and documentation to clarify the approval process for NFTs, ensuring that users understand the need to approve the CampaignInfo contract before calling refund functions. - Enhanced overall clarity and maintainability of the code by consolidating NFT management logic.
…ampaignInfo contract - Revised documentation across crowdfunding, escrow, and marketplace use cases to reflect that pledge NFTs are managed via the CampaignInfo contract instead of the treasury contracts. - Enhanced comments to specify the approval process for NFTs, ensuring users understand the need to approve the CampaignInfo contract before invoking refund functions. - Improved clarity and consistency in refund flow descriptions, detailing the distinct paths for cancellation and refunds based on payment types.
…ionality - Updated the README and code examples for the Payment Treasury to enhance clarity on the payment processes, including both off-chain and on-chain flows. - Introduced new files for creating campaigns, deploying treasuries, processing payments, and handling refunds, ensuring a comprehensive guide for users. - Clarified the roles of platform admins and creators in managing campaigns and treasuries, and detailed the steps for fee disbursement and fund withdrawal. - Improved documentation to reflect the distinct paths for payment processing and refund handling, emphasizing the NFT management through the CampaignInfo contract.
…ontract - Revised the README files for Escrow, Marketplace, and Prepayment use cases to reflect the integration of the CampaignInfo contract in the payment processes. - Clarified the roles of CampaignInfoFactory and TreasuryFactory in creating and deploying contracts, enhancing the understanding of the overall flow. - Improved the integration flow steps to detail the creation of CampaignInfo contracts before deploying PaymentTreasury and TimeConstrainedPaymentTreasury. - Enhanced clarity on the NFT management process and the distinct roles of platform admins and campaign creators in managing funds and payments.
- Updated the verification process for treasury registrations to filter and confirm implementations specific to the NovaPay platform, avoiding false positives from shared deployments. - Added detailed logging for registered implementations and their approval status, ensuring clarity on which implementations are approved. - Improved comments to clarify the purpose of each verification step, specifically for NovaPay, enhancing overall code readability and maintainability.
Update event log fetching documentation and improve code consistency
…-chain payment flow
…repareContractWrite
- Updated the verification process to derive active treasury registrations by filtering out removed implementations, ensuring accurate tracking of current registrations for the NovaPay platform. - Improved logging to reflect the count of active implementations and their approval status, providing clearer insights into the treasury's state. - Enhanced comments for better understanding of the verification steps and the significance of approval events in the context of treasury management.
- Introduced a new "Examples" section detailing scenario-driven TypeScript examples that cover various SDK functionalities, providing users with practical implementation stories. - Added a "Use Cases" section that outlines business-oriented integration guides, illustrating how real companies can utilize the SDK for specific applications. - Enhanced the README to improve navigation and understanding of the SDK's capabilities, directing users to relevant resources for both executable examples and documentation guides.
… restore 100% branch coverage
…ements Add missing events, reads, errors, type-safe constants, simulation results, transaction preparation, and getReceipt
Add scenario-driven SDK examples and use-cases with real-world storytelling
mahabubAlahi
approved these changes
Apr 17, 2026
chore: update changeset
![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: e404554e84
ℹ️ 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".
devmahmud
approved these changes
Apr 17, 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
4 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.
Release: Contracts SDK v1.2
What's New
Simulation & Transaction Preparation
SimulationResult— everysimulate.*method now returns{ result, request }instead ofvoid, unlocking gas estimation, calldata inspection, and account-abstraction flows.prepareContractWrite/toPreparedTransaction— build raw transaction params (to,data,value,gas) without sending, for AA UserOps, Safe multisig, or custom signing flows.prepareContractWriteis now generic overTAbito preserve ABI-driven type safety forfunctionName.simulateWithErrorDecode— one-call simulate-then-decode wrapper that returns a typedSimulationResultor throws a decoded contract error.ViemSimulateRequestwith structured fields (address,abi,functionName,args) instead of rawto/data.Client Enhancements
getReceipt()on the client — non-blocking transaction receipt lookup. Returnsnullfor unmined transactions; re-throws non-receipt errors (e.g. network failures) instead of swallowing them.multicallutility — batch multiple read calls into a single RPC round-trip.Type-Safe Constants
GLOBAL_PARAMS_EVENTS,CAMPAIGN_INFO_EVENTS,ALL_OR_NOTHING_EVENTS,KEEP_WHATS_RAISED_EVENTS,PAYMENT_TREASURY_EVENTS,ITEM_REGISTRY_EVENTS,TREASURY_FACTORY_EVENTS,CAMPAIGN_INFO_FACTORY_EVENTS.*ErrorNamesobjects for every contract.Expanded Exports
GLOBAL_PARAMS_ABI,CAMPAIGN_INFO_ABI, etc.) from@oaknetwork/contracts-sdk/contracts.encodeFunctionData,decodeFunctionResult,decodeEventLog.ABI & SDK Gap Fixes
paused()reads added toGlobalParamsandPaymentTreasury.GlobalParams:PlatformLineItemTypeSet,PlatformLineItemTypeRemoved,DataAddedToRegistryPaymentTreasury:Paused,UnpausedCampaignInfo,AllOrNothing,KeepWhatsRaised:Cancelled,Paused,Unpaused(from PausableCancellable)get*Logs+watch*helpers.CampaignInfo— 10 new reads (getPledgeCount,getPledgeData,getImageURI,contractURI,name,symbol,tokenURI,ownerOf,balanceOf,supportsInterface),PledgeNFTMinted/ImageURIUpdated/ContractURIUpdatedevents, and a newPledgeDatastruct.PausedError,NotPausedError,CancelledError,NotCancelledError,CannotCancel,PledgeNFTUnAuthorized,PledgeNFTInvalidJsonString.approve,setApprovalForAll,safeTransferFrom,transferFrom,balanceOf,ownerOf,tokenURIand related events (Approval,ApprovalForAll,Transfer) removed from treasury contracts. These operations belong on theCampaignInfocontract, which manages all pledge NFTs.Metrics & Reporting
New
@oaknetwork/contracts-sdk/metricssubpath withplatform,campaign, andtreasuryaggregation helpers for dashboards and analytics.Scenario-Driven Examples (70+ examples across 7 scenarios)
A complete, narrative-first example library under
packages/contracts/src/examples/. Each scenario tells a real-world story with clear role markers (Protocol Admin, Platform Admin, Creator, Backer):Use-Case Integration Guides
Business-oriented guides under
packages/contracts/src/use-cases/covering:All use cases now include the full lifecycle: campaign creation → treasury deployment → operations.
Documentation
Internal / Quality
packages/contractsholds 100 % statement / branch / function / line coverage (enforced in CI).Bytes4forsupportsInterface,TAbigeneric forprepareContractWrite,ViemSimulateRequestfor structured simulation responses.GlobalParams,ItemRegistry, andPaymentTreasuryerror parsing.getReceiptcatchesTransactionReceiptNotFoundErrorspecifically, re-throws other errors.Migration Notes
simulate.*methods now returnSimulationResult({ result, request }) instead ofvoid. Callers that previously discarded the return value are unaffected; callers that want structured data can now destructure it.AllOrNothingandKeepWhatsRaisedentities no longer expose ERC-721 methods (approve,setApprovalForAll,balanceOf,ownerOf,tokenURI,safeTransferFrom,transferFrom) or events (Approval,ApprovalForAll,Transfer). Use theCampaignInfoentity for all NFT operations instead.ALL_OR_NOTHING_EVENTS.Receipt) over string literals for safer refactors.Test Plan
pnpm build,pnpm lint,pnpm test(100 % coverage thresholds enforced forpackages/contracts)@oaknetwork/contracts-sdk@oaknetwork/contracts-sdk/metricsand/contractssubpath exports resolve in a downstream consumer