feat: add new authority actions for nano header

pedroferreira1 · pedroferreira1 · commit f140252758da · 2025-05-16T09:14:03.000-03:00
diff --git a/__tests__/integration/nanocontracts/bet.test.ts b/__tests__/integration/nanocontracts/bet.test.ts
@@ -142,7 +142,7 @@ describe('full cycle of bet nano contract', () => {
           {
             type: 'deposit',
             token: NATIVE_TOKEN_UID,
-            amount: 100,
+            amount: 100n,
             changeAddress: address0,
           },
         ],
@@ -158,7 +158,23 @@ describe('full cycle of bet nano contract', () => {
           {
             type: 'deposit',
             token: NATIVE_TOKEN_UID,
-            amount: 100,
+            amount: 100n,
+            changeAddress: address0,
+          },
+        ],
+      })
+    ).rejects.toThrow(NanoContractTransactionError);
+
+    // Not enough funds for the deposit
+    await expect(
+      wallet.createAndSendNanoContractTransaction('bet', address2, {
+        ncId: tx1.hash,
+        args: [address2, '1x0'],
+        actions: [
+          {
+            type: 'deposit',
+            token: NATIVE_TOKEN_UID,
+            amount: 1001n,
             changeAddress: address0,
           },
         ],
diff --git a/src/nano_contracts/builder.ts b/src/nano_contracts/builder.ts
@@ -15,10 +15,12 @@ import {
   DEFAULT_TX_VERSION,
   NATIVE_TOKEN_UID,
   NANO_CONTRACTS_INITIALIZE_METHOD,
+  TOKEN_MINT_MASK,
+  TOKEN_MELT_MASK
 } from '../constants';
 import Serializer from './serializer';
 import HathorWallet from '../new/wallet';
-import { NanoContractTransactionError } from '../errors';
+import { NanoContractTransactionError, UtxoError } from '../errors';
 import {
   ActionTypeToActionHeaderType,
   NanoContractActionHeader,
@@ -196,18 +198,14 @@ class NanoContractTransactionBuilder {
    * Create inputs (and maybe change outputs) to complete the deposit
    *
    * @param {action} Action to be completed (must be a deposit type)
-   * @param {tokens} Array of tokens to get the token data correctly
    *
    * @memberof NanoContractTransactionBuilder
    * @inner
    */
-  async executeDeposit(
-    action: NanoContractAction,
-    tokens: string[]
-  ): Promise<[IDataInput[], IDataOutput[]]> {
+  async executeDeposit(action: NanoContractAction): Promise<[IDataInput[], IDataOutput[]]> {
     if (action.type !== NanoContractActionType.DEPOSIT) {
       throw new NanoContractTransactionError(
-        "Can't execute a deposit with an action which type is differente than deposit."
+        "Can't execute a deposit with an action which type is different than deposit."
       );
     }
 
@@ -225,8 +223,17 @@ class NanoContractTransactionBuilder {
     if (action.address) {
       utxoOptions.filter_address = action.address;
     }
-    const utxosData = await this.wallet.getUtxosForAmount(action.amount, utxoOptions);
-    // XXX What if I don't have enough funds? Validate it!
+
+    let utxosData;
+    try {
+      utxosData = await this.wallet.getUtxosForAmount(action.amount, utxoOptions);
+    } catch (e) {
+      if (e instanceof UtxoError) {
+        throw new NanoContractTransactionError('Not enough utxos to execute the deposit.');
+      }
+
+      throw e;
+    }
     const inputs: IDataInput[] = [];
     for (const utxo of utxosData.utxos) {
       inputs.push({
@@ -266,21 +273,20 @@ class NanoContractTransactionBuilder {
    * then creates the output only of the difference
    *
    * @param {action} Action to be completed (must be a withdrawal type)
-   * @param {tokens} Array of tokens to get the token data correctly
    *
    * @memberof NanoContractTransactionBuilder
    * @inner
    */
-  executeWithdrawal(action: NanoContractAction, tokens: string[]): IDataOutput | null {
+  executeWithdrawal(action: NanoContractAction): IDataOutput | null {
     if (action.type !== NanoContractActionType.WITHDRAWAL) {
       throw new NanoContractTransactionError(
-        "Can't execute a withdrawal with an action which type is differente than withdrawal."
+        "Can't execute a withdrawal with an action which type is different than withdrawal."
       );
     }
 
     if (!action.amount || !action.token) {
       throw new NanoContractTransactionError(
-        'Address, amount and token are required for withdrawal action.'
+        'Amount and token are required for withdrawal action.'
       );
     }
 
@@ -327,6 +333,98 @@ class NanoContractTransactionBuilder {
     };
   }
 
+  /**
+   * Execute a grant authority action
+   * Create inputs (and maybe change output) to complete the action
+   *
+   * @param {action} Action to be completed (must be a grant authority type)
+   *
+   * @memberof NanoContractTransactionBuilder
+   * @inner
+   */
+  async executeGrantAuthority(action: NanoContractAction): Promise<[IDataInput[], IDataOutput[]]> {
+    if (action.type !== NanoContractActionType.GRANT_AUTHORITY) {
+      throw new NanoContractTransactionError(
+        "Can't execute a grant authority with an action which type is different than grant authority."
+      );
+    }
+
+    if (!action.authority || !action.token) {
+      throw new NanoContractTransactionError('Authority and token are required for grant authority action.');
+    }
+
+    const authorityAddressParam = action.authorityAddress;
+    if (authorityAddressParam && !(await this.wallet.isAddressMine(authorityAddressParam))) {
+      throw new NanoContractTransactionError('Authority address must belong to the same wallet.');
+    }
+
+    // Get the utxos with the authority of the action and create the input
+    const utxos = await this.wallet.getAuthorityUtxo(action.token, action.authority, { many: false, only_available_utxos: true, filter_address: action.address });
+
+    if (!utxos || utxos.length === 0) {
+      throw new NanoContractTransactionError('Not enough authority utxos to execute the grant authority.');
+    }
+
+    const inputs: IDataInput[] = [];
+    // The method gets only one utxo
+    const utxo = utxos[0];
+    inputs.push({
+      txId: utxo.txId,
+      index: utxo.index,
+      value: utxo.value,
+      authorities: utxo.authorities,
+      token: utxo.token,
+      address: utxo.address,
+    });
+
+    const outputs: IDataOutput[] = [];
+    // If there's the authorityAddress param, then we must create another authority output for this address
+    if (action.authorityAddress) {
+      outputs.push({
+        type: getAddressType(action.authorityAddress, this.wallet.getNetworkObject()),
+        address: action.authorityAddress,
+        value: action.authority === 'mint' ? TOKEN_MINT_MASK : TOKEN_MELT_MASK,
+        timelock: null,
+        token: action.token,
+        authorities: action.authority === 'mint' ? 1n : 2n,
+      });
+    }
+
+    return [inputs, outputs];
+  }
+
+  /**
+   * Execute an invoke authority action
+   *
+   * @param {action} Action to be completed (must be an invoke authority type)
+   *
+   * @memberof NanoContractTransactionBuilder
+   * @inner
+   */
+  executeInvokeAuthority(action: NanoContractAction): IDataOutput | null {
+    if (action.type !== NanoContractActionType.INVOKE_AUTHORITY) {
+      throw new NanoContractTransactionError(
+        "Can't execute an invoke authority with an action which type is different than invoke authority."
+      );
+    }
+
+    if (!action.address || !action.authority || !action.token) {
+      throw new NanoContractTransactionError(
+        'Address, authority, and token are required for invoke authority action.'
+      );
+    }
+
+    // Create the output with the authority of the action
+    return {
+      type: getAddressType(action.address, this.wallet.getNetworkObject()),
+      address: action.address,
+      value: action.authority === 'mint' ? TOKEN_MINT_MASK : TOKEN_MELT_MASK,
+      timelock: null,
+      token: action.token,
+      authorities: action.authority === 'mint' ? 1n : 2n,
+    };
+  }
+
   /**
    * Verify if the builder attributes are valid for the nano build
    *
diff --git a/src/nano_contracts/types.ts b/src/nano_contracts/types.ts
@@ -23,11 +23,15 @@ export enum NanoContractVertexType {
 export enum NanoContractActionType {
   DEPOSIT = 'deposit',
   WITHDRAWAL = 'withdrawal',
+  GRANT_AUTHORITY = 'grant_authority',
+  INVOKE_AUTHORITY = 'invoke_authority'
 }
 
 export enum NanoContractHeaderActionType {
   DEPOSIT = 1,
   WITHDRAWAL = 2,
+  GRANT_AUTHORITY = 3,
+  INVOKE_AUTHORITY = 4,
 }
 
 export const ActionTypeToActionHeaderType: Record<
@@ -36,6 +40,8 @@ export const ActionTypeToActionHeaderType: Record<
 > = {
   [NanoContractActionType.DEPOSIT]: NanoContractHeaderActionType.DEPOSIT,
   [NanoContractActionType.WITHDRAWAL]: NanoContractHeaderActionType.WITHDRAWAL,
+  [NanoContractActionType.GRANT_AUTHORITY]: NanoContractHeaderActionType.GRANT_AUTHORITY,
+  [NanoContractActionType.INVOKE_AUTHORITY]: NanoContractHeaderActionType.INVOKE_AUTHORITY,
 };
 
 // The action in the header is serialized/deserialized in the class
@@ -50,12 +56,18 @@ export interface NanoContractActionHeader {
 export interface NanoContractAction {
   type: NanoContractActionType;
   token: string;
-  amount: OutputValueType;
-  // For withdrawal is optional, which is address to send the output, in case one is created
-  // For deposit is optional, and it's the address to filter the utxos
+  // For withdrawal/deposit is required but authority actions
+  // will receive its information from the authority field
+  amount: OutputValueType | null;
+  // For withdrawal and create authority is required, which is address to send the output
+  // For deposit or grant authority actions is optional, and it's the address to filter the utxos
   address: string | null;
   // For deposit action is the change address used by the change output after selecting the utxos
   changeAddress: string | null;
+  // In case of an authority action, it specifies which authority
+  authority: 'mint' | 'melt' | null;
+  // For grant authority action, it's the address to create the authority output, if the user wants to keep it
+  authorityAddress: string | null;
 }
 
 // Arguments for blueprint methods
diff --git a/src/new/wallet.js b/src/new/wallet.js
@@ -1798,6 +1798,7 @@ class HathorWallet extends EventEmitter {
    * @param {Object} [options] Object with custom options.
    * @param {boolean} [options.many=false] if should return many utxos or just one (default false)
    * @param {boolean} [options.only_available_utxos=false] If we should filter for available utxos.
+   * @param {string} [options.filter_address=null] Address to filter the utxo to get.
    *
    * @return {Promise<{
    *   txId: string,
@@ -1809,20 +1810,7 @@ class HathorWallet extends EventEmitter {
    *       Returns an empty array in case there are no tx_outupts for this type.
    * */
   async getMintAuthority(tokenUid, options = {}) {
-    const newOptions = {
-      token: tokenUid,
-      authorities: 1n, // mint authority
-      only_available_utxos: options.only_available_utxos ?? false,
-    };
-    if (!options.many) {
-      // limit number of utxos to select if many is false
-      newOptions.max_utxos = 1;
-    }
-    const utxos = [];
-    for await (const utxo of this.storage.selectUtxos(newOptions)) {
-      utxos.push(utxo);
-    }
-    return utxos;
+    return this.getAuthorityUtxo(tokenUid, 'mint', options);
   }
 
   /**
@@ -1832,6 +1820,7 @@ class HathorWallet extends EventEmitter {
    * @param {Object} [options] Object with custom options.
    * @param {boolean} [options.many=false] if should return many utxos or just one (default false)
    * @param {boolean} [options.only_available_utxos=false] If we should filter for available utxos.
+   * @param {string} [options.filter_address=null] Address to filter the utxo to get.
    *
    * @return {Promise<{
    *   txId: string,
@@ -1843,10 +1832,43 @@ class HathorWallet extends EventEmitter {
    *       Returns an empty array in case there are no tx_outupts for this type.
    * */
   async getMeltAuthority(tokenUid, options = {}) {
+    return this.getAuthorityUtxo(tokenUid, 'melt', options);
+  }
+
+  /**
+   * Get authority utxo
+   *
+   * @param {string} tokenUid UID of the token to select the authority utxo
+   * @param {string} authority The authority to filter ('mint' or 'melt')
+   * @param {Object} [options] Object with custom options.
+   * @param {boolean} [options.many=false] if should return many utxos or just one (default false)
+   * @param {boolean} [options.only_available_utxos=false] If we should filter for available utxos.
+   * @param {string} [options.filter_address=null] Address to filter the utxo to get.
+   *
+   * @return {Promise<{
+   *   txId: string,
+   *   index: number,
+   *   address: string,
+   *   authorities: OutputValueType
+   * }[]>} Promise that resolves with an Array of objects with properties of the authority output.
+   *       The "authorities" field actually contains the output value with the authority masks.
+   *       Returns an empty array in case there are no tx_outupts for this type.
+   * */
+  async getAuthorityUtxo(tokenUid, authority, options = {}) {
+    let authorityValue;
+    if (authority === 'mint') {
+      authorityValue = 1n;
+    } else if (authority === 'melt') {
+      authorityValue = 2n;
+    } else {
+      throw new Error('Invalid authority value.');
+    }
+
     const newOptions = {
       token: tokenUid,
-      authorities: 2n, // melt authority
+      authorities: authorityValue,
       only_available_utxos: options.only_available_utxos ?? false,
+      filter_address: options.filter_address ?? null,
     };
     if (!options.many) {
       // limit number of utxos to select if many is false
