algosdk 3.4.0 → 3.5.0

package/src/transaction.ts

@@ -1,5 +1,9 @@
 import base32 from 'hi-base32';
 import { boxReferencesToEncodingData } from './boxStorage.js';
+import {
+  resourceReferencesToEncodingData,
+  convertIndicesToResourceReferences,
+} from './appAccess.js';
 import { Address } from './encoding/address.js';
 import * as encoding from './encoding/encoding.js';
 import {
@@ -180,6 +184,73 @@ function ensureBoxReference(input: unknown): TransactionBoxReference {
   throw new Error(`Not a box reference: ${input}`);
 }
 
+export interface TransactionHoldingReference {
+  readonly assetIndex: bigint;
+  readonly address: Address;
+}
+
+function ensureHoldingReference(input: unknown): TransactionHoldingReference {
+  if (input != null && typeof input === 'object') {
+    const { assetIndex, address } = input as TransactionHoldingReference;
+    return {
+      assetIndex: utils.ensureUint64(assetIndex),
+      address: ensureAddress(address),
+    };
+  }
+  throw new Error(`Not a holding reference: ${input}`);
+}
+
+export interface TransactionLocalsReference {
+  readonly appIndex: bigint;
+  readonly address: Address;
+}
+
+function ensureLocalsReference(input: unknown): TransactionLocalsReference {
+  if (input != null && typeof input === 'object') {
+    const { appIndex, address } = input as TransactionLocalsReference;
+    return {
+      appIndex: utils.ensureUint64(appIndex),
+      address: ensureAddress(address),
+    };
+  }
+  throw new Error(`Not a locals reference: ${input}`);
+}
+
+export interface TransactionResourceReference {
+  readonly address?: Readonly<Address>;
+  readonly appIndex?: Readonly<bigint>;
+  readonly assetIndex?: Readonly<bigint>;
+  readonly holding?: Readonly<TransactionHoldingReference>;
+  readonly locals?: Readonly<TransactionLocalsReference>;
+  readonly box?: Readonly<TransactionBoxReference>;
+}
+
+function ensureResourceReference(input: unknown): TransactionResourceReference {
+  if (input != null && typeof input === 'object') {
+    const { address, appIndex, assetIndex, holding, locals, box } =
+      input as TransactionResourceReference;
+    if (address !== undefined) {
+      return { address: ensureAddress(address) };
+    }
+    if (appIndex !== undefined) {
+      return { appIndex: utils.ensureUint64(appIndex) };
+    }
+    if (assetIndex !== undefined) {
+      return { assetIndex: utils.ensureUint64(assetIndex) };
+    }
+    if (holding !== undefined) {
+      return { holding: ensureHoldingReference(holding) };
+    }
+    if (locals !== undefined) {
+      return { locals: ensureLocalsReference(locals) };
+    }
+    if (box !== undefined) {
+      return { box: ensureBoxReference(box) };
+    }
+  }
+  throw new Error(`Not a resource reference: ${input}`);
+}
+
 const TX_TAG = new TextEncoder().encode('TX');
 
 export interface PaymentTransactionFields {
@@ -242,6 +313,7 @@ export interface ApplicationTransactionFields {
   readonly foreignApps: ReadonlyArray<bigint>;
   readonly foreignAssets: ReadonlyArray<bigint>;
   readonly boxes: ReadonlyArray<TransactionBoxReference>;
+  readonly access: ReadonlyArray<TransactionResourceReference>;
 }
 
 export interface StateProofTransactionFields {
@@ -404,6 +476,80 @@ export class Transaction implements encoding.Encodable {
           )
         ),
       },
+      {
+        key: 'al',
+        valueSchema: new OptionalSchema(
+          new ArraySchema(
+            new NamedMapSchema(
+              allOmitEmpty([
+                {
+                  key: 'd',
+                  valueSchema: new OptionalSchema(new AddressSchema()),
+                },
+                {
+                  key: 's',
+                  valueSchema: new OptionalSchema(new Uint64Schema()),
+                },
+                {
+                  key: 'p',
+                  valueSchema: new OptionalSchema(new Uint64Schema()),
+                },
+                {
+                  key: 'h',
+                  valueSchema: new OptionalSchema(
+                    new NamedMapSchema(
+                      allOmitEmpty([
+                        {
+                          key: 'd',
+                          valueSchema: new Uint64Schema(),
+                        },
+                        {
+                          key: 's',
+                          valueSchema: new Uint64Schema(),
+                        },
+                      ])
+                    )
+                  ),
+                },
+                {
+                  key: 'l',
+                  valueSchema: new OptionalSchema(
+                    new NamedMapSchema(
+                      allOmitEmpty([
+                        {
+                          key: 'd',
+                          valueSchema: new Uint64Schema(),
+                        },
+                        {
+                          key: 'p',
+                          valueSchema: new Uint64Schema(),
+                        },
+                      ])
+                    )
+                  ),
+                },
+                {
+                  key: 'b',
+                  valueSchema: new OptionalSchema(
+                    new NamedMapSchema(
+                      allOmitEmpty([
+                        {
+                          key: 'i',
+                          valueSchema: new Uint64Schema(),
+                        },
+                        {
+                          key: 'n',
+                          valueSchema: new ByteArraySchema(),
+                        },
+                      ])
+                    )
+                  ),
+                },
+              ])
+            )
+          )
+        ),
+      },
       { key: 'apap', valueSchema: new OptionalSchema(new ByteArraySchema()) },
       { key: 'apsu', valueSchema: new OptionalSchema(new ByteArraySchema()) },
       {
@@ -702,6 +848,9 @@ export class Transaction implements encoding.Encodable {
         boxes: ensureArray(params.appCallParams.boxes ?? []).map(
           ensureBoxReference
         ),
+        access: ensureArray(params.appCallParams.access ?? []).map(
+          ensureResourceReference
+        ),
       };
     }
 
@@ -829,6 +978,13 @@ export class Transaction implements encoding.Encodable {
           this.applicationCall.appIndex
         )
       );
+      data.set(
+        'al',
+        resourceReferencesToEncodingData(
+          this.applicationCall.appIndex,
+          this.applicationCall.access
+        )
+      );
       data.set('apap', this.applicationCall.approvalProgram);
       data.set('apsu', this.applicationCall.clearProgram);
       data.set(
@@ -1030,6 +1186,12 @@ export class Transaction implements encoding.Encodable {
           };
         });
       }
+      const references = data.get('al') as
+        | Array<Map<string, unknown>>
+        | undefined;
+      if (references) {
+        appCallParams.access = convertIndicesToResourceReferences(references);
+      }
       params.appCallParams = appCallParams;
     } else if (params.type === TransactionType.stpf) {
       const stateProofParams: StateProofTransactionParams = {

package/src/types/transactions/base.ts

@@ -181,6 +181,86 @@ export interface BoxReference {
   name: Uint8Array;
 }
 
+/**
+ * A grouping of the asset index and address of the account
+ */
+export interface HoldingReference {
+  /**
+   * The asset index of the holding
+   */
+  assetIndex: number | bigint;
+
+  /**
+   * The address of the account holding the asset
+   */
+  address: string | Address;
+}
+
+/** A grouping of the application index and address of the account
+ */
+export interface LocalsReference {
+  /**
+   * The application index of the local state
+   */
+  appIndex: number | bigint;
+
+  /**
+   * The address of the account holding the local state
+   */
+  address: string | Address;
+}
+
+/**
+ * Parameters for resource references in application transactions
+ */
+export interface ApplicationCallReferenceParams {
+  /**
+   * A grouping of the asset index and address of the account
+   */
+  holdings?: HoldingReference[];
+
+  /** A grouping of the application index and address of the account
+   */
+  locals?: LocalsReference[];
+
+  /**
+   * If true, use the foreign accounts, apps, assets, boxes, holdings, and locals fields to construct the access list
+   */
+  convertToAccess?: boolean;
+}
+
+export interface ResourceReference {
+  /**
+   * Address string, any additional accounts to supply to the application
+   */
+  address?: string | Address;
+
+  /**
+   * Asset index uniquely specifying the asset
+   */
+  assetIndex?: number | bigint;
+
+  /**
+   * A unique application ID
+   */
+  appIndex?: number | bigint;
+
+  /**
+   * Holding definition: asset ID and account address
+   */
+  holding?: HoldingReference;
+
+  /**
+   * Local state definition: application ID and account address
+   */
+  locals?: LocalsReference;
+
+  /**
+   * Box definition: application ID and a name of the box
+   */
+  box?: BoxReference;
+}
+
 /**
  * Contains payment transaction parameters.
  *
@@ -451,6 +531,11 @@ export interface ApplicationCallTransactionParams {
    * A grouping of the app ID and name of the box in an Uint8Array
    */
   boxes?: BoxReference[];
+
+  /**
+   * Resources accessed by the application
+   */
+  access?: ResourceReference[];
 }
 
 /**