ARC-59: ASA Inbox Router

/* eslint-disable max-classes-per-file */

// eslint-disable-next-line import/no-unresolved, import/extensions
import { Contract } from "@algorandfoundation/tealscript";

type SendAssetInfo = {
  /**
   * The total number of inner transactions required to send the asset through the router.
   * This should be used to add extra fees to the app call
   */
  itxns: uint64;
  /** The total MBR the router needs to send the asset through the router. */
  mbr: uint64;
  /** Whether the router is already opted in to the asset or not */
  routerOptedIn: boolean;
  /** Whether the receiver is already directly opted in to the asset or not */
  receiverOptedIn: boolean;
  /** The amount of ALGO the receiver would currently need to claim the asset */
  receiverAlgoNeededForClaim: uint64;
};

class ControlledAddress extends Contract {
  @allow.create("DeleteApplication")
  new(): Address {
    sendPayment({
      rekeyTo: this.txn.sender,
    });

    return this.app.address;
  }
}

export class ARC59 extends Contract {
  inboxes = BoxMap<Address, Address>();

  /**
   * Deploy ARC59 contract
   *
   */
  createApplication(): void {}

  /**
   * Opt the ARC59 router into the ASA. This is required before this app can be used to send the ASA to anyone.
   *
   * @param asa The ASA to opt into
   */
  arc59_optRouterIn(asa: AssetID): void {
    sendAssetTransfer({
      assetReceiver: this.app.address,
      assetAmount: 0,
      xferAsset: asa,
    });
  }

  /**
   * Gets the existing inbox for the receiver or creates a new one if it does not exist
   *
   * @param receiver The address to get or create the inbox for
   * @returns The inbox address
   */
  arc59_getOrCreateInbox(receiver: Address): Address {
    if (this.inboxes(receiver).exists) return this.inboxes(receiver).value;

    const inbox = sendMethodCall<typeof ControlledAddress.prototype.new>({
      onCompletion: OnCompletion.DeleteApplication,
      approvalProgram: ControlledAddress.approvalProgram(),
      clearStateProgram: ControlledAddress.clearProgram(),
    });

    this.inboxes(receiver).value = inbox;

    return inbox;
  }

  /**
   *
   * @param receiver The address to send the asset to
   * @param asset The asset to send
   *
   * @returns Returns the following information for sending an asset:
   * The number of itxns required, the MBR required, whether the router is opted in, whether the receiver is opted in,
   * and how much ALGO the receiver would need to claim the asset
   */
  arc59_getSendAssetInfo(receiver: Address, asset: AssetID): SendAssetInfo {
    const routerOptedIn = this.app.address.isOptedInToAsset(asset);
    const receiverOptedIn = receiver.isOptedInToAsset(asset);
    const info: SendAssetInfo = {
      itxns: 1,
      mbr: 0,
      routerOptedIn: routerOptedIn,
      receiverOptedIn: receiverOptedIn,
      receiverAlgoNeededForClaim: 0,
    };

    if (receiverOptedIn) return info;

    const algoNeededToClaim =
      receiver.minBalance + globals.assetOptInMinBalance + globals.minTxnFee;

    // Determine how much ALGO the receiver needs to claim the asset
    if (receiver.balance < algoNeededToClaim) {
      info.receiverAlgoNeededForClaim += algoNeededToClaim - receiver.balance;
    }

    // Add mbr and transaction for opting the router in
    if (!routerOptedIn) {
      info.mbr += globals.assetOptInMinBalance;
      info.itxns += 1;
    }

    if (!this.inboxes(receiver).exists) {
      // Two itxns to create inbox (create + rekey)
      // One itxns to send MBR
      // One itxn to opt in
      info.itxns += 4;

      // Calculate the MBR for the inbox box
      const preMBR = globals.currentApplicationAddress.minBalance;
      this.inboxes(receiver).value = globals.zeroAddress;
      const boxMbrDelta = globals.currentApplicationAddress.minBalance - preMBR;
      this.inboxes(receiver).delete();

      // MBR = MBR for the box + min balance for the inbox + ASA MBR
      info.mbr +=
        boxMbrDelta + globals.minBalance + globals.assetOptInMinBalance;

      return info;
    }

    const inbox = this.inboxes(receiver).value;

    if (!inbox.isOptedInToAsset(asset)) {
      // One itxn to opt in
      info.itxns += 1;

      if (!(inbox.balance >= inbox.minBalance + globals.assetOptInMinBalance)) {
        // One itxn to send MBR
        info.itxns += 1;

        // MBR = ASA MBR
        info.mbr += globals.assetOptInMinBalance;
      }
    }

    return info;
  }

  /**
   * Send an asset to the receiver
   *
   * @param receiver The address to send the asset to
   * @param axfer The asset transfer to this app
   * @param additionalReceiverFunds The amount of ALGO to send to the receiver/inbox in addition to the MBR
   *
   * @returns The address that the asset was sent to (either the receiver or their inbox)
   */
  arc59_sendAsset(
    axfer: AssetTransferTxn,
    receiver: Address,
    additionalReceiverFunds: uint64
  ): Address {
    verifyAssetTransferTxn(axfer, {
      assetReceiver: this.app.address,
    });

    // If the receiver is opted in, send directly to their account
    if (receiver.isOptedInToAsset(axfer.xferAsset)) {
      sendAssetTransfer({
        assetReceiver: receiver,
        assetAmount: axfer.assetAmount,
        xferAsset: axfer.xferAsset,
      });

      if (additionalReceiverFunds !== 0) {
        sendPayment({
          receiver: receiver,
          amount: additionalReceiverFunds,
        });
      }

      return receiver;
    }

    const inboxExisted = this.inboxes(receiver).exists;
    const inbox = this.arc59_getOrCreateInbox(receiver);

    if (additionalReceiverFunds !== 0) {
      sendPayment({
        receiver: inbox,
        amount: additionalReceiverFunds,
      });
    }

    if (!inbox.isOptedInToAsset(axfer.xferAsset)) {
      let inboxMbrDelta = globals.assetOptInMinBalance;
      if (!inboxExisted) inboxMbrDelta += globals.minBalance;

      // Ensure the inbox has enough balance to opt in
      if (inbox.balance < inbox.minBalance + inboxMbrDelta) {
        sendPayment({
          receiver: inbox,
          amount: inboxMbrDelta,
        });
      }

      // Opt the inbox in
      sendAssetTransfer({
        sender: inbox,
        assetReceiver: inbox,
        assetAmount: 0,
        xferAsset: axfer.xferAsset,
      });
    }

    // Transfer the asset to the inbox
    sendAssetTransfer({
      assetReceiver: inbox,
      assetAmount: axfer.assetAmount,
      xferAsset: axfer.xferAsset,
    });

    return inbox;
  }

  /**
   * Claim an ASA from the inbox
   *
   * @param asa The ASA to claim
   */
  arc59_claim(asa: AssetID): void {
    const inbox = this.inboxes(this.txn.sender).value;

    sendAssetTransfer({
      sender: inbox,
      assetReceiver: this.txn.sender,
      assetAmount: inbox.assetBalance(asa),
      xferAsset: asa,
      assetCloseTo: this.txn.sender,
    });

    sendPayment({
      sender: inbox,
      receiver: this.txn.sender,
      amount: inbox.balance - inbox.minBalance,
    });
  }

  /**
   * Reject the ASA by closing it out to the ASA creator. Always sends two inner transactions.
   * All non-MBR ALGO balance in the inbox will be sent to the caller.
   *
   * @param asa The ASA to reject
   */
  arc59_reject(asa: AssetID) {
    const inbox = this.inboxes(this.txn.sender).value;

    sendAssetTransfer({
      sender: inbox,
      assetReceiver: asa.creator,
      assetAmount: inbox.assetBalance(asa),
      xferAsset: asa,
      assetCloseTo: asa.creator,
    });

    sendPayment({
      sender: inbox,
      receiver: this.txn.sender,
      amount: inbox.balance - inbox.minBalance,
    });
  }

  /**
   * Get the inbox address for the given receiver
   *
   * @param receiver The receiver to get the inbox for
   *
   * @returns Zero address if the receiver does not yet have an inbox, otherwise the inbox address
   */
  arc59_getInbox(receiver: Address): Address {
    return this.inboxes(receiver).exists
      ? this.inboxes(receiver).value
      : globals.zeroAddress;
  }

  /** Claim any extra algo from the inbox */
  arc59_claimAlgo() {
    const inbox = this.inboxes(this.txn.sender).value;

    assert(inbox.balance - inbox.minBalance !== 0);

    sendPayment({
      sender: inbox,
      receiver: this.txn.sender,
      amount: inbox.balance - inbox.minBalance,
    });
  }
}

/**
 * Send an asset to a receiver using the ARC59 router
 *
 * @param appClient The ARC59 client generated by algokit
 * @param assetId The ID of the asset to send
 * @param sender The address of the sender
 * @param receiver The address of the receiver
 * @param algorand The AlgorandClient instance to use to send transactions
 * @param sendAlgoForNewAccount Whether to send 201_000 uALGO to the receiver so they can claim the asset with a 0-ALGO balance
 */
async function arc59SendAsset(
  appClient: Arc59Client,
  assetId: bigint,
  sender: string,
  receiver: string,
  algorand: algokit.AlgorandClient
) {
  // Get the address of the ARC59 router
  const arc59RouterAddress = (await appClient.appClient.getAppReference())
    .appAddress;

  // Call arc59GetSendAssetInfo to get the following:
  // itxns - The number of transactions needed to send the asset
  // mbr - The minimum balance that must be sent to the router
  // routerOptedIn - Whether the router has opted in to the asset
  // receiverOptedIn - Whether the receiver has opted in to the asset
  const [
    itxns,
    mbr,
    routerOptedIn,
    receiverOptedIn,
    receiverAlgoNeededForClaim,
  ] = (await appClient.arc59GetSendAssetInfo({ asset: assetId, receiver }))
    .return!;

  // If the receiver has opted in, just send the asset directly
  if (receiverOptedIn) {
    await algorand.send.assetTransfer({
      sender,
      receiver,
      assetId,
      amount: 1n,
    });

    return;
  }

  // Create a composer to form an atomic transaction group
  const composer = appClient.compose();

  const signer = algorand.account.getSigner(sender);

  // If the MBR is non-zero, send the MBR to the router
  if (mbr || receiverAlgoNeededForClaim) {
    const mbrPayment = await algorand.transactions.payment({
      sender,
      receiver: arc59RouterAddress,
      amount: algokit.microAlgos(Number(mbr + receiverAlgoNeededForClaim)),
    });

    composer.addTransaction({ txn: mbrPayment, signer });
  }

  // If the router is not opted in, add a call to arc59OptRouterIn to do so
  if (!routerOptedIn) composer.arc59OptRouterIn({ asa: assetId });

  /** The box of the receiver's pubkey will always be needed */
  const boxes = [algosdk.decodeAddress(receiver).publicKey];

  /** The address of the receiver's inbox */
  const inboxAddress = (
    await appClient.compose().arc59GetInbox({ receiver }, { boxes }).simulate()
  ).returns[0];

  // The transfer of the asset to the router
  const axfer = await algorand.transactions.assetTransfer({
    sender,
    receiver: arc59RouterAddress,
    assetId,
    amount: 1n,
  });

  // An extra itxn is if we are also sending ALGO for the receiver claim
  const totalItxns = itxns + (receiverAlgoNeededForClaim === 0n ? 0n : 1n);

  composer.arc59SendAsset(
    { axfer, receiver, additionalReceiverFunds: receiverAlgoNeededForClaim },
    {
      sendParams: { fee: algokit.microAlgos(1000 + 1000 * Number(totalItxns)) },
      boxes, // The receiver's pubkey
      // Always good to include both accounts here, even if we think only the receiver is needed. This is to help protect against race conditions within a block.
      accounts: [receiver, inboxAddress],
      // Even though the asset is available in the group, we need to explicitly define it here because we will be checking the asset balance of the receiver
      assets: [Number(assetId)],
    }
  );

  // Disable resource population to ensure that our manually defined resources are correct
  algokit.Config.configure({ populateAppCallResources: false });

  // Send the transaction group
  await composer.execute();

  // Re-enable resource population
  algokit.Config.configure({ populateAppCallResources: true });
}

/**
 * Claim an asset from the ARC59 inbox
 *
 * @param appClient The ARC59 client generated by algokit
 * @param assetId The ID of the asset to claim
 * @param claimer The address of the account claiming the asset
 * @param algorand The AlgorandClient instance to use to send transactions
 */
async function arc59Claim(
  appClient: Arc59Client,
  assetId: bigint,
  claimer: string,
  algorand: algokit.AlgorandClient
) {
  const composer = appClient.compose();

  // Check if the claimer has opted in to the asset
  let claimerOptedIn = false;
  try {
    await algorand.account.getAssetInformation(claimer, assetId);
    claimerOptedIn = true;
  } catch (e) {
    // Do nothing
  }

  const inbox = (
    await appClient
      .compose()
      .arc59GetInbox({ receiver: claimer })
      .simulate({ allowUnnamedResources: true })
  ).returns[0];

  let totalTxns = 3;

  // If the inbox has extra ALGO, claim it
  const inboxInfo = await algorand.account.getInformation(inbox);
  if (inboxInfo.minBalance < inboxInfo.amount) {
    totalTxns += 2;
    composer.arc59ClaimAlgo(
      {},
      {
        sender: algorand.account.getAccount(claimer),
        sendParams: { fee: algokit.algos(0) },
      }
    );
  }

  // If the claimer hasn't already opted in, add a transaction to do so
  if (!claimerOptedIn) {
    composer.addTransaction({
      txn: await algorand.transactions.assetOptIn({ assetId, sender: claimer }),
      signer: algorand.account.getSigner(claimer),
    });
  }

  composer.arc59Claim(
    { asa: assetId },
    {
      sender: algorand.account.getAccount(claimer),
      sendParams: { fee: algokit.microAlgos(1000 * totalTxns) },
    }
  );

  await composer.execute();
}