@andrewkimjoseph/celina-sdk 0.5.1 → 0.7.0

package/README.md

@@ -28,11 +28,16 @@ npm i @andrewkimjoseph/celina-sdk
 
 Requires Node.js ≥ 20.
 
+### LLM tool catalog (v0.5+)
+
+For MCP servers and chat APIs (Vercel AI SDK, etc.), import shared tool definitions from `@andrewkimjoseph/celina-sdk/tools` instead of redefining schemas. See [LLM tool catalog](docs/guides/tool-catalog.md) — includes the recommended **`dynamicTool`** pattern so TypeScript does not OOM on large tool sets.
+
 ## Documentation
 
 **Full docs:** [celina-sdk on GitBook](https://andrewkimjoseph.gitbook.io/celina-sdk)
 
 - [Quick start](https://andrewkimjoseph.gitbook.io/celina-sdk/getting-started/quick-start)
+- [LLM tool catalog](docs/guides/tool-catalog.md) — `@andrewkimjoseph/celina-sdk/tools` for MCP and AI SDK hosts
 - [Architecture](docs/concepts/architecture.md) — client composition and stack
 - [Prepared flows](docs/concepts/prepared-flows.md) — `SerializedPreparedFlow`, CELINA calldata tag
 - [wagmi integration](https://andrewkimjoseph.gitbook.io/celina-sdk/guides/wagmi-integration)
@@ -54,7 +59,7 @@ const celina = createCelinaClient();
 await celina.token.getStablecoinBalances("0xYourAddress");
 
 const flow = await celina.transaction.prepareSend("0xFrom", "0xTo", "USDm", "10");
-// flow.steps → pass to wagmi sendTransaction (calldata includes CELINA attribution suffix)
+// flow.steps → pass to wagmi sendTransactionAsync (calldata includes CELINA attribution suffix)
 
 // Carbon DeFi (reads + unsigned strategy/trade prep)
 const strategies = await celina.carbon.getStrategies("0xYourAddress");

package/build/abis/gooddollar-broker.d.ts

@@ -0,0 +1,77 @@
+/** GoodDollar MentoBroker on Celo — reserve swap quotes and execution. */
+export declare const goodDollarBrokerAbi: readonly [{
+    readonly type: "function";
+    readonly name: "getAmountOut";
+    readonly inputs: readonly [{
+        readonly name: "exchangeProvider";
+        readonly type: "address";
+    }, {
+        readonly name: "exchangeId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "tokenIn";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenOut";
+        readonly type: "address";
+    }, {
+        readonly name: "amountIn";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "getAmountIn";
+    readonly inputs: readonly [{
+        readonly name: "exchangeProvider";
+        readonly type: "address";
+    }, {
+        readonly name: "exchangeId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "tokenIn";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenOut";
+        readonly type: "address";
+    }, {
+        readonly name: "amountOut";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "swapIn";
+    readonly inputs: readonly [{
+        readonly name: "exchangeProvider";
+        readonly type: "address";
+    }, {
+        readonly name: "exchangeId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "tokenIn";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenOut";
+        readonly type: "address";
+    }, {
+        readonly name: "amountIn";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amountOutMin";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amountOut";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "nonpayable";
+}];

package/build/abis/gooddollar-broker.js

@@ -0,0 +1,44 @@
+/** GoodDollar MentoBroker on Celo — reserve swap quotes and execution. */
+export const goodDollarBrokerAbi = [
+    {
+        type: "function",
+        name: "getAmountOut",
+        inputs: [
+            { name: "exchangeProvider", type: "address" },
+            { name: "exchangeId", type: "bytes32" },
+            { name: "tokenIn", type: "address" },
+            { name: "tokenOut", type: "address" },
+            { name: "amountIn", type: "uint256" },
+        ],
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view",
+    },
+    {
+        type: "function",
+        name: "getAmountIn",
+        inputs: [
+            { name: "exchangeProvider", type: "address" },
+            { name: "exchangeId", type: "bytes32" },
+            { name: "tokenIn", type: "address" },
+            { name: "tokenOut", type: "address" },
+            { name: "amountOut", type: "uint256" },
+        ],
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view",
+    },
+    {
+        type: "function",
+        name: "swapIn",
+        inputs: [
+            { name: "exchangeProvider", type: "address" },
+            { name: "exchangeId", type: "bytes32" },
+            { name: "tokenIn", type: "address" },
+            { name: "tokenOut", type: "address" },
+            { name: "amountIn", type: "uint256" },
+            { name: "amountOutMin", type: "uint256" },
+        ],
+        outputs: [{ name: "amountOut", type: "uint256" }],
+        stateMutability: "nonpayable",
+    },
+];
+//# sourceMappingURL=gooddollar-broker.js.map

package/build/abis/gooddollar-broker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gooddollar-broker.js","sourceRoot":"","sources":["../../src/abis/gooddollar-broker.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,SAAS,EAAE;YAC7C,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE;YACvC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;YACpC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;YACrC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;SACtC;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACxC,eAAe,EAAE,MAAM;KACxB;IACD;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,SAAS,EAAE;YAC7C,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE;YACvC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;YACpC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;YACrC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE;SACvC;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACxC,eAAe,EAAE,MAAM;KACxB;IACD;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,SAAS,EAAE;YAC7C,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE;YACvC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;YACpC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;YACrC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;YACrC,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,EAAE;SAC1C;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACjD,eAAe,EAAE,YAAY;KAC9B;CACO,CAAC"}

package/build/analytics/mcp-tool-events.js

@@ -25,6 +25,8 @@ export const MCP_TOOL_EVENT_BY_SDK_METHOD = {
     "contract.callFunction": "call_contract_function",
     "contract.estimateGas": "estimate_contract_gas",
     "ens.resolveEns": "resolve_ens",
+    "gooddollar.getReserveQuote.buy": "get_gooddollar_reserve_quote",
+    "gooddollar.getReserveQuote.sell": "get_gooddollar_reserve_quote",
     "gooddollar.getUbiClaimEligibility": "get_gooddollar_ubi_entitlement",
     "gooddollar.getWhitelistingInfo": "get_gooddollar_whitelisting_info",
     "governance.getGovernanceProposals": "get_governance_proposals",

package/build/analytics/mcp-tool-events.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-tool-events.js","sourceRoot":"","sources":["../../src/analytics/mcp-tool-events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAqC;IAC5E,oBAAoB,EAAE,aAAa;IACnC,0BAA0B,EAAE,oBAAoB;IAChD,qBAAqB,EAAE,WAAW;IAClC,qCAAqC,EAAE,WAAW;IAClD,4BAA4B,EAAE,mBAAmB;IACjD,6BAA6B,EAAE,oBAAoB;IACnD,2BAA2B,EAAE,iBAAiB;IAC9C,oBAAoB,EAAE,qBAAqB;IAC3C,0BAA0B,EAAE,2BAA2B;IACvD,oBAAoB,EAAE,qBAAqB;IAC3C,wBAAwB,EAAE,0BAA0B;IACpD,yBAAyB,EAAE,2BAA2B;IACtD,sBAAsB,EAAE,uBAAuB;IAC/C,oBAAoB,EAAE,qBAAqB;IAC3C,sBAAsB,EAAE,wBAAwB;IAChD,aAAa,EAAE,aAAa;IAC5B,cAAc,EAAE,cAAc;IAC9B,qBAAqB,EAAE,sBAAsB;IAC7C,yBAAyB,EAAE,0BAA0B;IACrD,uBAAuB,EAAE,wBAAwB;IACjD,sBAAsB,EAAE,uBAAuB;IAC/C,gBAAgB,EAAE,aAAa;IAC/B,mCAAmC,EAAE,gCAAgC;IACrE,gCAAgC,EAAE,kCAAkC;IACpE,mCAAmC,EAAE,0BAA0B;IAC/D,+BAA+B,EAAE,sBAAsB;IACvD,oBAAoB,EAAE,mBAAmB;IACzC,oBAAoB,EAAE,oBAAoB;IAC1C,mBAAmB,EAAE,iBAAiB;IACtC,gBAAgB,EAAE,cAAc;IAChC,6BAA6B,EAAE,0BAA0B;IACzD,4BAA4B,EAAE,yBAAyB;IACvD,sBAAsB,EAAE,mBAAmB;IAC3C,sBAAsB,EAAE,mBAAmB;IAC3C,sBAAsB,EAAE,mBAAmB;IAC3C,sBAAsB,EAAE,mBAAmB;IAC3C,wBAAwB,EAAE,qBAAqB;IAC/C,8BAA8B,EAAE,wBAAwB;IACxD,4BAA4B,EAAE,sBAAsB;IACpD,6BAA6B,EAAE,wBAAwB;IACvD,kCAAkC,EAAE,6BAA6B;IACjE,4BAA4B,EAAE,sBAAsB;IACpD,mBAAmB,EAAE,mBAAmB;IACxC,6BAA6B,EAAE,yBAAyB;IACxD,uBAAuB,EAAE,mBAAmB;IAC5C,oBAAoB,EAAE,gBAAgB;IACtC,0BAA0B,EAAE,eAAe;IAC3C,iCAAiC,EAAE,sBAAsB;IACzD,2BAA2B,EAAE,kBAAkB;IAC/C,sBAAsB,EAAE,uBAAuB;IAC/C,sBAAsB,EAAE,mBAAmB;CACnC,CAAC"}
+{"version":3,"file":"mcp-tool-events.js","sourceRoot":"","sources":["../../src/analytics/mcp-tool-events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAqC;IAC5E,oBAAoB,EAAE,aAAa;IACnC,0BAA0B,EAAE,oBAAoB;IAChD,qBAAqB,EAAE,WAAW;IAClC,qCAAqC,EAAE,WAAW;IAClD,4BAA4B,EAAE,mBAAmB;IACjD,6BAA6B,EAAE,oBAAoB;IACnD,2BAA2B,EAAE,iBAAiB;IAC9C,oBAAoB,EAAE,qBAAqB;IAC3C,0BAA0B,EAAE,2BAA2B;IACvD,oBAAoB,EAAE,qBAAqB;IAC3C,wBAAwB,EAAE,0BAA0B;IACpD,yBAAyB,EAAE,2BAA2B;IACtD,sBAAsB,EAAE,uBAAuB;IAC/C,oBAAoB,EAAE,qBAAqB;IAC3C,sBAAsB,EAAE,wBAAwB;IAChD,aAAa,EAAE,aAAa;IAC5B,cAAc,EAAE,cAAc;IAC9B,qBAAqB,EAAE,sBAAsB;IAC7C,yBAAyB,EAAE,0BAA0B;IACrD,uBAAuB,EAAE,wBAAwB;IACjD,sBAAsB,EAAE,uBAAuB;IAC/C,gBAAgB,EAAE,aAAa;IAC/B,gCAAgC,EAAE,8BAA8B;IAChE,iCAAiC,EAAE,8BAA8B;IACjE,mCAAmC,EAAE,gCAAgC;IACrE,gCAAgC,EAAE,kCAAkC;IACpE,mCAAmC,EAAE,0BAA0B;IAC/D,+BAA+B,EAAE,sBAAsB;IACvD,oBAAoB,EAAE,mBAAmB;IACzC,oBAAoB,EAAE,oBAAoB;IAC1C,mBAAmB,EAAE,iBAAiB;IACtC,gBAAgB,EAAE,cAAc;IAChC,6BAA6B,EAAE,0BAA0B;IACzD,4BAA4B,EAAE,yBAAyB;IACvD,sBAAsB,EAAE,mBAAmB;IAC3C,sBAAsB,EAAE,mBAAmB;IAC3C,sBAAsB,EAAE,mBAAmB;IAC3C,sBAAsB,EAAE,mBAAmB;IAC3C,wBAAwB,EAAE,qBAAqB;IAC/C,8BAA8B,EAAE,wBAAwB;IACxD,4BAA4B,EAAE,sBAAsB;IACpD,6BAA6B,EAAE,wBAAwB;IACvD,kCAAkC,EAAE,6BAA6B;IACjE,4BAA4B,EAAE,sBAAsB;IACpD,mBAAmB,EAAE,mBAAmB;IACxC,6BAA6B,EAAE,yBAAyB;IACxD,uBAAuB,EAAE,mBAAmB;IAC5C,oBAAoB,EAAE,gBAAgB;IACtC,0BAA0B,EAAE,eAAe;IAC3C,iCAAiC,EAAE,sBAAsB;IACzD,2BAA2B,EAAE,kBAAkB;IAC/C,sBAAsB,EAAE,uBAAuB;IAC/C,sBAAsB,EAAE,mBAAmB;CACnC,CAAC"}

package/build/config/gooddollar.d.ts

@@ -2,3 +2,15 @@
 export declare const GOODDOLLAR_IDENTITY_ADDRESS: "0xC361A6E67822a0EDc17D899227dd9FC50BD62F42";
 /** GoodDollar UBISchemeV2 contract on Celo mainnet. */
 export declare const GOODDOLLAR_UBI_SCHEME_ADDRESS: "0x43d72Ff17701B2DA814620735C39C620Ce0ea4A1";
+/** GoodDollar G$ token on Celo mainnet (SuperGoodDollar). */
+export declare const GOODDOLLAR_TOKEN_ADDRESS: "0x62B8B11039FcfE5aB0C56E502b1C372A3d2a9c7A";
+/** MentoBroker proxy — user-facing entry for G$ reserve swaps on Celo. */
+export declare const GOODDOLLAR_MENTO_BROKER: "0x88de45906D4F5a57315c133620cfa484cB297541";
+/** GoodDollar MentoExchangeProvider on Celo mainnet. */
+export declare const GOODDOLLAR_MENTO_EXCHANGE_PROVIDER: "0x2fFBB49055d487DdBBb0C052Cd7c2a02A7971e41";
+/** Exchange pool id for G$ ↔ USDm (CUSD in GoodProtocol deployment). */
+export declare const GOODDOLLAR_CUSD_EXCHANGE_ID: "0xba77f5c7bb3317643c6d81d1ef3f9913561741d92095f88efa402faf2cbe9124";
+/** Reserve collateral token (USDm / cUSD) for the G$ pool on Celo. */
+export declare const GOODDOLLAR_RESERVE_COLLATERAL: "0x765DE816845861e75A25fCA122bb6898B8B1282a";
+/** Whether both tokens form a supported GoodDollar reserve pair (G$ ↔ USDm). */
+export declare function isGoodDollarUsdReservePair(tokenIn: string, tokenOut: string): boolean;

package/build/config/gooddollar.js

@@ -2,4 +2,23 @@
 export const GOODDOLLAR_IDENTITY_ADDRESS = "0xC361A6E67822a0EDc17D899227dd9FC50BD62F42";
 /** GoodDollar UBISchemeV2 contract on Celo mainnet. */
 export const GOODDOLLAR_UBI_SCHEME_ADDRESS = "0x43d72Ff17701B2DA814620735C39C620Ce0ea4A1";
+/** GoodDollar G$ token on Celo mainnet (SuperGoodDollar). */
+export const GOODDOLLAR_TOKEN_ADDRESS = "0x62B8B11039FcfE5aB0C56E502b1C372A3d2a9c7A";
+/** MentoBroker proxy — user-facing entry for G$ reserve swaps on Celo. */
+export const GOODDOLLAR_MENTO_BROKER = "0x88de45906D4F5a57315c133620cfa484cB297541";
+/** GoodDollar MentoExchangeProvider on Celo mainnet. */
+export const GOODDOLLAR_MENTO_EXCHANGE_PROVIDER = "0x2fFBB49055d487DdBBb0C052Cd7c2a02A7971e41";
+/** Exchange pool id for G$ ↔ USDm (CUSD in GoodProtocol deployment). */
+export const GOODDOLLAR_CUSD_EXCHANGE_ID = "0xba77f5c7bb3317643c6d81d1ef3f9913561741d92095f88efa402faf2cbe9124";
+/** Reserve collateral token (USDm / cUSD) for the G$ pool on Celo. */
+export const GOODDOLLAR_RESERVE_COLLATERAL = "0x765DE816845861e75A25fCA122bb6898B8B1282a";
+const GOODDOLLAR_SYMBOLS = new Set(["gooddollar", "g$"]);
+const RESERVE_COLLATERAL_SYMBOLS = new Set(["usdm", "cusd"]);
+/** Whether both tokens form a supported GoodDollar reserve pair (G$ ↔ USDm). */
+export function isGoodDollarUsdReservePair(tokenIn, tokenOut) {
+    const a = tokenIn.trim().toLowerCase();
+    const b = tokenOut.trim().toLowerCase();
+    return ((GOODDOLLAR_SYMBOLS.has(a) && RESERVE_COLLATERAL_SYMBOLS.has(b)) ||
+        (GOODDOLLAR_SYMBOLS.has(b) && RESERVE_COLLATERAL_SYMBOLS.has(a)));
+}
 //# sourceMappingURL=gooddollar.js.map

package/build/config/gooddollar.js.map

@@ -1 +1 @@
-{"version":3,"file":"gooddollar.js","sourceRoot":"","sources":["../../src/config/gooddollar.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,MAAM,CAAC,MAAM,2BAA2B,GACtC,4CAAqD,CAAC;AAExD,uDAAuD;AACvD,MAAM,CAAC,MAAM,6BAA6B,GACxC,4CAAqD,CAAC"}
+{"version":3,"file":"gooddollar.js","sourceRoot":"","sources":["../../src/config/gooddollar.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,MAAM,CAAC,MAAM,2BAA2B,GACtC,4CAAqD,CAAC;AAExD,uDAAuD;AACvD,MAAM,CAAC,MAAM,6BAA6B,GACxC,4CAAqD,CAAC;AAExD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,wBAAwB,GACnC,4CAAqD,CAAC;AAExD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,uBAAuB,GAClC,4CAAqD,CAAC;AAExD,wDAAwD;AACxD,MAAM,CAAC,MAAM,kCAAkC,GAC7C,4CAAqD,CAAC;AAExD,wEAAwE;AACxE,MAAM,CAAC,MAAM,2BAA2B,GACtC,oEAA6E,CAAC;AAEhF,sEAAsE;AACtE,MAAM,CAAC,MAAM,6BAA6B,GACxC,4CAAqD,CAAC;AAExD,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC;AACzD,MAAM,0BAA0B,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE7D,gFAAgF;AAChF,MAAM,UAAU,0BAA0B,CAAC,OAAe,EAAE,QAAgB;IAC1E,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACvC,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxC,OAAO,CACL,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,0BAA0B,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAChE,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,0BAA0B,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CACjE,CAAC;AACJ,CAAC"}

package/build/index.d.ts

@@ -32,7 +32,7 @@ export interface CelinaClient {
     uniswap: UniswapService;
     /** Aave V3 `prepareSupply` and `prepareWithdraw` flows on Celo. */
     aave: AaveService;
-    /** GoodDollar IdentityV4 whitelist status and daily UBI claim preparation. */
+    /** GoodDollar IdentityV4 whitelist, UBI claims, and G$ ↔ USDm reserve swaps. */
     gooddollar: GoodDollarService;
     /** Celo and Ethereum ENS resolution. */
     ens: EnsService;
@@ -81,7 +81,8 @@ export { AAVE_POOL, AAVE_SUPPORTED_SYMBOLS, resolveAaveAsset, } from "./config/a
 export { CHAIN, DEFAULT_RPC_URL } from "./config/chains.js";
 export { appendCelinaCalldataTag, CELINA_DATA_SUFFIX, } from "./config/celina-tag.js";
 export type { AaveAsset } from "./config/aave.js";
-export { GOODDOLLAR_IDENTITY_ADDRESS, GOODDOLLAR_UBI_SCHEME_ADDRESS, } from "./config/gooddollar.js";
+export { GOODDOLLAR_CUSD_EXCHANGE_ID, GOODDOLLAR_IDENTITY_ADDRESS, GOODDOLLAR_MENTO_BROKER, GOODDOLLAR_MENTO_EXCHANGE_PROVIDER, GOODDOLLAR_RESERVE_COLLATERAL, GOODDOLLAR_TOKEN_ADDRESS, GOODDOLLAR_UBI_SCHEME_ADDRESS, isGoodDollarUsdReservePair, } from "./config/gooddollar.js";
+export type { GoodDollarReserveSwapParams } from "./services/gooddollar.service.js";
 export type { CarbonPrepareResult, CarbonRestSuccess, } from "./types/carbon.js";
 export type { CarbonWriteBody } from "./services/carbon.service.js";
 export { CARBON_APP_BASE_URL, CARBON_CHAIN, CELO_CARBON_CONTRACTS, DEFAULT_CARBON_REST_BASE_URL, carbonActivityDeepLink, } from "./config/carbon.js";

package/build/index.js

@@ -56,7 +56,7 @@ export { serializePreparedFlow } from "./types/prepared.js";
 export { AAVE_POOL, AAVE_SUPPORTED_SYMBOLS, resolveAaveAsset, } from "./config/aave.js";
 export { CHAIN, DEFAULT_RPC_URL } from "./config/chains.js";
 export { appendCelinaCalldataTag, CELINA_DATA_SUFFIX, } from "./config/celina-tag.js";
-export { GOODDOLLAR_IDENTITY_ADDRESS, GOODDOLLAR_UBI_SCHEME_ADDRESS, } from "./config/gooddollar.js";
+export { GOODDOLLAR_CUSD_EXCHANGE_ID, GOODDOLLAR_IDENTITY_ADDRESS, GOODDOLLAR_MENTO_BROKER, GOODDOLLAR_MENTO_EXCHANGE_PROVIDER, GOODDOLLAR_RESERVE_COLLATERAL, GOODDOLLAR_TOKEN_ADDRESS, GOODDOLLAR_UBI_SCHEME_ADDRESS, isGoodDollarUsdReservePair, } from "./config/gooddollar.js";
 export { CARBON_APP_BASE_URL, CARBON_CHAIN, CELO_CARBON_CONTRACTS, DEFAULT_CARBON_REST_BASE_URL, carbonActivityDeepLink, } from "./config/carbon.js";
 export { resolveCarbonTokenAddress, normalizeCarbonWriteBody, CARBON_WRITE_TOKEN_FIELDS, } from "./utils/carbon-token.js";
 export { buildCarbonExecutionSteps } from "./utils/carbon-execution.js";

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/build/services/ens.service.d.ts

@@ -17,7 +17,7 @@ export declare class EnsService {
     constructor(ensClientFactory: EnsClientFactory);
     /**
      * Resolve an ENS name on Celo or Ethereum to an address.
-     * @param name - ENS name (e.g. `vitalik.eth`)
+     * @param name - ENS name (e.g. `andrewkimjoseph.celo.eth`)
      * @param chain - `"celo"` tries Celo coin type first, then Ethereum; `"ethereum"` uses ETH only
      * @throws When no address record exists for the name
      */

package/build/services/ens.service.js

@@ -14,7 +14,7 @@ export class EnsService {
     }
     /**
      * Resolve an ENS name on Celo or Ethereum to an address.
-     * @param name - ENS name (e.g. `vitalik.eth`)
+     * @param name - ENS name (e.g. `andrewkimjoseph.celo.eth`)
      * @param chain - `"celo"` tries Celo coin type first, then Ethereum; `"ethereum"` uses ETH only
      * @throws When no address record exists for the name
      */

package/build/services/gooddollar.service.d.ts

@@ -1,8 +1,16 @@
 import type { CeloClientFactory } from "../clients/celo-client.js";
 import { type SerializedPreparedFlow } from "../types/prepared.js";
-/** GoodDollar IdentityV4 whitelist, reverification, and daily UBI claim preparation. */
+/** Optional parameters for GoodDollar reserve swap prepares. */
+export interface GoodDollarReserveSwapParams {
+    /** Max slippage tolerance in percent (default `0.5`). */
+    slippageTolerance?: number;
+    /** Address receiving output tokens (default: `from`). */
+    recipient?: `0x${string}`;
+}
+/** GoodDollar IdentityV4 whitelist, reverification, daily UBI claim, and reserve swap preparation. */
 export declare class GoodDollarService {
     private readonly clientFactory;
+    private readonly tokenService;
     constructor(clientFactory: CeloClientFactory);
     private getPublicClient;
     /**
@@ -86,6 +94,29 @@ export declare class GoodDollarService {
      * Validates whitelist, entitlement, and simulates gas before returning steps.
      */
     prepareClaimUbi(from: `0x${string}`): Promise<SerializedPreparedFlow>;
+    private resolveReservePair;
+    private reserveOptions;
+    private baseReserveQuoteFields;
+    /**
+     * Expected GoodDollar reserve output for G$ ↔ USDm — no wallet required.
+     */
+    getReserveQuote(tokenIn: string, tokenOut: string, amount: string, from?: `0x${string}`): Promise<{
+        protocol: "gooddollar_reserve";
+        network: "mainnet";
+        tokenIn: string;
+        tokenOut: string;
+        amountIn: string;
+        expectedOut: string;
+        routeHops: number;
+        broker: "0x88de45906D4F5a57315c133620cfa484cB297541";
+        exchangeProvider: "0x2fFBB49055d487DdBBb0C052Cd7c2a02A7971e41";
+        exchangeId: "0xba77f5c7bb3317643c6d81d1ef3f9913561741d92095f88efa402faf2cbe9124";
+    }>;
+    private buildReserveSwap;
+    /**
+     * Build unsigned GoodDollar reserve swap steps (approve + swapIn when needed).
+     */
+    prepareReserveSwap(from: `0x${string}`, tokenIn: string, tokenOut: string, amount: string, params?: GoodDollarReserveSwapParams): Promise<SerializedPreparedFlow>;
     private effectiveAuthCount;
     private fetchReverifyDaysOptions;
     private buildReverificationProgress;

package/build/services/gooddollar.service.js

@@ -1,12 +1,15 @@
 /**
- * GoodDollar IdentityV4 whitelist and reverification reads on Celo mainnet.
+ * GoodDollar IdentityV4 whitelist, reverification reads, UBI claims, and reserve swaps on Celo mainnet.
  */
-import { concat, encodeFunctionData, formatUnits } from "viem";
+import { concat, encodeFunctionData, erc20Abi, formatUnits, maxUint256, } from "viem";
+import { goodDollarBrokerAbi } from "../abis/gooddollar-broker.js";
 import { goodDollarIdentityAbi } from "../abis/gooddollar-identity.js";
 import { ubiSchemeAbi } from "../abis/ubi-scheme.js";
-import { GOODDOLLAR_IDENTITY_ADDRESS, GOODDOLLAR_UBI_SCHEME_ADDRESS, } from "../config/gooddollar.js";
+import { GOODDOLLAR_CUSD_EXCHANGE_ID, GOODDOLLAR_IDENTITY_ADDRESS, GOODDOLLAR_MENTO_BROKER, GOODDOLLAR_MENTO_EXCHANGE_PROVIDER, GOODDOLLAR_RESERVE_COLLATERAL, GOODDOLLAR_TOKEN_ADDRESS, GOODDOLLAR_UBI_SCHEME_ADDRESS, isGoodDollarUsdReservePair, } from "../config/gooddollar.js";
 import { CELINA_DATA_SUFFIX } from "../config/celina-tag.js";
 import { serializePreparedFlow, } from "../types/prepared.js";
+import { ALLOWANCE_MAPPING_SLOTS, erc20AllowanceStateOverride, } from "../utils/erc20-allowance-storage.js";
+import { TokenService } from "./token.service.js";
 import { formatUnixDate } from "../utils/format-date.js";
 import { formatDuration } from "../utils/format-duration.js";
 import { formatUnixDateTimeUtc, formatUnixIso, } from "../utils/format-unix-datetime.js";
@@ -27,11 +30,37 @@ function statusLabel(status) {
 function taggedCalldata(data) {
     return concat([data, CELINA_DATA_SUFFIX]);
 }
-/** GoodDollar IdentityV4 whitelist, reverification, and daily UBI claim preparation. */
+const DEFAULT_RESERVE_SLIPPAGE = 0.5;
+function trimDisplayDecimals(value) {
+    const num = Number(value);
+    if (!Number.isFinite(num)) {
+        return value;
+    }
+    if (Math.abs(num) >= 1000) {
+        return num.toLocaleString(undefined, { maximumFractionDigits: 2 });
+    }
+    if (Math.abs(num) >= 1) {
+        return num.toLocaleString(undefined, { maximumFractionDigits: 4 });
+    }
+    return num.toLocaleString(undefined, { maximumSignificantDigits: 6 });
+}
+function applySlippage(amountOut, slippagePercent) {
+    const bps = BigInt(Math.round(slippagePercent * 100));
+    return (amountOut * (10000n - bps)) / 10000n;
+}
+function tokenAddress(token) {
+    if (token.address === "native") {
+        throw new Error(`${token.symbol} is native CELO; GoodDollar reserve swaps require ERC-20 tokens.`);
+    }
+    return token.address;
+}
+/** GoodDollar IdentityV4 whitelist, reverification, daily UBI claim, and reserve swap preparation. */
 export class GoodDollarService {
     clientFactory;
+    tokenService;
     constructor(clientFactory) {
         this.clientFactory = clientFactory;
+        this.tokenService = new TokenService(clientFactory);
     }
     getPublicClient() {
         return this.clientFactory.getClients().public;
@@ -287,6 +316,187 @@ export class GoodDollarService {
         };
         return serializePreparedFlow(flow);
     }
+    resolveReservePair(tokenIn, tokenOut) {
+        if (!isGoodDollarUsdReservePair(tokenIn, tokenOut)) {
+            throw new Error(`No GoodDollar reserve route for ${tokenIn} → ${tokenOut}. Supported: GoodDollar ↔ USDm.`);
+        }
+        const resolvedIn = this.tokenService.resolveToken(tokenIn);
+        const resolvedOut = this.tokenService.resolveToken(tokenOut);
+        const tokenInAddr = tokenAddress(resolvedIn);
+        const tokenOutAddr = tokenAddress(resolvedOut);
+        const gdAddr = GOODDOLLAR_TOKEN_ADDRESS.toLowerCase();
+        const collateralAddr = GOODDOLLAR_RESERVE_COLLATERAL.toLowerCase();
+        const inLower = tokenInAddr.toLowerCase();
+        const outLower = tokenOutAddr.toLowerCase();
+        if (!((inLower === gdAddr && outLower === collateralAddr) ||
+            (inLower === collateralAddr && outLower === gdAddr))) {
+            throw new Error(`No GoodDollar reserve route for ${resolvedIn.symbol} → ${resolvedOut.symbol}.`);
+        }
+        return { resolvedIn, resolvedOut, tokenInAddr, tokenOutAddr };
+    }
+    reserveOptions(params) {
+        return {
+            slippageTolerance: params?.slippageTolerance ?? DEFAULT_RESERVE_SLIPPAGE,
+        };
+    }
+    baseReserveQuoteFields(resolvedIn, resolvedOut, amount, expectedOutWei) {
+        return {
+            protocol: "gooddollar_reserve",
+            network: "mainnet",
+            tokenIn: resolvedIn.symbol,
+            tokenOut: resolvedOut.symbol,
+            amountIn: amount,
+            expectedOut: formatUnits(expectedOutWei, resolvedOut.decimals),
+            routeHops: 1,
+            broker: GOODDOLLAR_MENTO_BROKER,
+            exchangeProvider: GOODDOLLAR_MENTO_EXCHANGE_PROVIDER,
+            exchangeId: GOODDOLLAR_CUSD_EXCHANGE_ID,
+        };
+    }
+    /**
+     * Expected GoodDollar reserve output for G$ ↔ USDm — no wallet required.
+     */
+    async getReserveQuote(tokenIn, tokenOut, amount, from) {
+        const { public: client } = this.clientFactory.getClients();
+        const { resolvedIn, resolvedOut, tokenInAddr, tokenOutAddr } = this.resolveReservePair(tokenIn, tokenOut);
+        const amountInWei = this.tokenService.parseAmount(amount, resolvedIn.decimals);
+        if (from) {
+            await this.tokenService.assertSpendableBalance(from, resolvedIn, amount, {
+                spendToken: tokenInAddr,
+            });
+        }
+        const expectedOutWei = await client.readContract({
+            address: GOODDOLLAR_MENTO_BROKER,
+            abi: goodDollarBrokerAbi,
+            functionName: "getAmountOut",
+            args: [
+                GOODDOLLAR_MENTO_EXCHANGE_PROVIDER,
+                GOODDOLLAR_CUSD_EXCHANGE_ID,
+                tokenInAddr,
+                tokenOutAddr,
+                amountInWei,
+            ],
+        });
+        return this.baseReserveQuoteFields(resolvedIn, resolvedOut, amount, expectedOutWei);
+    }
+    async buildReserveSwap(from, tokenIn, tokenOut, amount, params) {
+        const { public: client } = this.clientFactory.getClients();
+        const { resolvedIn, resolvedOut, tokenInAddr, tokenOutAddr } = this.resolveReservePair(tokenIn, tokenOut);
+        const recipient = params?.recipient ?? from;
+        const amountInWei = this.tokenService.parseAmount(amount, resolvedIn.decimals);
+        const { slippageTolerance } = this.reserveOptions(params);
+        await this.tokenService.assertSpendableBalance(from, resolvedIn, amount, {
+            spendToken: tokenInAddr,
+        });
+        const expectedOutWei = await client.readContract({
+            address: GOODDOLLAR_MENTO_BROKER,
+            abi: goodDollarBrokerAbi,
+            functionName: "getAmountOut",
+            args: [
+                GOODDOLLAR_MENTO_EXCHANGE_PROVIDER,
+                GOODDOLLAR_CUSD_EXCHANGE_ID,
+                tokenInAddr,
+                tokenOutAddr,
+                amountInWei,
+            ],
+        });
+        const amountOutMin = applySlippage(expectedOutWei, slippageTolerance);
+        const swapData = taggedCalldata(encodeFunctionData({
+            abi: goodDollarBrokerAbi,
+            functionName: "swapIn",
+            args: [
+                GOODDOLLAR_MENTO_EXCHANGE_PROVIDER,
+                GOODDOLLAR_CUSD_EXCHANGE_ID,
+                tokenInAddr,
+                tokenOutAddr,
+                amountInWei,
+                amountOutMin,
+            ],
+        }));
+        return {
+            client,
+            from,
+            recipient,
+            resolvedIn,
+            resolvedOut,
+            tokenInAddr,
+            tokenOutAddr,
+            amount,
+            amountInWei,
+            expectedOutWei,
+            amountOutMin,
+            swapData,
+        };
+    }
+    /**
+     * Build unsigned GoodDollar reserve swap steps (approve + swapIn when needed).
+     */
+    async prepareReserveSwap(from, tokenIn, tokenOut, amount, params) {
+        const built = await this.buildReserveSwap(from, tokenIn, tokenOut, amount, params);
+        const { client, resolvedIn, resolvedOut, tokenInAddr, amountInWei, expectedOutWei, swapData, recipient, } = built;
+        const displayIn = trimDisplayDecimals(built.amount);
+        const displayOut = trimDisplayDecimals(formatUnits(expectedOutWei, resolvedOut.decimals));
+        const steps = [];
+        const allowance = await client.readContract({
+            address: tokenInAddr,
+            abi: erc20Abi,
+            functionName: "allowance",
+            args: [from, GOODDOLLAR_MENTO_BROKER],
+        });
+        if (allowance < amountInWei) {
+            steps.push({
+                kind: "erc20",
+                to: tokenInAddr,
+                data: taggedCalldata(encodeFunctionData({
+                    abi: erc20Abi,
+                    functionName: "approve",
+                    args: [GOODDOLLAR_MENTO_BROKER, maxUint256],
+                })),
+                value: "0",
+                description: `Approve ${resolvedIn.symbol} for GoodDollar reserve`,
+            });
+        }
+        steps.push({
+            kind: "contract",
+            to: GOODDOLLAR_MENTO_BROKER,
+            data: swapData,
+            value: "0",
+            description: `Swap ${displayIn} ${resolvedIn.symbol} → ~${displayOut} ${resolvedOut.symbol} via GoodDollar reserve`,
+        });
+        const swapEstimateRequest = {
+            account: from,
+            to: GOODDOLLAR_MENTO_BROKER,
+            data: swapData,
+            value: 0n,
+        };
+        if (allowance < amountInWei) {
+            for (const mappingSlot of ALLOWANCE_MAPPING_SLOTS) {
+                try {
+                    await client.estimateGas({
+                        ...swapEstimateRequest,
+                        stateOverride: erc20AllowanceStateOverride(tokenInAddr, from, GOODDOLLAR_MENTO_BROKER, maxUint256, mappingSlot),
+                    });
+                    break;
+                }
+                catch (error) {
+                    const isLast = mappingSlot === ALLOWANCE_MAPPING_SLOTS.at(-1);
+                    if (isLast) {
+                        throw error;
+                    }
+                }
+            }
+        }
+        else {
+            await client.estimateGas(swapEstimateRequest);
+        }
+        const flow = {
+            network: "mainnet",
+            from,
+            summary: `GoodDollar reserve: ${displayIn} ${resolvedIn.symbol} → ${displayOut} ${resolvedOut.symbol}${recipient !== from ? ` (recipient ${recipient})` : ""}`,
+            steps,
+        };
+        return serializePreparedFlow(flow);
+    }
     effectiveAuthCount(dateAuthenticated, authCount, optionsLength) {
         if (dateAuthenticated < LEGACY_AUTH_CUTOFF) {
             return optionsLength - 1;