feat: Adding private wallet functionality with the integration tests

.circleci/config.yml

@@ -266,6 +266,21 @@ jobs:
       - store_test_results:
           path: packages/integration-test/reports/
 
+  test-monthly:
+    docker:
+      - *node_image
+    working_directory: *working_directory
+    resource_class: large
+    steps:
+      - attach_workspace:
+          at: *working_directory
+      - run:
+          name: 'Test payment-processor (hinkal)'
+          no_output_timeout: 30m
+          command: 'yarn workspace @requestnetwork/payment-processor run test:hinkal'
+      - store_test_results:
+          path: packages/payment-processor/reports/
+
   # Release a next version package everytime we merge to master
   next-release:
     docker:
@@ -349,3 +364,19 @@ workflows:
       - test-nightly:
           requires:
             - build
+
+  monthly:
+    triggers:
+      - schedule:
+          # This is a cron job for "every 1st day of the month at 22 hours"
+          cron: '0 22 1 * *'
+          filters:
+            branches:
+              only:
+                - master
+
+    jobs:
+      - build
+      - test-monthly:
+          requires:
+            - build

packages/payment-processor/package.json

@@ -35,10 +35,12 @@
     "lint": "eslint . --fix",
     "lint:check": "eslint .",
     "prepare": "yarn run build",
-    "test": "jest --runInBand",
+    "test": "jest --testPathIgnorePatterns test/payment/erc-20-private-payment-hinkal.test.ts --runInBand",
+    "test:hinkal": "jest test/payment/erc-20-private-payment-hinkal.test.ts --runInBand",
     "test:watch": "yarn test --watch"
   },
   "dependencies": {
+    "@hinkal/common": "0.2.7",
     "@openzeppelin/contracts": "4.9.6",
     "@requestnetwork/currency": "0.23.0",
     "@requestnetwork/payment-detection": "0.49.0",

packages/payment-processor/src/index.ts

@@ -3,6 +3,7 @@ export * from './payment/btc-address-based';
 export * from './payment/erc20';
 export * from './payment/erc20-proxy';
 export * from './payment/erc20-fee-proxy';
+export * from './payment/erc-20-private-payment-hinkal';
 export * from './payment/erc777-stream';
 export * from './payment/erc777-utils';
 export * from './payment/eth-input-data';

packages/payment-processor/src/payment/erc-20-private-payment-hinkal.ts

@@ -0,0 +1,215 @@
+import { Contract, ContractTransaction, Signer, BigNumberish, providers, BigNumber } from 'ethers';
+import { erc20FeeProxyArtifact } from '@requestnetwork/smart-contracts';
+import {
+  ERC20FeeProxy__factory,
+  ERC20Proxy__factory,
+  ERC20__factory,
+} from '@requestnetwork/smart-contracts/types';
+import { ClientTypes, ExtensionTypes } from '@requestnetwork/types';
+import { Erc20PaymentNetwork, getPaymentNetworkExtension } from '@requestnetwork/payment-detection';
+import { EvmChains } from '@requestnetwork/currency';
+import {
+  getAmountToPay,
+  getProvider,
+  getRequestPaymentValues,
+  getSigner,
+  validateRequest,
+  validateErc20FeeProxyRequest,
+  getProxyAddress,
+} from './utils';
+import { IPreparedPrivateTransaction } from './prepared-transaction';
+
+import { emporiumOp, IHinkal, RelayerTransaction } from '@hinkal/common';
+import { prepareEthersHinkal } from '@hinkal/common/providers/prepareEthersHinkal';
+
+/**
+ * This is a globally accessible state variable exported for use in other parts of the application or tests.
+ */
+export const hinkalStore: Record<string, IHinkal> = {};
+
+/**
+ * Adds an IHinkal instance to the Hinkal store for a given signer.
+ *
+ * This function checks if an IHinkal instance already exists for the provided signer’s address in the `hinkalStore`.
+ * If it does not exist, it initializes the instance using `prepareEthersHinkal` and stores it. The existing or newly
+ * created instance is then returned.
+ *
+ * @param signer - The signer for which the IHinkal instance should be added or retrieved.
+ */
+export async function addToHinkalStore(signer: Signer): Promise<IHinkal> {
+  const address = await signer.getAddress();
+  if (!hinkalStore[address]) {
+    hinkalStore[address] = await prepareEthersHinkal(signer);
+  }
+  return hinkalStore[address];
+}
+
+/**
+ * Sends ERC20 tokens into a Hinkal shielded address.
+ *
+ * @param signerOrProvider the Web3 provider, or signer.
+ * @param tokenAddress - The address of the ERC20 token being sent.
+ * @param amount - The amount of tokens to send.
+ * @param recipientInfo - (Optional) The shielded address of the recipient. If provided, the tokens will be deposited into the recipient's shielded balance. If not provided, the deposit will increase the sender's shielded balance.
+ *
+ * @returns A promise that resolves to a `ContractTransaction`.
+ */
+export async function sendToHinkalShieldedAddressFromPublic(
+  signerOrProvider: providers.Provider | Signer = getProvider(),
+  tokenAddress: string,
+  amount: BigNumberish,
+  recipientInfo?: string,
+): Promise<ContractTransaction> {
+  const signer = getSigner(signerOrProvider);
+  const hinkalObject = await addToHinkalStore(signer);
+
+  const amountToPay = BigNumber.from(amount).toBigInt();
+  if (recipientInfo) {
+    return hinkalObject.depositForOther([tokenAddress], [amountToPay], recipientInfo);
+  } else {
+    return hinkalObject.deposit([tokenAddress], [amountToPay]);
+  }
+}
+
+/**
+ * Processes a transaction to pay privately a request through the ERC20 fee proxy contract.
+ * @param request request to pay.
+ * @param signerOrProvider the Web3 provider, or signer. Defaults to window.ethereum.
+ * @param amount optionally, the amount to pay. Defaults to remaining amount of the request.
+ */
+export async function payErc20ProxyRequestFromHinkalShieldedAddress(
+  request: ClientTypes.IRequestData,
+  signerOrProvider: providers.Provider | Signer = getProvider(),
+  amount?: BigNumberish,
+): Promise<RelayerTransaction> {
+  const signer = getSigner(signerOrProvider);
+  const hinkalObject = await addToHinkalStore(signer);
+
+  const { amountToPay, tokenAddress, ops } = prepareErc20ProxyPaymentFromHinkalShieldedAddress(
+    request,
+    amount,
+  );
+
+  return hinkalObject.actionPrivateWallet(
+    [tokenAddress],
+    [-amountToPay],
+    [false],
+    ops,
+  ) as Promise<RelayerTransaction>;
+}
+
+/**
+ * Processes a transaction to pay privately a request through the ERC20 fee proxy.
+ * @param request request to pay.
+ * @param signerOrProvider the Web3 provider, or signer. Defaults to window.ethereum.
+ * @param amount optionally, the amount to pay. Defaults to remaining amount of the request.
+ * @param feeAmount optionally, the fee amount to pay. Defaults to the fee amount of the request.
+ */
+export async function payErc20FeeProxyRequestFromHinkalShieldedAddress(
+  request: ClientTypes.IRequestData,
+  signerOrProvider: providers.Provider | Signer = getProvider(),
+  amount?: BigNumberish,
+  feeAmount?: BigNumberish,
+): Promise<RelayerTransaction> {
+  const signer = getSigner(signerOrProvider);
+  const hinkalObject = await addToHinkalStore(signer);
+
+  const { amountToPay, tokenAddress, ops } = prepareErc20FeeProxyPaymentFromHinkalShieldedAddress(
+    request,
+    amount,
+    feeAmount,
+  );
+
+  return hinkalObject.actionPrivateWallet(
+    [tokenAddress],
+    [-amountToPay],
+    [false],
+    ops,
+  ) as Promise<RelayerTransaction>;
+}
+
+/**
+ * Prepare the transaction to privately pay a request through the ERC20 proxy contract, can be used with a Multisig contract.
+ * @param request request to pay
+ * @param amount optionally, the amount to pay. Defaults to remaining amount of the request.
+ */
+export function prepareErc20ProxyPaymentFromHinkalShieldedAddress(
+  request: ClientTypes.IRequestData,
+  amount?: BigNumberish,
+): IPreparedPrivateTransaction {
+  validateRequest(request, ExtensionTypes.PAYMENT_NETWORK_ID.ERC20_PROXY_CONTRACT);
+
+  const { value: tokenAddress } = request.currencyInfo;
+  const proxyAddress = getProxyAddress(
+    request,
+    Erc20PaymentNetwork.ERC20ProxyPaymentDetector.getDeploymentInformation,
+  );
+
+  const tokenContract = new Contract(tokenAddress, ERC20__factory.createInterface());
+  const proxyContract = new Contract(proxyAddress, ERC20Proxy__factory.createInterface());
+
+  const { paymentReference, paymentAddress } = getRequestPaymentValues(request);
+  const amountToPay = getAmountToPay(request, amount);
+
+  const ops = [
+    emporiumOp(tokenContract, 'approve', [proxyContract.address, amountToPay]),
+    emporiumOp(proxyContract, 'transferFromWithReference', [
+      tokenAddress,
+      paymentAddress,
+      amountToPay,
+      `0x${paymentReference}`,
+    ]),
+  ];
+
+  return {
+    amountToPay: amountToPay.toBigInt(),
+    tokenAddress,
+    ops,
+  };
+}
+
+/**
+ * Prepare the transaction to privately pay a request through the ERC20 fee proxy contract, can be used with a Multisig contract.
+ * @param request request to pay
+ * @param amount optionally, the amount to pay. Defaults to remaining amount of the request.
+ * @param feeAmountOverride optionally, the fee amount to pay. Defaults to the fee amount of the request.
+ */
+export function prepareErc20FeeProxyPaymentFromHinkalShieldedAddress(
+  request: ClientTypes.IRequestData,
+  amount?: BigNumberish,
+  feeAmountOverride?: BigNumberish,
+): IPreparedPrivateTransaction {
+  validateErc20FeeProxyRequest(request, amount, feeAmountOverride);
+
+  const { value: tokenAddress, network } = request.currencyInfo;
+  EvmChains.assertChainSupported(network!);
+  const pn = getPaymentNetworkExtension(request);
+  const proxyAddress = erc20FeeProxyArtifact.getAddress(network, pn?.version);
+
+  const tokenContract = new Contract(tokenAddress, ERC20__factory.createInterface());
+  const proxyContract = new Contract(proxyAddress, ERC20FeeProxy__factory.createInterface());
+
+  const { paymentReference, paymentAddress, feeAddress, feeAmount } =
+    getRequestPaymentValues(request);
+  const amountToPay = getAmountToPay(request, amount);
+  const feeToPay = String(feeAmountOverride || feeAmount || 0);
+  const totalAmount = amountToPay.add(BigNumber.from(feeToPay));
+
+  const ops = [
+    emporiumOp(tokenContract, 'approve', [proxyContract.address, totalAmount]),
+    emporiumOp(proxyContract, 'transferFromWithReferenceAndFee', [
+      tokenAddress,
+      paymentAddress,
+      amountToPay,
+      `0x${paymentReference}`,
+      feeToPay,
+      feeAddress,
+    ]),
+  ];
+
+  return {
+    amountToPay: totalAmount.toBigInt(),
+    tokenAddress,
+    ops,
+  };
+}

packages/payment-processor/src/payment/prepared-transaction.ts

@@ -5,3 +5,13 @@ export interface IPreparedTransaction {
   data: string;
   to: string;
 }
+
+/** Interface for preparing private transactions using Hinkal middleware */
+export interface IPreparedPrivateTransaction {
+  /** Amount to pay in base units (e.g., wei for ETH, smallest decimal unit for ERC20 tokens based on their decimals()) */
+  amountToPay: bigint;
+  /** ERC20 token contract address */
+  tokenAddress: string;
+  /** list of operations encoded as HexStrings */
+  ops: string[];
+}