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

@@ -1050,6 +1050,58 @@ export async function handleV2ResourceDelegations(
   });
 }
 
+/**
+ * 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'>
+) {
+  const bitgo = req.bitgo;
+  const coin = bitgo.coin(req.decoded.coin);
+
+  if (!Array.isArray(req.decoded.delegations) || req.decoded.delegations.length === 0) {
+    throw new Error('delegations 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 {
+    if (coin.supportsTss()) {
+      result = await wallet.sendResourceDelegations(createTSSSendParams(req, wallet));
+    } else {
+      result = await wallet.sendResourceDelegations(createSendParams(req));
+    }
+  } catch (err) {
+    // Surface unexpected errors as 400 rather than 500
+    (err as any).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;
+}
+
 /**
  *  payload meant for prebuildAndSignTransaction() in sdk-core which
  * validates the payload and makes the appropriate request to WP to
@@ -1829,6 +1881,10 @@ export function setupAPIRoutes(app: express.Application, config: Config): void {
     prepareBitGo(config),
     typedPromiseWrapper(handleV2ResourceDelegations),
   ]);
+  router.post('express.v2.wallet.delegateresources', [
+    prepareBitGo(config),
+    typedPromiseWrapper(handleV2DelegateResources),
+  ]);
 
   // Miscellaneous
   router.post('express.canonicaladdress', [prepareBitGo(config), typedPromiseWrapper(handleCanonicalAddress)]);

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

@@ -55,6 +55,7 @@ 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';
 
 // Too large types can cause the following error
 //
@@ -180,6 +181,12 @@ export const ExpressV2WalletConsolidateAccountApiSpec = apiSpec({
   },
 });
 
+export const ExpressV2WalletDelegateResourcesApiSpec = apiSpec({
+  'express.v2.wallet.delegateresources': {
+    post: PostDelegateResources,
+  },
+});
+
 export const ExpressWalletFanoutUnspentsApiSpec = apiSpec({
   'express.v1.wallet.fanoutunspents': {
     put: PutFanoutUnspents,
@@ -385,6 +392,7 @@ export type ExpressApi = typeof ExpressPingApiSpec &
   typeof ExpressV2WalletAccelerateTxApiSpec &
   typeof ExpressV2WalletAccountResourcesApiSpec &
   typeof ExpressV2WalletResourceDelegationsApiSpec &
+  typeof ExpressV2WalletDelegateResourcesApiSpec &
   typeof ExpressWalletManagementApiSpec;
 
 export const ExpressApi: ExpressApi = {
@@ -428,6 +436,7 @@ export const ExpressApi: ExpressApi = {
   ...ExpressV2WalletAccelerateTxApiSpec,
   ...ExpressV2WalletAccountResourcesApiSpec,
   ...ExpressV2WalletResourceDelegationsApiSpec,
+  ...ExpressV2WalletDelegateResourcesApiSpec,
   ...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: t.union([t.string, t.undefined]),
+});
+
+/**
+ * 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/sdk-coin-trx/src/trx.ts

@@ -225,6 +225,11 @@ export class Trx extends BaseCoin {
     return true;
   }
 
+  /** @inheritDoc */
+  supportsResourceDelegation(): boolean {
+    return true;
+  }
+
   /**
    * Checks if this is a valid base58
    * @param address

modules/sdk-core/src/bitgo/baseCoin/baseCoin.ts

@@ -173,6 +173,10 @@ export abstract class BaseCoin implements IBaseCoin {
     return false;
   }
 
+  supportsResourceDelegation(): boolean {
+    return false;
+  }
+
   /**
    * Gets config for how token enablements work for this coin
    * @returns

modules/sdk-core/src/bitgo/baseCoin/iBaseCoin.ts

@@ -575,6 +575,7 @@ export interface IBaseCoin {
   sweepWithSendMany(): boolean;
   transactionDataAllowed(): boolean;
   allowsAccountConsolidations(): boolean;
+  supportsResourceDelegation(): boolean;
   getTokenEnablementConfig(): TokenEnablementConfig;
   supportsTss(): boolean;
   supportsMultisig(): boolean;

modules/sdk-core/src/bitgo/wallet/iWallet.ts

@@ -63,6 +63,19 @@ export interface BuildConsolidationTransactionOptions extends PrebuildTransactio
   consolidateAddresses?: string[];
 }
 
+export interface ResourceDelegationEntry {
+  receiverAddress: string;
+  amount: string;
+  /** Resource type to delegate (e.g. 'ENERGY', 'BANDWIDTH'). */
+  resource: string;
+}
+
+export interface BuildResourceDelegationTransactionOptions
+  extends PrebuildTransactionOptions,
+    WalletSignTransactionOptions {
+  delegations: ResourceDelegationEntry[];
+}
+
 export interface BuildTokenEnablementOptions extends PrebuildTransactionOptions {
   enableTokens: TokenEnablement[];
 }
@@ -251,6 +264,7 @@ export interface PrebuildTransactionResult extends TransactionPrebuild {
   pendingApprovalId?: string;
   reqId?: IRequestTracer;
   payload?: string;
+  stakingParams?: unknown;
 }
 
 export interface CustomSigningFunction {
@@ -1096,6 +1110,12 @@ export interface IWallet {
   buildAccountConsolidations(params?: BuildConsolidationTransactionOptions): Promise<PrebuildTransactionResult[]>;
   sendAccountConsolidation(params?: PrebuildAndSignTransactionOptions): Promise<any>;
   sendAccountConsolidations(params?: BuildConsolidationTransactionOptions): Promise<any>;
+  buildResourceDelegations(params: BuildResourceDelegationTransactionOptions): Promise<PrebuildTransactionResult[]>;
+  sendResourceDelegation(params: PrebuildAndSignTransactionOptions): Promise<any>;
+  sendResourceDelegations(params: BuildResourceDelegationTransactionOptions): Promise<{
+    success: any[];
+    failure: { message: string; receiverAddress?: string }[];
+  }>;
   buildTokenEnablements(params?: BuildTokenEnablementOptions): Promise<PrebuildTransactionResult[]>;
   sendTokenEnablement(params?: PrebuildAndSignTransactionOptions): Promise<any>;
   sendTokenEnablements(params?: BuildTokenEnablementOptions): Promise<any>;