chain release2.9 compatibility Grace Period and overdue

packages/grid_client/scripts/compare_locked_balance.ts

@@ -71,7 +71,7 @@ async function getUsersWithContracts(grid: GridClient) {
 
   return users;
 }
-
+/** @deprecated */
 async function getContractsLockedAmount(grid: GridClient, contracts: Contract[]) {
   const contractLockDetails = await Promise.all(
     contracts.map(contract => grid.contracts.contractLock({ id: +contract.contractID })),

packages/grid_client/src/clients/tf-grid/contracts.ts

@@ -1,16 +1,26 @@
-import {
+import GridProxyClient, {
+  CertificationType,
   Contract,
+  ContractsQuery,
+  ContractState,
+  ContractType,
+} from "@threefold/gridproxy_client";
+import {
+  BillingInformation,
   ContractLock,
   ContractLockOptions,
+  ContractPaymentState,
   Contracts,
   ExtrinsicResult,
   GetDedicatedNodePriceOptions,
+  NodeContractUsedResources,
   SetDedicatedNodeExtraFeesOptions,
 } from "@threefold/tfchain_client";
+import { GridClientError } from "@threefold/types";
 import { Decimal } from "decimal.js";
 
-import { formatErrorMessage } from "../../helpers";
-import { ContractStates } from "../../modules";
+import { bytesToGB, formatErrorMessage } from "../../helpers";
+import { calculator, ContractStates, currency } from "../../modules";
 import { Graphql } from "../graphql/client";
 
 export type DiscountLevel = "None" | "Default" | "Bronze" | "Silver" | "Gold";
@@ -110,6 +120,21 @@ export interface LockContracts {
   totalAmountLocked: number;
 }
 
+export type OverdueDetails = { [key: number]: number };
+
+export interface ContractsOverdue {
+  nameContracts: OverdueDetails;
+  nodeContracts: OverdueDetails;
+  rentContracts: OverdueDetails;
+  totalOverdueAmount: number;
+}
+export interface CalculateOverdueOptions {
+  contractInfo: Contract;
+  gridProxyClient: GridProxyClient;
+}
+
+const SECONDS_ONE_HOUR = 60 * 60;
+
 class TFContracts extends Contracts {
   async listContractsByTwinId(options: ListContractByTwinIdOptions): Promise<GqlContracts> {
     options.stateList = options.stateList || [ContractStates.Created, ContractStates.GracePeriod];
@@ -301,13 +326,219 @@ class TFContracts extends Contracts {
     });
   }
 
+  /** @deprecated */
   async contractLock(options: ContractLockOptions) {
     const res = await super.contractLock(options);
     const amountLocked = new Decimal(res.amountLocked);
     res.amountLocked = amountLocked.div(10 ** 7).toNumber();
     return res;
   }
 
+  /**
+   * Function to convert USD to TFT
+   * @param {Decimal} USD the amount in USD.
+   * @returns  {Decimal} The amount in TFT.
+   */
+  private async convertToTFT(USD: Decimal) {
+    try {
+      const tftPrice = (await this.client.tftPrice.get()) ?? 0;
+      const tft = new currency(tftPrice).convertUSDtoTFT({ amount: USD.toNumber() });
+      return new Decimal(tft);
+    } catch (error) {
+      throw new GridClientError(`Failed to convert to mTFT due: ${error}`);
+    }
+  }
+  /**
+   * list all contracts, this is not restricted with the items counts
+   * this basically check if the count is larger than the page size, it make another request with the item count as the size pram.
+   * @param {GridProxyClient} proxy will be used to list the contracts
+   * @param {Partial<ContractsQuery>} queries
+   * @returns
+   */
+  async listAllContracts(proxy: GridProxyClient, queries: Partial<ContractsQuery>) {
+    const contracts = await proxy.contracts.list({ ...queries, retCount: true });
+    if (contracts.data.length < contracts.count!) {
+      return (
+        await proxy.contracts.list({
+          ...queries,
+          size: contracts.count!,
+        })
+      ).data;
+    } else return contracts.data;
+  }
+
+  /**
+   * Calculate total IPV4 and total overdraft on all node contracts on rented node.
+   * @description In node contracts on rented nodes we need to have both the overdraft to be added to rent contract overdraft.
+   * please note that the unbilled NU amount is added to the total overdraft exactly as the in the other contract types.
+   * the IPV4 cost to add to the estimated cost of the rent contract.
+   */
+  private async getContractsCostOnRentedNode(nodeId: number, proxy: GridProxyClient) {
+    const contracts = await this.listAllContracts(proxy, {
+      nodeId,
+      state: [ContractState.GracePeriod],
+      numberOfPublicIps: 1,
+    });
+    const publicIpsCount = contracts.reduce((acc, contract) => acc + (contract.details.number_of_public_ips || 0), 0);
+    // will convert  from Unit USD to USD inline;
+    const ipPrice = (await this.client.pricingPolicies.get({ id: 1 })).ipu.value / 10 ** 7;
+    const BillingInformationPromises = contracts.reduce((acc: Promise<BillingInformation>[], contract) => {
+      acc.push(this.client.contracts.getContractBillingInformationByID(contract.contract_id));
+      return acc;
+    }, []);
+    const overDraftPromises = contracts.reduce((acc: Promise<ContractPaymentState>[], contract) => {
+      acc.push(this.client.contracts.getContractPaymentState(contract.contract_id));
+      return acc;
+    }, []);
+
+    const overDraftResult = await Promise.all(overDraftPromises);
+    const billingInfoResult = await Promise.all(BillingInformationPromises);
+
+    const totalOverDraft = overDraftResult.reduce(
+      (acc: Decimal, paymentState) => acc.add(paymentState.additionalOverdraft).add(paymentState.standardOverdraft),
+      new Decimal(0),
+    );
+    const totalNUCost = billingInfoResult.reduce((acc: number, billingInfo) => acc + billingInfo.amountUnbilled, 0);
+    const totalNUCostTFTUnit = await this.convertToTFT(new Decimal(totalNUCost));
+    const totalIPCost = ipPrice * publicIpsCount;
+    return {
+      //return ip cost per month
+      totalIpCost: totalIPCost * 24 * 30,
+      totalOverdraft: totalOverDraft.add(totalNUCostTFTUnit),
+    };
+  }
+
+  /**
+   * This function is for calculating the estimated cost of the contract per month.
+   * @description
+   *  Name contract cost is fixed price for the unique name,
+   * Rent contract cost is the cost of the total node resources,
+   * Node contract have two cases:
+   * 1- on rented contract, this case the cost will be only for the ipv4.
+   * 2- on shared node, this will be the shared price of the used resources
+
+   * @param {Contract} contract 
+   * @param {GridProxyClient} proxy 
+   * @returns the cost of the contract per month in USD
+   */
+  async getContractCost(contract: Contract, proxy: GridProxyClient) {
+    const calc = new calculator(this.client);
+
+    if (contract.type == ContractType.Name) return await calc.namePricing();
+
+    //TODO allow ipv4 to be number
+
+    /** Other contract types need the node information */
+    const nodeDetails = await proxy.nodes.byId(contract.details.nodeId);
+
+    const isCertified = nodeDetails.certificationType == CertificationType.Certified ? true : false;
+    if (contract.type == ContractType.Rent) {
+      const { cru, sru, mru, hru } = nodeDetails.total_resources;
+      const USDCost = (
+        await calc.calculateWithMyBalance({
+          ipv4u: false,
+          certified: isCertified,
+          cru: bytesToGB(cru),
+          mru: bytesToGB(mru),
+          hru: bytesToGB(hru),
+          sru: bytesToGB(sru),
+        })
+      ).dedicatedPrice;
+
+      return USDCost;
+    }
+
+    /** Node Contract */
+
+    /** Node contract on rented node
+     * If the node contract has IPV4 will return the price of the ipv4 per month
+     * If not there is no cost, will return zero
+     */
+
+    if (nodeDetails.rented) {
+      if (!contract.details.number_of_public_ips) return 0;
+
+      const ipPrice = (await this.client.pricingPolicies.get({ id: 1 })).ipu.value / 10 ** 7;
+      return ipPrice * 30 * 24;
+    }
+
+    const usedREsources: NodeContractUsedResources = await this.client.contracts.getNodeContractResources({
+      id: contract.contract_id,
+    });
+    const { cru, sru, mru, hru } = usedREsources.used;
+    const USDCost = (
+      await calc.calculateWithMyBalance({
+        ipv4u: !!contract.details.number_of_public_ips,
+        certified: isCertified,
+        cru: bytesToGB(cru),
+        mru: bytesToGB(mru),
+        hru: bytesToGB(hru),
+        sru: bytesToGB(sru),
+      })
+    ).sharedPrice;
+
+    return await USDCost;
+  }
+
+  /**
+   * Calculates the overdue amount for a contract.
+   *
+   * @description This method calculates the overdue amount, the overdue amount basically is the sum of three parts:
+   * 1- Total over draft: is the sum of additional overdraft and standard overdraft.
+   * 2- Unbilled NU: is the unbilled amount of network usage.
+   * 3- The estimated cost of the contract for the total period: this part is dependant on the contract type and if the contract is on rented node or not.
+   * If the contract is rent contract, will add both of ipv4 cost and the total overdue of all associated contracts.
+   * The total period is the time since the last billing added to Allowance period.
+   * The resulting overdue amount represents the amount that needs to be addressed.
+   *
+   * @param {CalculateOverdueOptions} options - The options containing the contract and gridProxyClient.
+   * @returns {Promise<number>} - The calculated overdue amount in TFT.
+   */
+  async calculateContractOverDue(options: CalculateOverdueOptions) {
+    const contractInfo = options.contractInfo;
+
+    /** Get the Un-billed amount in unit USD  for the network usage */
+    const unbilledNU = (await this.client.contracts.getContractBillingInformationByID(contractInfo.contract_id))
+      .amountUnbilled;
+    const unbilledNUTFTUnit = await this.convertToTFT(new Decimal(unbilledNU));
+
+    const { standardOverdraft, additionalOverdraft, lastUpdatedSeconds } =
+      await this.client.contracts.getContractPaymentState(contractInfo.contract_id);
+
+    /**Calculate the elapsed seconds since last pilling*/
+    const elapsedSeconds = Date.now() / 1000 - lastUpdatedSeconds;
+
+    let contractMonthlyCost = new Decimal(await this.getContractCost(contractInfo, options.gridProxyClient));
+    /**Calculate total over overDraft added to the NU unbilled amount*/
+    let totalOverDraft = new Decimal(standardOverdraft).add(additionalOverdraft);
+
+    if (contractInfo.type == ContractType.Rent) {
+      // get the contracts on the rented node, calculate the nu, then add the ipv4 cost
+      const totalContractsCost = await this.getContractsCostOnRentedNode(
+        contractInfo.details.nodeId,
+        options.gridProxyClient,
+      );
+      totalOverDraft = totalOverDraft.add(totalContractsCost.totalOverdraft);
+      contractMonthlyCost = contractMonthlyCost.add(totalContractsCost.totalIpCost);
+    }
+
+    // time since the last billing with allowance time of **one hour**
+    const totalPeriodTime = elapsedSeconds + SECONDS_ONE_HOUR;
+
+    //USD
+    const contractCostPerSecond = contractMonthlyCost.div(30 * 24 * SECONDS_ONE_HOUR);
+    const contractCostTFT = await this.convertToTFT(contractCostPerSecond);
+
+    // cost of the current billing period with the mentioned allowance time
+    const totalPeriodCost = contractCostTFT.times(totalPeriodTime);
+    const overdue = totalOverDraft.add(unbilledNUTFTUnit);
+
+    //convert to TFT
+    const OverdueTFT = overdue.div(10 ** 7);
+
+    return OverdueTFT.add(totalPeriodCost);
+  }
+
   /**
    * WARNING: Please be careful when executing this method, it will delete all your contracts.
    * @param  {CancelMyContractOptions} options
@@ -335,28 +566,60 @@ class TFContracts extends Contracts {
     await this.client.applyAllExtrinsics(extrinsics);
     return ids;
   }
-
-  async batchUnlockContracts(ids: number[]) {
-    const billableContractsIDs: number[] = [];
-    for (const id of ids) {
-      if ((await this.contractLock({ id })).amountLocked > 0) billableContractsIDs.push(id);
+  /**
+   * Async function that request to resume the passed contracts.
+   *
+   * @description
+   * This function create array of `ExtrinsicResult<number>` to use in `applyAllExtrinsics`.
+   * It's not guaranteed that the contracts will be resumed; It just trigger billing request; if it pass the contract will be resumed.
+   * the function will ignore all contracts that do not have overdue, also if there is sum rent contracts, its associated node contracts that have ipv4 will be added.
+   * @param {Contract[]} contracts contracts to be
+   * @param {GridProxyClient} proxy
+   * @returns {number[]} contract ids that have been requested to resume
+   */
+  async batchUnlockContracts(contracts: Contract[], proxy: GridProxyClient) {
+    const billableContractsIDs: Set<number> = new Set();
+    for (const contract of contracts) {
+      const contractOverdue = (
+        await this.calculateContractOverDue({ contractInfo: contract, gridProxyClient: proxy })
+      ).toNumber();
+      if (contractOverdue > 0) {
+        billableContractsIDs.add(contract.contract_id);
+
+        if (contract.type == ContractType.Rent) {
+          /** add associated node contracts on the rented node `with public ip` to the contracts to bill */
+          const nodeContracts = await this.listAllContracts(proxy, {
+            numberOfPublicIps: 1,
+            state: [ContractState.GracePeriod],
+            nodeId: contract.details.nodeId,
+          });
+          nodeContracts.forEach(contract => billableContractsIDs.add(contract.contract_id));
+        }
+      }
     }
     const extrinsics: ExtrinsicResult<number>[] = [];
-    for (const id of billableContractsIDs) {
+    for (const id of Array.from(billableContractsIDs)) {
       extrinsics.push(await this.unlock(id));
     }
     return this.client.applyAllExtrinsics(extrinsics);
   }
 
-  async unlockMyContracts(graphqlURL: string) {
-    const contracts = await this.listMyContracts({
-      stateList: [ContractStates.GracePeriod],
-      graphqlURL,
+  /**
+   * Request to resume all grace period contracts associated with the current twinId
+   * @description
+   * This function lists all grace period contracts, then call {@link batchUnlockContracts}.
+   * @param {String} gridProxyUrl
+   * @returns contract ids that have been requested to resume.
+   */
+  async unlockMyContracts(gridProxyUrl: string) {
+    const proxy = new GridProxyClient(gridProxyUrl);
+    const contracts = await this.listAllContracts(proxy, {
+      state: [ContractState.GracePeriod],
+      twinId: await this.client.twins.getMyTwinId(),
     });
-    const ids: number[] = [...contracts.nameContracts, ...contracts.nodeContracts, ...contracts.rentContracts].map(
-      contract => parseInt(contract.contractID),
-    );
-    return await this.batchUnlockContracts(ids);
+
+    if (contracts.length == 0) return [];
+    return await this.batchUnlockContracts(contracts as Contract[], proxy);
   }
 
   async getDedicatedNodeExtraFee(options: GetDedicatedNodePriceOptions): Promise<number> {

packages/grid_client/src/helpers/utils.ts

@@ -81,6 +81,14 @@ function convertObjectToQueryString(obj: Record<string, any>): string {
 
   return queryString;
 }
+/**
+ * Function to convert from bytes to Gigabytes
+ * @param {Number} bytes
+ * @returns {Number}
+ */
+function bytesToGB(bytes: number) {
+  return bytes / Math.pow(1024, 3);
+}
 
 export {
   generateString,
@@ -95,4 +103,5 @@ export {
   generateRandomHexSeed,
   zeroPadding,
   convertObjectToQueryString,
+  bytesToGB,
 };

packages/grid_client/src/modules/calculator.ts

@@ -122,6 +122,22 @@ class Calculator {
     return pricing;
   }
 
+  /**
+   * Calculates the cost of a unique name per month.
+   *
+   * This function retrieves the price per hour for a unique name, and calculates the total cost in mUSD.
+   *
+   *
+   * @returns {Promise<number>} - The price in mUSD for the unique name usage per month.
+   */
+  @validateInput
+  async namePricing() {
+    const uniqueNamePricePerHour = (await this.getPrices()).uniqueName.value;
+    const priceInUSD = uniqueNamePricePerHour / 10 ** 7;
+    // return cost per month
+    return priceInUSD * 24 * 30;
+  }
+
   /**
    * Asynchronously retrieves the TFT price from the TFChain.
    *