feat(sdk-core): add bulk TRX resource delegation SDK methods

Adds buildAccountDelegations, sendAccountDelegation, sendAccountDelegations
to the Wallet class and IWallet interface, mirroring the consolidation API.
Adds Express typed route schema and handler for
POST /api/v2/:coin/wallet/:id/delegateResources with TSS/custodial/hot wallet
branching and partial-success (202) response handling.

CHALO-287

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: bhavidhingra

modules/express/src/clientRoutes.ts

@@ -1052,6 +1052,90 @@ export async function handleV2ResourceDelegations(
   });
 }
 
+/**
+ * Shared handler for bulk resource management (delegation / undelegation).
+ * Builds, signs, and sends one on-chain transaction per entry.
+ */
+async function handleV2ResourceManagement(
+  type: 'delegateResource' | 'undelegateResource',
+  req:
+    | ExpressApiRouteRequest<'express.v2.wallet.delegateresources', 'post'>
+    | ExpressApiRouteRequest<'express.v2.wallet.undelegateresources', 'post'>
+) {
+  const bitgo = req.bitgo;
+  const coin = bitgo.coin(req.decoded.coin);
+
+  if (type === 'delegateResource') {
+    const decoded = (req as ExpressApiRouteRequest<'express.v2.wallet.delegateresources', 'post'>).decoded;
+    if (!Array.isArray(decoded.delegations) || decoded.delegations.length === 0) {
+      throw new Error('delegations must be a non-empty array');
+    }
+  } else {
+    const decoded = (req as ExpressApiRouteRequest<'express.v2.wallet.undelegateresources', 'post'>).decoded;
+    if (!Array.isArray(decoded.undelegations) || decoded.undelegations.length === 0) {
+      throw new Error('undelegations must be a non-empty array');
+    }
+  }
+
+  if (!coin.supportsResourceDelegation()) {
+    throw new Error(`${coin.getFamily()} does not support resource delegation`);
+  }
+
+  const wallet = await coin.wallets().get({ id: req.decoded.id });
+
+  let result: any;
+  try {
+    const params = wallet._wallet.multisigType === 'tss' ? createTSSSendParams(req, wallet) : createSendParams(req);
+    result =
+      type === 'delegateResource'
+        ? await wallet.sendResourceDelegations(params)
+        : await wallet.sendResourceUndelegations(params);
+  } catch (err) {
+    // Surface unexpected errors as 400 rather than 500
+    err.status = 400;
+    throw err;
+  }
+
+  // Handle partial success / failure
+  if (result.failure.length > 0) {
+    let msg = '';
+    let status = 202;
+
+    if (result.success.length > 0) {
+      msg = `Transactions failed: ${result.failure.length} and succeeded: ${result.success.length}`;
+    } else {
+      status = 400;
+      msg = `All transactions failed`;
+    }
+
+    throw apiResponse(status, result, msg);
+  }
+
+  return result;
+}
+
+/**
+ * Handle bulk resource delegation (e.g. TRX ENERGY/BANDWIDTH delegation).
+ * Builds, signs, and sends one on-chain delegation transaction per entry in req.body.delegations.
+ * @param req
+ */
+export async function handleV2DelegateResources(
+  req: ExpressApiRouteRequest<'express.v2.wallet.delegateresources', 'post'>
+) {
+  return handleV2ResourceManagement('delegateResource', req);
+}
+
+/**
+ * Handle bulk resource undelegation (e.g. TRX ENERGY/BANDWIDTH undelegation).
+ * Builds, signs, and sends one on-chain undelegation transaction per entry in req.body.undelegations.
+ * @param req
+ */
+export async function handleV2UndelegateResources(
+  req: ExpressApiRouteRequest<'express.v2.wallet.undelegateresources', 'post'>
+) {
+  return handleV2ResourceManagement('undelegateResource', req);
+}
+
 /**
  *  payload meant for prebuildAndSignTransaction() in sdk-core which
  * validates the payload and makes the appropriate request to WP to
@@ -1834,6 +1918,14 @@ export function setupAPIRoutes(app: express.Application, config: Config): void {
     prepareBitGo(config),
     typedPromiseWrapper(handleV2ResourceDelegations),
   ]);
+  router.post('express.v2.wallet.delegateresources', [
+    prepareBitGo(config),
+    typedPromiseWrapper(handleV2DelegateResources),
+  ]);
+  router.post('express.v2.wallet.undelegateresources', [
+    prepareBitGo(config),
+    typedPromiseWrapper(handleV2UndelegateResources),
+  ]);
 
   // Miscellaneous
   router.post('express.canonicaladdress', [prepareBitGo(config), typedPromiseWrapper(handleCanonicalAddress)]);

modules/express/src/typedRoutes/api/index.ts

@@ -58,6 +58,8 @@ import { PostWalletAccelerateTx } from './v2/walletAccelerateTx';
 import { PostIsWalletAddress } from './v2/isWalletAddress';
 import { GetAccountResources } from './v2/accountResources';
 import { GetResourceDelegations } from './v2/resourceDelegations';
+import { PostDelegateResources } from './v2/delegateResources';
+import { PostUndelegateResources } from './v2/undelegateResources';
 
 // Too large types can cause the following error
 //
@@ -192,6 +194,18 @@ export const ExpressV2WalletConsolidateAccountApiSpec = apiSpec({
   },
 });
 
+export const ExpressV2WalletDelegateResourcesApiSpec = apiSpec({
+  'express.v2.wallet.delegateresources': {
+    post: PostDelegateResources,
+  },
+});
+
+export const ExpressV2WalletUndelegateResourcesApiSpec = apiSpec({
+  'express.v2.wallet.undelegateresources': {
+    post: PostUndelegateResources,
+  },
+});
+
 export const ExpressWalletFanoutUnspentsApiSpec = apiSpec({
   'express.v1.wallet.fanoutunspents': {
     put: PutFanoutUnspents,
@@ -397,6 +411,8 @@ export type ExpressApi = typeof ExpressPingApiSpec &
   typeof ExpressV2WalletAccelerateTxApiSpec &
   typeof ExpressV2WalletAccountResourcesApiSpec &
   typeof ExpressV2WalletResourceDelegationsApiSpec &
+  typeof ExpressV2WalletDelegateResourcesApiSpec &
+  typeof ExpressV2WalletUndelegateResourcesApiSpec &
   typeof ExpressWalletManagementApiSpec;
 
 export const ExpressApi: ExpressApi = {
@@ -440,6 +456,8 @@ export const ExpressApi: ExpressApi = {
   ...ExpressV2WalletAccelerateTxApiSpec,
   ...ExpressV2WalletAccountResourcesApiSpec,
   ...ExpressV2WalletResourceDelegationsApiSpec,
+  ...ExpressV2WalletDelegateResourcesApiSpec,
+  ...ExpressV2WalletUndelegateResourcesApiSpec,
   ...ExpressWalletManagementApiSpec,
 };
 

modules/express/src/typedRoutes/api/v2/delegateResources.ts

@@ -0,0 +1,105 @@
+import * as t from 'io-ts';
+import { httpRoute, httpRequest, optional } from '@api-ts/io-ts-http';
+import { BitgoExpressError } from '../../schemas/error';
+
+/**
+ * Path parameters for the delegate resources endpoint
+ */
+export const DelegateResourcesParams = {
+  /** Coin identifier (e.g., 'trx', 'ttrx') */
+  coin: t.string,
+  /** Wallet ID */
+  id: t.string,
+} as const;
+
+/**
+ * A single resource delegation entry
+ */
+export const DelegationEntryCodec = t.type({
+  /** On-chain address that will receive the delegated resources */
+  receiverAddress: t.string,
+  /** Amount of TRX (in SUN) to stake for the delegation */
+  amount: t.string,
+  /** Resource type to delegate (e.g. 'ENERGY', 'BANDWIDTH') */
+  resource: t.string,
+});
+
+/**
+ * Request body for delegating resources to multiple receiver addresses.
+ * Each delegation entry triggers a separate on-chain staking transaction
+ * from the wallet's root address to the receiver address.
+ *
+ * Signing behaviour by wallet type:
+ *   - Hot (non-TSS)   → signed locally with walletPassphrase and submitted
+ *   - Custodial non-TSS → sent for BitGo approval via initiateTransaction
+ *   - TSS (any)       → build response contains txRequestId; signed by TSS service
+ */
+export const DelegateResourcesRequestBody = {
+  /** Delegation entries — one on-chain transaction is built per entry */
+  delegations: t.array(DelegationEntryCodec),
+
+  /** Wallet passphrase to decrypt the user key (hot wallets) */
+  walletPassphrase: optional(t.string),
+  /** Extended private key (alternative to walletPassphrase) */
+  xprv: optional(t.string),
+  /** One-time password for 2FA */
+  otp: optional(t.string),
+
+  /** API version for TSS transaction request response ('lite' or 'full') */
+  apiVersion: optional(t.union([t.literal('lite'), t.literal('full')])),
+} as const;
+
+export const DelegationFailureEntry = t.type({
+  /** Human-readable error message */
+  message: t.string,
+  /** Receiver address that failed, if available */
+  receiverAddress: optional(t.string),
+});
+
+/**
+ * Response for the delegate resources operation.
+ * Returns arrays of successful and failed delegation transactions.
+ */
+export const DelegateResourcesResponse = t.type({
+  /** Successfully sent delegation transactions */
+  success: t.array(t.unknown),
+  /** Errors from failed delegation transactions */
+  failure: t.array(DelegationFailureEntry),
+});
+
+/**
+ * Response for partial success or failure cases (202/400).
+ * Includes both the transaction results and error metadata.
+ */
+export const DelegateResourcesErrorResponse = t.intersection([DelegateResourcesResponse, BitgoExpressError]);
+
+/**
+ * Bulk Resource Delegation
+ *
+ * Delegates resources (ENERGY or BANDWIDTH) from a wallet's root address to one or more
+ * receiver addresses. Each delegation entry produces a separate on-chain staking transaction.
+ * This is the resource-delegation analogue of the consolidateAccount endpoint.
+ *
+ * Supported coins: TRON (trx, ttrx) and any future coins that support resource delegation.
+ *
+ * The API may return partial success (status 202) if some delegations succeed but others fail.
+ *
+ * @operationId express.v2.wallet.delegateresources
+ * @tag express
+ */
+export const PostDelegateResources = httpRoute({
+  path: '/api/v2/{coin}/wallet/{id}/delegateResources',
+  method: 'POST',
+  request: httpRequest({
+    params: DelegateResourcesParams,
+    body: DelegateResourcesRequestBody,
+  }),
+  response: {
+    /** All delegations succeeded */
+    200: DelegateResourcesResponse,
+    /** Partial success — some delegations succeeded, others failed */
+    202: DelegateResourcesErrorResponse,
+    /** All delegations failed */
+    400: DelegateResourcesErrorResponse,
+  },
+});

modules/express/src/typedRoutes/api/v2/undelegateResources.ts

@@ -0,0 +1,75 @@
+import * as t from 'io-ts';
+import { httpRoute, httpRequest, optional } from '@api-ts/io-ts-http';
+import { BitgoExpressError } from '../../schemas/error';
+import { DelegateResourcesParams, DelegationEntryCodec, DelegationFailureEntry } from './delegateResources';
+
+/**
+ * Request body for undelegating resources from multiple receiver addresses.
+ * Each undelegation entry triggers a separate on-chain transaction that reclaims
+ * previously delegated resources back to the wallet's root address.
+ *
+ * Signing behaviour by wallet type:
+ *   - Hot (non-TSS)   → signed locally with walletPassphrase and submitted
+ *   - Custodial non-TSS → sent for BitGo approval via initiateTransaction
+ *   - TSS (any)       → build response contains txRequestId; signed by TSS service
+ */
+export const UndelegateResourcesRequestBody = {
+  /** Undelegation entries — one on-chain transaction is built per entry */
+  undelegations: t.array(DelegationEntryCodec),
+
+  /** Wallet passphrase to decrypt the user key (hot wallets) */
+  walletPassphrase: optional(t.string),
+  /** Extended private key (alternative to walletPassphrase) */
+  xprv: optional(t.string),
+  /** One-time password for 2FA */
+  otp: optional(t.string),
+
+  /** API version for TSS transaction request response ('lite' or 'full') */
+  apiVersion: optional(t.union([t.literal('lite'), t.literal('full')])),
+} as const;
+
+/**
+ * Response for the undelegate resources operation.
+ * Returns arrays of successful and failed undelegation transactions.
+ */
+export const UndelegateResourcesResponse = t.type({
+  /** Successfully sent undelegation transactions */
+  success: t.array(t.unknown),
+  /** Errors from failed undelegation transactions */
+  failure: t.array(DelegationFailureEntry),
+});
+
+/**
+ * Response for partial success or failure cases (202/400).
+ */
+export const UndelegateResourcesErrorResponse = t.intersection([UndelegateResourcesResponse, BitgoExpressError]);
+
+/**
+ * Bulk Resource Undelegation
+ *
+ * Reclaims delegated resources (ENERGY or BANDWIDTH) back to a wallet's root address
+ * from one or more receiver addresses. Each entry produces a separate on-chain transaction.
+ *
+ * Supported coins: TRON (trx, ttrx) and any future coins that support resource delegation.
+ *
+ * The API may return partial success (status 202) if some undelegations succeed but others fail.
+ *
+ * @operationId express.v2.wallet.undelegateresources
+ * @tag express
+ */
+export const PostUndelegateResources = httpRoute({
+  path: '/api/v2/{coin}/wallet/{id}/undelegateResources',
+  method: 'POST',
+  request: httpRequest({
+    params: DelegateResourcesParams,
+    body: UndelegateResourcesRequestBody,
+  }),
+  response: {
+    /** All undelegations succeeded */
+    200: UndelegateResourcesResponse,
+    /** Partial success — some undelegations succeeded, others failed */
+    202: UndelegateResourcesErrorResponse,
+    /** All undelegations failed */
+    400: UndelegateResourcesErrorResponse,
+  },
+});