@nadohq/client 0.33.0 → 0.35.0

package/dist/types-CFgxXCy2.d.ts

@@ -0,0 +1,18 @@
+import { Address } from "viem";
+
+//#region src/apis/rewards/types.d.ts
+/**
+ * Identifies an Airdrop contract to read from or write to. The address is returned by the indexer
+ * as `wallet.claim.airdropAddress` of a cash incentives event.
+ */
+interface AirdropAddressParams {
+  /** Airdrop contract holding the reward. */
+  airdropAddress: Address;
+}
+interface GetClaimedAirdropAmountsParams extends AirdropAddressParams {
+  /** Wallet to look up the claimed amounts for. */
+  address: Address;
+}
+//#endregion
+export { GetClaimedAirdropAmountsParams as n, AirdropAddressParams as t };
+//# sourceMappingURL=types-CFgxXCy2.d.ts.map

package/dist/types-CFgxXCy2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-CFgxXCy2.d.ts","names":[],"sources":["../src/apis/rewards/src/apis/rewards/types.ts"],"mappings":";;;;;AAMA;;UAAiB,oBAAA;EAEf;EAAA,cAAA,EAAgB,OAAO;AAAA;AAAA,UAGR,8BAAA,SAAuC,oBAAoB;;EAE1E,OAAA,EAAS,OAAA;AAAA"}

package/dist/{types-DnBjJCnd.d.ts → types-OZlzeknc.d.ts}

@@ -27,4 +27,4 @@ interface MintMockERC20Params {
 }
 //#endregion
 export { MintMockERC20Params as a, TransferQuoteParams as c, GetTokenWalletBalanceParams as i, WithdrawCollateralParams as l, BurnNlpParams as n, MintNlpParams as o, GetTokenAllowanceParams as r, ProductIdOrTokenAddress as s, ApproveAllowanceParams as t, WithdrawCollateralV2Params as u };
-//# sourceMappingURL=types-DnBjJCnd.d.ts.map
+//# sourceMappingURL=types-OZlzeknc.d.ts.map

package/dist/{types-DnBjJCnd.d.ts.map → types-OZlzeknc.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"types-DnBjJCnd.d.ts","names":[],"sources":["../src/apis/spot/src/apis/spot/types.ts"],"mappings":";;;;;KAUY,uBAAA;EAEN,SAAA;AAAA;EAGA,YAAY;AAAA;AAAA,KAGb,gBAAA;EACH,OAAA;AAAA,IACE,uBAAuB;AAAA,KAEf,sBAAA,GAAyB,uBAAA;EACnC,MAAA,EAAQ,YAAY;AAAA;AAAA,KAGV,2BAAA,GAA8B,gBAAgB;AAAA,KAE9C,uBAAA,GAA0B,gBAAgB;AAAA,KAE1C,wBAAA,GAA2B,uBAAA,CACrC,uBAAA,CAAwB,8BAAA;AAAA,KAGd,0BAAA,GAA6B,uBAAA,CACvC,uBAAA,CAAwB,gCAAA;AAAA,KAGd,mBAAA,GAAsB,uBAAA,CAChC,uBAAA,CAAwB,yBAAA;AAAA,KAGd,aAAA,GAAgB,uBAAA,CAC1B,uBAAA,CAAwB,mBAAA;AAAA,KAGd,aAAA,GAAgB,uBAAA,CAC1B,uBAAA,CAAwB,mBAAA;AAAA,UAGT,mBAAA;EACf,SAAA;EACA,MAAA,EAAQ,YAAY;AAAA"}
+{"version":3,"file":"types-OZlzeknc.d.ts","names":[],"sources":["../src/apis/spot/src/apis/spot/types.ts"],"mappings":";;;;;KAUY,uBAAA;EAEN,SAAA;AAAA;EAGA,YAAY;AAAA;AAAA,KAGb,gBAAA;EACH,OAAA;AAAA,IACE,uBAAuB;AAAA,KAEf,sBAAA,GAAyB,uBAAA;EACnC,MAAA,EAAQ,YAAY;AAAA;AAAA,KAGV,2BAAA,GAA8B,gBAAgB;AAAA,KAE9C,uBAAA,GAA0B,gBAAgB;AAAA,KAE1C,wBAAA,GAA2B,uBAAA,CACrC,uBAAA,CAAwB,8BAAA;AAAA,KAGd,0BAAA,GAA6B,uBAAA,CACvC,uBAAA,CAAwB,gCAAA;AAAA,KAGd,mBAAA,GAAsB,uBAAA,CAChC,uBAAA,CAAwB,yBAAA;AAAA,KAGd,aAAA,GAAgB,uBAAA,CAC1B,uBAAA,CAAwB,mBAAA;AAAA,KAGd,aAAA,GAAgB,uBAAA,CAC1B,uBAAA,CAAwB,mBAAA;AAAA,UAGT,mBAAA;EACf,SAAA;EACA,MAAA,EAAQ,YAAY;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nadohq/client",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "type": "module",
   "sideEffects": false,
   "description": "Nado SDK client — unified API for trading, market data, and collateral management on Nado",
@@ -41,11 +41,11 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "@nadohq/engine-client": "^0.33.0",
-    "@nadohq/indexer-client": "^0.33.0",
-    "@nadohq/mobile-client": "^0.33.0",
-    "@nadohq/shared": "^0.33.0",
-    "@nadohq/trigger-client": "^0.33.0",
+    "@nadohq/engine-client": "^0.35.0",
+    "@nadohq/indexer-client": "^0.35.0",
+    "@nadohq/mobile-client": "^0.35.0",
+    "@nadohq/shared": "^0.35.0",
+    "@nadohq/trigger-client": "^0.35.0",
     "ts-mixer": "6.0.4"
   },
   "peerDependencies": {
@@ -56,5 +56,5 @@
     "bignumber.js": "11.1.1",
     "viem": "2.52.0"
   },
-  "gitHead": "7743524dd36aa73253da8c01ffba4f4085dcffcb"
+  "gitHead": "232349cb0f432b024dab1b1c623e8ad3b74b8f85"
 }

package/src/apis/rewards/BaseRewardsAPI.ts

@@ -0,0 +1,20 @@
+import { AIRDROP_ABI, ContractInstance } from '@nadohq/shared';
+import { getContract } from 'viem';
+import { BaseNadoAPI } from '../base';
+import { AirdropAddressParams } from './types';
+
+export class BaseRewardsAPI extends BaseNadoAPI {
+  /**
+   * Builds a contract instance for an Airdrop contract. Airdrop addresses are not part of the core
+   * Nado deployment; they are returned by the indexer alongside a claim proof.
+   */
+  protected getAirdropContract({
+    airdropAddress,
+  }: AirdropAddressParams): ContractInstance<typeof AIRDROP_ABI> {
+    return getContract({
+      abi: AIRDROP_ABI,
+      address: airdropAddress,
+      client: this.context.walletClient ?? this.context.publicClient,
+    });
+  }
+}

package/src/apis/rewards/RewardsExecuteAPI.ts

@@ -0,0 +1,77 @@
+import {
+  AirdropClaimProof,
+  claimAirdropRewards,
+  isWriteableContract,
+  toBigNumber,
+  WalletNotProvidedError,
+} from '@nadohq/shared';
+import { Hash } from 'viem';
+import { BaseRewardsAPI } from './BaseRewardsAPI';
+
+export class RewardsExecuteAPI extends BaseRewardsAPI {
+  /**
+   * Claims every currently claimable cash incentives reward for the connected wallet in a single
+   * transaction, fetching the merkle proofs from the indexer itself.
+   *
+   * The Airdrop contract verifies proofs against `msg.sender`, so this can only ever claim for the
+   * connected wallet. Rewards that were already settled onchain are dropped before submitting,
+   * since the indexer keeps reporting them as claimable, as are rewards whose week the contract
+   * does not know about yet.
+   *
+   * @returns Hash of the submitted claim transaction.
+   * @throws `WalletNotProvidedError` when no wallet client is available to sign with.
+   * @throws When the indexer reports nothing claimable, or when no claimable reward is ready to
+   * claim onchain because each has either already been claimed or is not yet registered on the
+   * airdrop contract.
+   */
+  async claimCashIncentives(): Promise<Hash> {
+    const walletAddress = this.getWalletClientAddress();
+    const { events } = await this.context.indexerClient.getCashIncentives({
+      address: walletAddress,
+    });
+
+    const claimableRewards = events
+      .map((event) => event.wallet.claim)
+      .filter((claim) => claim.status === 'claimable');
+
+    // Every reward currently comes from the same airdrop contract, so they claim in one transaction
+    const airdropAddress = claimableRewards[0]?.airdropAddress;
+    if (!airdropAddress) {
+      throw new Error(
+        'No claimable cash incentives rewards found for this wallet.',
+      );
+    }
+
+    const airdropContract = this.getAirdropContract({ airdropAddress });
+    if (!isWriteableContract(airdropContract)) {
+      throw new WalletNotProvidedError();
+    }
+
+    // Indexed by week, 1-based, with an unused slot 0, so the last valid week is `length - 1`
+    const claimed = await airdropContract.read.getClaimed([walletAddress]);
+
+    const unclaimedProofs: AirdropClaimProof[] = [];
+    for (const { week, totalAmount, proof } of claimableRewards) {
+      // A reward can be published by the indexer before its merkle root is registered onchain, so
+      // skip those weeks rather than failing and blocking the weeks that are ready to claim
+      if (week < 1 || week >= claimed.length) {
+        continue;
+      }
+      // Claimed amounts are cumulative, so anything below the entitlement is still claimable
+      if (toBigNumber(claimed[week]).lt(toBigNumber(totalAmount))) {
+        unclaimedProofs.push({ week, totalAmount, proof });
+      }
+    }
+
+    if (unclaimedProofs.length === 0) {
+      throw new Error(
+        `No cash incentives rewards are ready to claim from the airdrop contract at ${airdropAddress}. Each claimable reward has either already been claimed onchain, or is not yet registered on the contract (it reports ${claimed.length - 1} week(s)).`,
+      );
+    }
+
+    return claimAirdropRewards({
+      airdropContract,
+      claimProofs: unclaimedProofs,
+    });
+  }
+}

package/src/apis/rewards/RewardsQueryAPI.ts

@@ -0,0 +1,35 @@
+import { GetIndexerCashIncentivesParams } from '@nadohq/indexer-client';
+import { BaseRewardsAPI } from './BaseRewardsAPI';
+import { GetClaimedAirdropAmountsParams } from './types';
+
+export class RewardsQueryAPI extends BaseRewardsAPI {
+  /**
+   * Gets cash incentives progress and claim state for a wallet. Each event's `wallet.claim` is
+   * tagged on `status`, and carries the merkle proof needed to claim onchain when that status is
+   * `claimable`.
+   *
+   * @param params
+   */
+  async getCashIncentives(params: GetIndexerCashIncentivesParams) {
+    return this.context.indexerClient.getCashIncentives(params);
+  }
+
+  /**
+   * Gets the cumulative amounts already claimed by a wallet from an airdrop contract, in raw token
+   * units, indexed directly by `week`.
+   *
+   * Weeks are 1-based, so index 0 is always zero and the array length is one greater than the
+   * number of reward events. A week is fully claimed when its entry equals the `totalAmount` of the
+   * corresponding claim proof; a smaller value means there is still an amount to claim, since
+   * entries are cumulative rather than per-transaction.
+   *
+   * @param params
+   */
+  async getClaimedAirdropAmounts({
+    address,
+    ...rest
+  }: GetClaimedAirdropAmountsParams): Promise<readonly bigint[]> {
+    const airdrop = this.getAirdropContract(rest);
+    return airdrop.read.getClaimed([address]);
+  }
+}

package/src/apis/rewards/index.ts

@@ -0,0 +1,11 @@
+import { Mixin } from 'ts-mixer';
+import { RewardsExecuteAPI } from './RewardsExecuteAPI';
+import { RewardsQueryAPI } from './RewardsQueryAPI';
+
+/**
+ * Combined rewards API for querying cash incentives progress and claiming rewards onchain
+ * through the Airdrop contract.
+ */
+export class RewardsAPI extends Mixin(RewardsExecuteAPI, RewardsQueryAPI) {}
+
+export * from './types';

package/src/apis/rewards/types.ts

@@ -0,0 +1,15 @@
+import { Address } from 'viem';
+
+/**
+ * Identifies an Airdrop contract to read from or write to. The address is returned by the indexer
+ * as `wallet.claim.airdropAddress` of a cash incentives event.
+ */
+export interface AirdropAddressParams {
+  /** Airdrop contract holding the reward. */
+  airdropAddress: Address;
+}
+
+export interface GetClaimedAirdropAmountsParams extends AirdropAddressParams {
+  /** Wallet to look up the claimed amounts for. */
+  address: Address;
+}

package/src/apis/spot/SpotExecuteAPI.ts

@@ -20,6 +20,10 @@ import {
 
 export class SpotExecuteAPI extends BaseSpotAPI {
   async deposit(params: DepositCollateralParams) {
+    if (!isWriteableContract(this.context.contracts.endpoint)) {
+      throw new WalletNotProvidedError();
+    }
+  
     return depositCollateral({
       endpoint: this.context.contracts.endpoint,
       subaccountName: params.subaccountName,

package/src/client.ts

@@ -1,6 +1,7 @@
 import { WalletClientWithAccount } from '@nadohq/shared';
 import { MarketAPI } from './apis/market';
 import { PerpAPI } from './apis/perp';
+import { RewardsAPI } from './apis/rewards';
 import { SpotAPI } from './apis/spot';
 import { SubaccountAPI } from './apis/subaccount';
 import { WebsocketAPI } from './apis/ws';
@@ -16,6 +17,7 @@ export class NadoClient {
   subaccount!: SubaccountAPI;
   spot!: SpotAPI;
   perp!: PerpAPI;
+  rewards!: RewardsAPI;
   ws!: WebsocketAPI;
 
   constructor(context: NadoClientContext) {
@@ -48,6 +50,7 @@ export class NadoClient {
         indexerEndpoint: this.context.indexerClient.opts.url,
         triggerEndpoint: this.context.triggerClient.opts.url,
         mobileEndpoint: this.context.mobileClient.opts.url,
+        clientType: this.context.clientType,
       },
       {
         walletClient,
@@ -65,6 +68,7 @@ export class NadoClient {
     this.subaccount = new SubaccountAPI(context);
     this.spot = new SpotAPI(context);
     this.perp = new PerpAPI(context);
+    this.rewards = new RewardsAPI(context);
     this.ws = new WebsocketAPI(context);
   }
 }

package/src/context.ts

@@ -33,10 +33,12 @@ export interface NadoClientContext {
   indexerClient: IndexerClient;
   triggerClient: TriggerClient;
   mobileClient: MobileClient;
+  // If provided, identifies the calling client, sent as a header with every request made by the service clients above
+  clientType?: string;
 }
 
 /**
- * Args for creating a context
+ * Args for creating a context with custom endpoints
  */
 interface NadoClientContextOpts {
   contractAddresses: NadoDeploymentAddresses;
@@ -44,6 +46,15 @@ interface NadoClientContextOpts {
   indexerEndpoint: string;
   triggerEndpoint: string;
   mobileEndpoint: string;
+  clientType?: string;
+}
+
+/**
+ * Args for creating a context with the default endpoints of a chain env
+ */
+interface NadoClientContextChainEnvOpts {
+  chainEnv: ChainEnv;
+  clientType?: string;
 }
 
 /**
@@ -54,7 +65,12 @@ export type CreateNadoClientContextAccountOpts = Pick<
   'walletClient' | 'linkedSignerWalletClient' | 'publicClient'
 >;
 
-export type CreateNadoClientContextOpts = NadoClientContextOpts | ChainEnv;
+/**
+ * Args for creating a context, either fully custom endpoints or a chain env with default endpoints.
+ */
+export type CreateNadoClientContextOpts =
+  | NadoClientContextOpts
+  | NadoClientContextChainEnvOpts;
 
 /**
  * Utility function to create client context from options
@@ -72,19 +88,21 @@ export function createClientContext(
     indexerEndpoint,
     triggerEndpoint,
     mobileEndpoint,
+    clientType,
   } = ((): NadoClientContextOpts => {
-    // Custom options
-    if (typeof opts === 'object') {
+    // Custom endpoint options
+    if (!('chainEnv' in opts)) {
       return opts;
     }
 
-    const chainEnv = opts;
+    const { chainEnv, clientType } = opts;
     return {
       contractAddresses: NADO_DEPLOYMENTS[chainEnv],
       engineEndpoint: ENGINE_CLIENT_ENDPOINTS[chainEnv],
       indexerEndpoint: INDEXER_CLIENT_ENDPOINTS[chainEnv],
       triggerEndpoint: TRIGGER_CLIENT_ENDPOINTS[chainEnv],
       mobileEndpoint: MOBILE_CLIENT_ENDPOINTS[chainEnv],
+      clientType,
     };
   })();
   const { publicClient, walletClient, linkedSignerWalletClient } = accountOpts;
@@ -132,25 +150,30 @@ export function createClientContext(
       }),
     },
     contractAddresses,
+    clientType,
     engineClient: new EngineClient({
       url: engineEndpoint,
       walletClient,
       linkedSignerWalletClient,
+      clientType,
     }),
     indexerClient: new IndexerClient({
       url: indexerEndpoint,
       walletClient,
       linkedSignerWalletClient,
+      clientType,
     }),
     triggerClient: new TriggerClient({
       url: triggerEndpoint,
       walletClient,
       linkedSignerWalletClient,
+      clientType,
     }),
     mobileClient: new MobileClient({
       url: mobileEndpoint,
       walletClient,
       linkedSignerWalletClient,
+      clientType,
     }),
   };
 }

package/src/createNadoClient.ts

@@ -9,8 +9,14 @@ import {
  * Creates a Nado client from given options.
  * {@label CLIENT}
  *
- * @param opts
+ * @param opts - A chain env or custom endpoints.
  * @param accountOpts
+ *
+ * @example
+ * const nadoClient = createNadoClient(
+ *   { chainEnv: 'inkMainnet' },
+ *   { publicClient, walletClient },
+ * );
  */
 export function createNadoClient(
   opts: CreateNadoClientContextOpts,

package/src/index.ts

@@ -4,6 +4,7 @@ export * from './createNadoClient';
 
 export * from './apis/market';
 export * from './apis/perp';
+export * from './apis/rewards';
 export * from './apis/spot';
 export * from './apis/subaccount';
 

package/dist/PerpExecuteAPI-DcAur1dM.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"PerpExecuteAPI-DcAur1dM.d.ts","names":[],"sources":["../src/apis/perp/src/apis/perp/PerpExecuteAPI.ts"],"mappings":";;;cAEa,cAAA,SAAuB,WAAW"}

package/dist/PerpExecuteAPI-bgOnDMQR.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"PerpExecuteAPI-bgOnDMQR.d.cts","names":[],"sources":["../src/apis/perp/src/apis/perp/PerpExecuteAPI.ts"],"mappings":";;;cAEa,cAAA,SAAuB,WAAW"}

package/dist/context-CHBPiOx6.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"context-CHBPiOx6.d.cts","names":[],"sources":["../src/src/context.ts"],"mappings":";;;;;;;;;;AAwBA;UAAiB,iBAAA;EACf,YAAA,EAAc,YAAA;EACd,YAAA,GAAe,uBAAA;EAEf,wBAAA,GAA2B,uBAAA;EAC3B,SAAA,EAAW,aAAA;EACX,iBAAA,EAAmB,uBAAA;EACnB,YAAA,EAAc,YAAA;EACd,aAAA,EAAe,aAAA;EACf,aAAA,EAAe,aAAA;EACf,YAAA,EAAc,YAAA;AAAA;;;;UAMN,qBAAA;EACR,iBAAA,EAAmB,uBAAuB;EAC1C,cAAA;EACA,eAAA;EACA,eAAA;EACA,cAAA;AAAA;;;;KAMU,kCAAA,GAAqC,IAAI,CACnD,iBAAA;AAAA,KAIU,2BAAA,GAA8B,qBAAA,GAAwB,QAAQ;;;;;;;iBAQ1D,mBAAA,CACd,IAAA,EAAM,2BAAA,EACN,WAAA,EAAa,kCAAA,GACZ,iBAAA"}

package/dist/context-D1xmE2Rd.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"context-D1xmE2Rd.d.ts","names":[],"sources":["../src/src/context.ts"],"mappings":";;;;;;;;;;AAwBA;UAAiB,iBAAA;EACf,YAAA,EAAc,YAAA;EACd,YAAA,GAAe,uBAAA;EAEf,wBAAA,GAA2B,uBAAA;EAC3B,SAAA,EAAW,aAAA;EACX,iBAAA,EAAmB,uBAAA;EACnB,YAAA,EAAc,YAAA;EACd,aAAA,EAAe,aAAA;EACf,aAAA,EAAe,aAAA;EACf,YAAA,EAAc,YAAA;AAAA;;;;UAMN,qBAAA;EACR,iBAAA,EAAmB,uBAAuB;EAC1C,cAAA;EACA,eAAA;EACA,eAAA;EACA,cAAA;AAAA;;;;KAMU,kCAAA,GAAqC,IAAI,CACnD,iBAAA;AAAA,KAIU,2BAAA,GAA8B,qBAAA,GAAwB,QAAQ;;;;;;;iBAQ1D,mBAAA,CACd,IAAA,EAAM,2BAAA,EACN,WAAA,EAAa,kCAAA,GACZ,iBAAA"}

package/dist/index-Bx-PsDsb.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-Bx-PsDsb.d.cts","names":[],"sources":["../src/apis/perp/src/apis/perp/index.ts"],"mappings":";;;;cAE8C,YAAA;cAEjC,OAAA,SAAgB,YAAmC"}

package/dist/index-D2pKqx7b.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-D2pKqx7b.d.cts","names":[],"sources":["../src/apis/market/src/apis/market/index.ts"],"mappings":";;;;cAIwB,cAAA;cAEX,SAAA,SAAkB,cAAuC"}

package/dist/index-DIlwbefm.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-DIlwbefm.d.ts","names":[],"sources":["../src/apis/perp/src/apis/perp/index.ts"],"mappings":";;;;cAE8C,YAAA;cAEjC,OAAA,SAAgB,YAAmC"}

package/dist/index-DPNd9PR1.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-DPNd9PR1.d.ts","names":[],"sources":["../src/apis/spot/src/apis/spot/index.ts"],"mappings":";;;;cAE8C,YAAA;;;AAAA;cAKjC,OAAA,SAAgB,YAAmC"}

package/dist/index-DqQ5-VOh.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-DqQ5-VOh.d.cts","names":[],"sources":["../src/apis/spot/src/apis/spot/index.ts"],"mappings":";;;;cAE8C,YAAA;;;AAAA;cAKjC,OAAA,SAAgB,YAAmC"}

package/dist/index-IIzvROYs.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-IIzvROYs.d.ts","names":[],"sources":["../src/apis/market/src/apis/market/index.ts"],"mappings":";;;;cAIwB,cAAA;cAEX,SAAA,SAAkB,cAAuC"}