Gradient strategy support

.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [20.x]
+        node-version: [22.x]
 
     steps:
       - uses: actions/checkout@v3

.nvmrc

@@ -1 +1 @@
-20
+22

README.md

@@ -9,7 +9,30 @@ This SDK is in beta. We cannot be held responsible for any losses caused by use
 
 ## Overview
 
-The SDK is a READ-ONLY tool, intended to facilitate working with Carbon contracts. It's a convenient wrapper around the Carbon matching algorithm and Carbon contracts, allowing programs and users get a ready to use transaction data that will allow them to manage strategies and fulfill trades
+The SDK is a READ-ONLY tool, intended to facilitate working with Carbon contracts. It's a convenient wrapper around the Carbon matching algorithm and Carbon contracts, allowing programs and users get a ready to use transaction data that will allow them to manage strategies and fulfill trades.
+
+The SDK supports two strategy families:
+
+- Standard Carbon strategies
+- Gradient strategies
+
+Gradient strategies are time-based moving limit orders. Each side of the strategy has:
+
+- a start price
+- an end price
+- a budget
+- a start time
+- an end time
+- a gradient type
+
+Supported gradient types:
+
+- `LinearIncrease`
+- `LinearDecrease`
+- `LinearInverseIncrease`
+- `LinearInverseDecrease`
+- `ExponentialIncrease`
+- `ExponentialDecrease`
 
 ## Installation
 
@@ -29,6 +52,9 @@ import {
   MatchActionBNStr,
   StrategyUpdate,
   EncodedStrategyBNStr,
+  GradientStrategyUpdate,
+  GradientEncodedStrategyBNStr,
+  GradientType,
 } from '@bancor/carbon-sdk';
 import { Toolkit } from '@bancor/carbon-sdk/strategy-management';
 import { ChainCache, initSyncedCache } from '@bancor/carbon-sdk/chain-cache';
@@ -78,13 +104,118 @@ const init = async (
 };
 ```
 
+## Gradient Contracts
+
+Gradient support is optional per chain.
+
+If `gradientControllerAddress` and `gradientVoucherAddress` are provided in `ContractsConfig`, the SDK will:
+
+- read and cache gradient strategies
+- process gradient strategy events in `ChainSync`
+- expose gradient strategy management methods
+
+If these addresses are omitted, the SDK will not issue calls to gradient contracts. This is useful for chains where gradient contracts have not been deployed yet.
+
+Example:
+
+```ts
+const config: ContractsConfig = {
+  carbonControllerAddress: '0x...',
+  multiCallAddress: '0x...',
+  voucherAddress: '0x...',
+  carbonBatcherAddress: '0x...',
+  gradientControllerAddress: '0x...',
+  gradientVoucherAddress: '0x...',
+};
+```
+
+## Strategy Types
+
+### Standard Strategies
+
+The existing standard strategy flow is unchanged. Main helpers include:
+
+- `createBuySellStrategy`
+- `updateStrategy`
+- `deleteStrategy`
+- `getStrategyById`
+- `getStrategiesByPair`
+- `getUserStrategies`
+
+### Gradient Strategies
+
+Gradient strategies are exposed in parallel to the standard strategy flow.
+
+Main helpers include:
+
+- `createBuySellGradientStrategy`
+- `updateGradientStrategy`
+- `deleteGradientStrategy`
+- `getGradientStrategyById`
+- `getGradientStrategiesByPair`
+- `getUserGradientStrategies`
+
+Example:
+
+```ts
+const tx = await carbonSDK.createBuySellGradientStrategy(
+  baseToken,
+  quoteToken,
+  '1800', // buyPriceStart
+  '1500', // buyPriceEnd
+  '1000', // buyBudget
+  GradientType.LinearDecrease,
+  1710000000, // buyStartTime
+  1712592000, // buyEndTime
+  '2200', // sellPriceStart
+  '2600', // sellPriceEnd
+  '1', // sellBudget
+  GradientType.ExponentialIncrease,
+  1710000000, // sellStartTime
+  1712592000 // sellEndTime
+);
+```
+
+## Encoding Helpers
+
+The shared encoder module supports both strategy types.
+
+Standard helpers:
+
+- `encodeOrder`
+- `decodeOrder`
+- `encodeStrategy`
+- `decodeStrategy`
+
+Gradient helpers:
+
+- `encodeGradientOrder`
+- `decodeGradientOrder`
+- `encodeGradientStrategy`
+- `decodeGradientStrategy`
+
+These live in `@bancor/carbon-sdk/utils`.
+
+## Chain Cache
+
+`ChainCache` and `ChainSync` support both standard and gradient strategies.
+
+The synced cache:
+
+- caches standard strategies by pair and id
+- caches gradient strategies by pair and id
+- keeps standard trade orders for the existing matcher flow
+- processes both standard and gradient strategy create/update/delete events
+
+Gradient cache lookups are available through the toolkit methods listed above.
+
 ## Notes
 
 ### 1. The SDK Logger supports 3 verbosity levels:
 
 - `0` (default) only prints errors and important logs.
 - `1` (debug) prints highly verbose logs.
-- `2` (debug readable) is same as `1` but also converts any BigNumber to an easy to read string (impacting performance).
+- `2` (debug readable) is same as `1` but also converts any bigint to an easy to read string (impacting performance).
 
 To use it in Node, set the environment variable `CARBON_DEFI_SDK_VERBOSITY` to the desired level.
 To use it from a browser app do, before importing the SDK:

demos/concentrated-amm-integration/demo.ts

@@ -37,6 +37,8 @@ async function demonstrateCarbonIntegration() {
     voucherAddress: '0x3660F04B79751e31128f6378eAC70807e38f554E',
     carbonBatcherAddress: '0x0199f3A6C4B192B9f9C3eBE31FBC535CdD4B7D4e',
     multiCallAddress: '0xcA11bde05977b3631167028862bE2a173976CA11',
+    gradientControllerAddress: '0x5BDdF8EdeEaE66Cc8477c9282b8c0462CD7132aa',
+    gradientVoucherAddress: '0x4973fa43c4c4b0Bbe4071eB3e7c900810Df143E8',
   });
 
   // const reader = new Reader(contracts);

package.json

@@ -2,7 +2,7 @@
   "name": "@bancor/carbon-sdk",
   "type": "module",
   "source": "src/index.ts",
-  "version": "0.0.130-DEV",
+  "version": "0.0.131-DEV",
   "description": "The SDK is a READ-ONLY tool, intended to facilitate working with Carbon contracts. It's a convenient wrapper around our matching algorithm, allowing programs and users get a ready to use transaction data that will allow them to manage strategies and fulfill trades",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -40,7 +40,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "typesVersions": {
     "*": {
@@ -67,7 +67,7 @@
   "types": "dist/index.d.ts",
   "scripts": {
     "clean": "rm -rf dist && rm -rf src/abis/types",
-    "compile-abis": "typechain --target ethers-v6 --out-dir 'src/abis/types' 'src/abis/**/*.json'",
+    "compile-abis": "typechain --target ethers-v6 --out-dir \"src/abis/types\" \"src/abis/**/*.json\"",
     "prebuild": "yarn clean && yarn compile-abis",
     "build": "yarn lint && rollup -c",
     "test": "yarn lint && mocha",
@@ -125,5 +125,6 @@
   },
   "peerDependencies": {
     "ethers": "^6.15.0"
-  }
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

rollup.config.js

@@ -2,7 +2,7 @@ import resolve from '@rollup/plugin-node-resolve';
 import commonjs from '@rollup/plugin-commonjs';
 import typescript from '@rollup/plugin-typescript';
 import { terser } from 'rollup-plugin-terser';
-import pkg from './package.json' assert { type: 'json' };
+import pkg from './package.json' with { type: 'json' };
 
 export default {
   input: {