Changelog
Version history for the Thetanuts Finance SDK.
Current Version
v0.2.3 — View all releases on GitHub
This SDK follows Semantic Versioning: MAJOR.MINOR.PATCH. Patch releases contain bug fixes and non-breaking improvements. Minor releases add new functionality in a backwards-compatible manner. Major releases may contain breaking changes and will be accompanied by a migration guide.
Where to look for release notes:
GitHub Releases — canonical per-version detail (commit log, before/after diffs, verification steps).
CHANGELOG.mdin the repo — terse per-version log, ships with the npm package.The summaries below are the user-facing highlights for the latest few releases.
Release History
v0.2.3 — strategyVault rename (BREAKING)
Renames two public symbols on client.strategyVault. Behavior, ABIs, and contract addresses are unchanged.
Heads up: despite the patch-level version bump, the two API renames below are breaking. Anyone using the previous config field or method names from v0.2.2 must update on upgrade. There are no deprecated aliases — old names are gone.
Breaking renames:
- const vault = STRATEGY_VAULT_CONFIG.<old>.vaults[0].address;
+ const vault = STRATEGY_VAULT_CONFIG.fixedStrike.vaults[0].address;
- const vaults = await client.strategyVault.<old>();
+ const vaults = await client.strategyVault.getFixedStrikeVaults();All sub-fields of STRATEGY_VAULT_CONFIG.<old> (vaults, baseAsset, quoteAsset, oracle) move with the rename. Migration is a straight find-and-replace; return shapes are identical.
Prose updates: comments, JSDoc, runtime error messages, and docs use neutral terms ("fixed-strike", "wheel strategy") throughout. No symbol changes beyond the two breaking renames above.
Test runner: scripts/run-mainnet-tests.ts now retries transient CALL_EXCEPTION errors from public RPCs (the public Base RPC drops bursts of read calls; the test suite was failing 28/30 instead of 30/30 because of dropped responses, not contract bugs). Runner accepts a BASE_RPC_URL env var to override the public default.
Unchanged: STRATEGY_VAULT_CONFIG.clvex, getClvexVaults(), getAllVaults(), all on-chain contract addresses, ABIs, and module shapes.
v0.2.2 — DX polish
Polish release with no new features and no breaking changes. Came out of a live /devex-review audit.
Bug fixes:
mapContractErrorno longer clobbers typedThetanutsErrorinstances (e.g.SIGNER_REQUIREDfromrequireSigner()). Callingclient.optionBook.claimFees(token)without a signer now reportscode: 'SIGNER_REQUIRED'instead of genericcode: 'CONTRACT_REVERT'.NETWORK_UNSUPPORTEDerror message now derives the supported-chains list dynamically fromCHAIN_CONFIGS_BY_ID. Previous hardcoded string"Supported chains: 8453 (Base)"omitted Ethereum (added in v0.2.1).
Project hygiene:
New
CONTRIBUTING.mddocuments local setup, the four required gates, the/codex review+/codex challengereview process, and the npm publish flow.New
SECURITY.md— vulnerability reporting policy and supported-versions table.New
.github/ISSUE_TEMPLATE/{bug_report,feature_request,question,config}.ymlandPULL_REQUEST_TEMPLATE.md.
Documentation:
Fixed broken link in
docs/resources/migration-guide.md(pointed at non-existentreference/error-codes.md; now points atguides/error-handling.md).Backfilled v0.1.x history in repo-root
CHANGELOG.md.
v0.2.1 — Base_r12 deployment + codex-found fixes
The first 0.2.x release published to npm. Bundles the Base_r12 deployment cutover with 22 fixes that three adversarial code-review passes found in the staged surface. v0.2.0 was prepared internally but never published; everything ships in this single release.
See the v0.2.1 GitHub Release for per-commit detail, before/after migration code, and verification steps.
Base_r12 cutover:
All chainId-8453 contract addresses point at the r12 deployment (
optionBook,optionFactory, all 13 implementations, LoanCoordinator, LoanHandler).deploymentBlock→45601440(deployed 2026-05-05).Historical reverse-lookup entries (
8453_v6,Base_r10) preserved so events emitted before the cutover still decode.Ethereum mainnet (
chainId 1) added as a vault-only chain.
New surface:
New
client.rangermodule — RangerOption (zone-bound, 4-strike payoff). Module is chain-gated; throwsNETWORK_UNSUPPORTEDon chains where RangerOption is not deployed (Ethereum mainnet today).RANGER_OPTION_ABIexported from the package root.chainConfig.twapConsumer(HistoricalPriceConsumerV3_TWAP) surfaced as a top-level chain-config field.New chain-config implementation keys:
RANGER,LINEAR_CALL,INVERSE_CALL_SPREAD,CALL_LOAN.New OptionBook surface:
cancelOrders,cancelOrdersExpiringBefore,getValidNumContracts,makerCancellationCutoff,minNumContracts,minPremiumAmount+MakerCutoffUpdatedevent.New OptionFactory surface:
claimEscrowedFunds,claimableTransfers,totalClaimableTransfers,activeRfqForOption,baseSplitFee,MAX_TRANSFER_DUST,MAX_ORACLE_STALENESS,settleQuotationEarlyByOrderBook,historicalTWAPConsumer,deprecationTime,settlementExtension+ 10 new events.
Production-revert fixes (would have silently reverted once the protocol enabled non-zero fees):
splitandreclaimCollateraldeclaredpayable; the SDK forwardsgetSplitFee()/getReclaimFee(ownedOption)asmsg.value.RangerModule.reclaimCollateralpasses the option being reclaimed (not the caller's address) togetReclaimFee. The fee is keyed on the option, not the caller.
ABI shape corrections (against canonical r12 JSONs):
OptionBook.getValidNumContractsreturns the canonical tupleresult { validContracts, collateralRequired }, not a singleuint256.BaseOption.optionTypeisview returns (uint256);RangerOption.optionTypeispure returns (uint256).BaseOption.returnExcessCollateraldeclares itsuint256return.LoanCoordinator.assetConfigsreturns the four-field tuple.
Event shape corrections:
OptionInitialized(11 fields),OptionSplit(addsfeePaidandcounterparty),TransferApproval(field order corrected),OptionSettlementFailed(no inputs), andExcessCollateralReturned(renamed fromCollateralReturned) all match r12.client.events.getCollateralReturnedEventsisgetExcessCollateralReturnedEventswith field shape{ seller, collateralToken, collateralReturned }.
Safety upgrades:
All four RFQ entry points (
requestForQuotation,encodeRequestForQuotation,registerReferral,callStaticCreateRFQ) reject the seven undeployedPHYSICAL_*_SPREAD/FLY/CONDOR/IRON_CONDORzero-address placeholders withINVALID_PARAMSbefore any transaction is built.
Loan changes:
LOAN_COORDINATOR_ABIupdated for r12:requestLoanno longer carriesconvertToLimitOrder;loanRequestsreturnsloanClaimed; newLoanClaimedevent.LoanRequest.keepOrderOpenis@deprecated— the r12 contract ignores the value.getLendingOpportunitiesfilter treats a missingconvertToLimitOrderindexer field as eligible — only skips when explicitlyfalse.
Naming reconciliation:
getOptionImplementationInfo(addr).namefor butterflies returns'CALL_FLY'/'PUT_FLY'(was'CALL_FLYS'/'PUT_FLYS').OptionImplementationInfo.typeunion:'RANGE'replaced by'RANGER'.
Breaking changes from v0.1.x:
client.events.getCollateralReturnedEventsremoved; replaced bygetExcessCollateralReturnedEventswith new fields.OptionSplitEventaddsfeePaidandcounterparty.getOptionImplementationInfo(addr).namefor butterflies renamed (above).LoanCoordinator.requestLoanno longer acceptsconvertToLimitOrder.
v0.1.6
Added
getAllClaimableFees()andclaimAllFees()helpers onoptionBookfor batch fee claiming across all collateral tokens.
v0.1.5
Added
getFactoryReferrerStats()for the/factory/referrer/:address/stateendpoint.Narrowed catch-block errors from
anytounknownfor stricter type safety.
v0.1.4
Added Yarn Classic (v1) and Yarn Berry (v2+) publish support.
Fixed
numContractsprecision handling andexistingOptionAddressparameter defaults.Fixed
LINEAR_CALLmax contracts calculation.Fixed nonce null safety in transaction encoding.
Fixed
toBigInthandling of scientific notation and negative numbers.Fixed floating-point overflow in multi-leg MM pricing calculations.
Added support for additional underlying assets and collateral tokens in the RFQ builder.
v0.1.3 and earlier
Initial public release of the Thetanuts Finance SDK.
Core modules:
optionBook,optionFactory,option,mmPricing,erc20,api,utils.buildRFQParams()andbuildRFQRequest()high-level builders.getFullOptionInfo()aggregated option query.strikeToChain()/strikeFromChain()precision-safe strike conversion.MM pricing filter utilities:
filterExpired(),filterByType(),filterByExpiry(),filterByStrikeRange(),sortByExpiryAndStrike().Book position PnL fields added to
Positiontype.Indexer method renames to clarify data source (
getUserPositionsFromIndexer(),getUserRFQsFromRfq(), etc.).
See Also
Migration Guide - Breaking changes and upgrade steps
Examples - Runnable code examples
Quick Start - Installation and setup
Last updated

