add corresponding getEffectiveAuditorHint function

Author: alinush

confidential-assets/src/api/confidentialAsset.ts

@@ -18,6 +18,7 @@ import {
   ConfidentialAssetTransactionBuilder,
   ConfidentialBalance,
   getBalance,
+  getEffectiveAuditorHint,
   getEncryptionKey,
   hasUserRegistered,
   isBalanceNormalized,
@@ -478,6 +479,27 @@ export class ConfidentialAsset {
     });
   }
 
+  /**
+   * Get the effective auditor hint for a user's confidential store.
+   * Indicates which auditor (global vs asset-specific) and epoch the balance ciphertext is encrypted for.
+   *
+   * @param args.accountAddress - The account address to query
+   * @param args.tokenAddress - The token address of the asset
+   * @param args.options - Optional ledger version for the view call
+   * @returns The auditor hint, or undefined if no auditor hint is set
+   */
+  async getEffectiveAuditorHint(args: {
+    accountAddress: AccountAddressInput;
+    tokenAddress: AccountAddressInput;
+    options?: LedgerVersionArg;
+  }): Promise<{ isGlobal: boolean; epoch: bigint } | undefined> {
+    return getEffectiveAuditorHint({
+      client: this.client(),
+      moduleAddress: this.moduleAddress(),
+      ...args,
+    });
+  }
+
   /**
    * Normalize a user's balance.
    *

confidential-assets/src/internal/viewFunctions.ts

@@ -257,6 +257,44 @@ export async function hasUserRegistered(args: ViewFunctionParams): Promise<boole
  * @returns The encryption key as a TwistedEd25519PublicKey
  * @throws {Error} If the encryption key cannot be retrieved
  */
+/**
+ * Response type for the effective auditor hint view function.
+ * Mirrors Move's `Option<EffectiveAuditorHint::V1 { is_global: bool, epoch: u64 }>`.
+ */
+export type EffectiveAuditorHintResponse = {
+  vec: { is_global: boolean; epoch: string }[];
+};
+
+/**
+ * Get the effective auditor hint for a user's confidential store.
+ * Indicates which auditor (global vs asset-specific) and epoch the balance ciphertext is encrypted for.
+ *
+ * @returns The auditor hint, or undefined if no auditor hint is set (e.g., balance is zero or no auditor was active).
+ */
+export async function getEffectiveAuditorHint(
+  args: ViewFunctionParams,
+): Promise<{ isGlobal: boolean; epoch: bigint } | undefined> {
+  const {
+    client,
+    accountAddress,
+    tokenAddress,
+    options,
+    moduleAddress = DEFAULT_CONFIDENTIAL_COIN_MODULE_ADDRESS,
+  } = args;
+  const [hint] = await client.view<[EffectiveAuditorHintResponse]>({
+    options,
+    payload: {
+      function: `${moduleAddress}::${MODULE_NAME}::get_effective_auditor_hint`,
+      typeArguments: [],
+      functionArguments: [accountAddress, tokenAddress],
+    },
+  });
+  if (hint.vec.length === 0) {
+    return undefined;
+  }
+  return { isGlobal: hint.vec[0].is_global, epoch: BigInt(hint.vec[0].epoch) };
+}
+
 export async function getEncryptionKey(
   args: ViewFunctionParams & {
     useCachedValue?: boolean;

confidential-assets/tests/e2e/confidentialAsset.test.ts

@@ -436,7 +436,7 @@ describe("Confidential Asset Sender API", () => {
     longTestTimeout,
   );
 
-  // Effective-auditor e2e tests require calling set_auditor_for_asset_type as the @aptos_framework (0x1)
+  // Effective-auditor e2e tests require calling set_asset_specific_auditor as the @aptos_framework (0x1)
   // signer, which we can't do on localnet without the framework private key. The effective-auditor
   // sigma protocol is fully covered by Move unit tests (all 6 configs) and SDK unit tests.
   // TODO: once an `aptos` CLI profile for 0x1 is available on localnet, add e2e tests for: