chore: pr feedback

Author: neilcampbell

docs/capabilities/app.md

@@ -382,6 +382,7 @@ When interacting with apps (creating, updating, deleting, calling), there are so
 - `appReferences?: bigint[]` - The ID of any apps to load to the [foreign apps array](https://dev.algorand.co/concepts/smart-contracts/resource-usage#what-are-reference-arrays).
 - `assetReferences?: bigint[]` - The ID of any assets to load to the [foreign assets array](https://dev.algorand.co/concepts/smart-contracts/resource-usage#what-are-reference-arrays).
 - `boxReferences?: (BoxReference | BoxIdentifier)[]` - Any [boxes](#box-references) to load to the [boxes array](https://dev.algorand.co/concepts/smart-contracts/resource-usage#what-are-reference-arrays)
+- `accessReference?: AccessReference[]` - Unifies `accountReferences`, `appReferences`, `assetReferences`, and `boxReferences` under a single list. If non-empty, these other reference lists must be empty. If access is empty, those other reference lists may be non-empty.
 
 When making an ABI call, the `args` parameter is replaced with a different type and there is also a `method` parameter per the [`AppMethodCall`](../code/modules/types_composer.md#appmethodcall) type:
 
@@ -428,6 +429,15 @@ export interface BoxReference {
 }
 ```
 
+## Access References
+
+Access references provide a unified way to specify all types of resource references (accounts, apps, assets, boxes, asset holdings, and app locals) that need to be accessible during smart contract execution. They are an alternative to using the separate `accountReferences`, `appReferences`, `assetReferences`, and `boxReferences` parameters.
+
+In using this unified field, you are able to use a total of 16 individual references, however cross references which enable smart contract access to local state and account asset balance information must be explicitly defined using `locals` and `holdings` fields respectively.
+When using the seperate reference arrays, you are constraints to a collective total of 8.
+
+The separate reference arrays (`accountReferences`, `appReferences`, etc.) remain fully supported, however when using `accessReferences`, you cannot also use `accountReferences`, `appReferences`, `assetReferences` or `boxReferences`.
+
 ## Compilation
 
 The [`AppManager`](#appmanager) class allows you to compile TEAL code with caching semantics that allows you to avoid duplicate compilation and keep track of source maps from compiled code.

src/transaction/transaction.spec.ts

@@ -1169,6 +1169,24 @@ describe('access references', () => {
   let appClient: AppClient
   let externalClient: AppClient
 
+  let alice: algosdk.Address
+  let bob: algosdk.Address
+  let charlie: algosdk.Address
+  let dan: algosdk.Address
+  let eve: algosdk.Address
+  let frank: algosdk.Address
+  let grace: algosdk.Address
+  let heidi: algosdk.Address
+  let ivan: algosdk.Address
+  let judy: algosdk.Address
+  let mallory: algosdk.Address
+  let niaj: algosdk.Address
+  let oscar: algosdk.Address
+  let peggy: algosdk.Address
+  let quentin: algosdk.Address
+  let ruth: algosdk.Address
+  let dave: algosdk.Address
+
   beforeEach(fixture.newScope)
 
   beforeAll(async () => {
@@ -1192,7 +1210,25 @@ describe('access references', () => {
       appId: (await appClient.getGlobalState()).externalAppID.value as bigint,
       defaultSender: testAccount,
     })
-  })
+
+    alice = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    bob = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    charlie = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    dan = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    eve = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    frank = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    grace = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    heidi = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    ivan = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    judy = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    mallory = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    niaj = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    oscar = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    peggy = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    quentin = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    ruth = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+    dave = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(1) })
+  }, 20_000) // Account generation and funding can be slow
 
   test('address reference enables access', async () => {
     const alice = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
@@ -1205,16 +1241,7 @@ describe('access references', () => {
     await appClient.send.bare.call({ args: [method, aliceAddr], populateAppCallResources: false, accessReferences: [{ address: alice }] })
   })
 
-  test('only 8 non access reference accounts can be supplied', async () => {
-    const alice = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const bob = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const charlie = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const dan = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const eve = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const frank = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const grace = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const heidi = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-
+  test('up to 8 non access reference accounts can be used', async () => {
     const method = appClient.getABIMethod('addressBalance').getSelector()
 
     const addressType = new ABIAddressType()
@@ -1227,24 +1254,22 @@ describe('access references', () => {
     })
   })
 
-  test('only 16 access addresses can be supplied', async () => {
-    const alice = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const bob = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const charlie = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const dan = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const eve = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const frank = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const grace = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const heidi = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const ivan = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const judy = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const mallory = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const niaj = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const oscar = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const peggy = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const quentin = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
-    const ruth = await fixture.context.generateAccount({ initialFunds: AlgoAmount.Algo(0.1) })
+  test('throws when more than 8 non access reference accounts are supplied', async () => {
+    const method = appClient.getABIMethod('addressBalance').getSelector()
+
+    const addressType = new ABIAddressType()
+    const aliceAddr = addressType.encode(alice)
 
+    await expect(
+      appClient.send.bare.call({
+        args: [method, aliceAddr],
+        populateAppCallResources: false,
+        accountReferences: [alice, bob, charlie, dan, eve, frank, grace, heidi, ivan],
+      }),
+    ).rejects.toThrow(/max number of accounts is 8/)
+  })
+
+  test('up to 16 access addresses can be used', async () => {
     const method = appClient.getABIMethod('addressBalance').getSelector()
 
     const addressType = new ABIAddressType()
@@ -1274,6 +1299,39 @@ describe('access references', () => {
     })
   })
 
+  test('throws when more than 16 access addresses are supplied', async () => {
+    const method = appClient.getABIMethod('addressBalance').getSelector()
+
+    const addressType = new ABIAddressType()
+    const aliceAddr = addressType.encode(alice)
+
+    await expect(
+      appClient.send.bare.call({
+        args: [method, aliceAddr],
+        populateAppCallResources: false,
+        accessReferences: [
+          { address: alice },
+          { address: bob },
+          { address: charlie },
+          { address: dan },
+          { address: eve },
+          { address: frank },
+          { address: grace },
+          { address: heidi },
+          { address: ivan },
+          { address: judy },
+          { address: mallory },
+          { address: niaj },
+          { address: oscar },
+          { address: peggy },
+          { address: quentin },
+          { address: ruth },
+          { address: dave },
+        ],
+      }),
+    ).rejects.toThrow(/max number of references is 16/)
+  })
+
   test('app reference enables access', async () => {
     const method = appClient.getABIMethod('externalAppCall').getSelector()