From 1baa335033cbe4ebba984548f018b8f60c0acd08 Mon Sep 17 00:00:00 2001
From: Cat McGee <hello@mcgee.cat>
Date: Mon, 6 May 2024 11:51:59 +0300
Subject: [PATCH 01/11] initial docs

---
 .../docs/developers/aztecjs/guides/authwit.md | 36 +++++++++++++++++++
 .../accounts/how_to_authwit.md}               |  6 +++-
 .../end-to-end/src/e2e_authwit.test.ts        |  2 ++
 yarn-project/end-to-end/src/fixtures/utils.ts |  3 ++
 4 files changed, 46 insertions(+), 1 deletion(-)
 create mode 100644 docs/docs/developers/aztecjs/guides/authwit.md
 rename docs/docs/developers/contracts/{resources/common_patterns/authwit.md => writing_contracts/accounts/how_to_authwit.md} (97%)

diff --git a/docs/docs/developers/aztecjs/guides/authwit.md b/docs/docs/developers/aztecjs/guides/authwit.md
new file mode 100644
index 00000000000..06a4c4dd43e
--- /dev/null
+++ b/docs/docs/developers/aztecjs/guides/authwit.md
@@ -0,0 +1,36 @@
+---
+title: How to use authentication witnesses (authwit)
+---
+
+This page assumes you have authwit set up correctly in your contract. To learn how to do that, [go here](../../contracts/writing_contracts/accounts/how_to_authwit.md).
+
+For an introduction to authentication witnesses on Aztec, [read this explainer](../../../learn/concepts/accounts/authwit.md).
+
+## Import libraries
+
+## Publicly deploy accounts
+
+:::note
+This is only required if you are using authwits in public
+:::note
+
+If you are using public authwit (ie using `assert_current_call_valid_authwit_public` in your contract), you will need to deploy the following accounts publicly:
+
+1. The account that is giving permission to an account to act on behalf of it (gives the authwit)
+2. The account that does the action (receives the authwit)
+
+Here is an example implementation:
+
+#include_code public_deploy_accounts yarn-project/end-to-end/src/fixtures/utils.ts typescript
+
+You would then call this like so:
+
+#include_code public_deploy_accounts yarn-project/end-to-end/src/e2e_authwit_test.ts typescript
+
+## Define the action
+
+## Set the authwit
+
+### Public
+
+### Private
diff --git a/docs/docs/developers/contracts/resources/common_patterns/authwit.md b/docs/docs/developers/contracts/writing_contracts/accounts/how_to_authwit.md
similarity index 97%
rename from docs/docs/developers/contracts/resources/common_patterns/authwit.md
rename to docs/docs/developers/contracts/writing_contracts/accounts/how_to_authwit.md
index f1649d731ef..c5481c0bf64 100644
--- a/docs/docs/developers/contracts/resources/common_patterns/authwit.md
+++ b/docs/docs/developers/contracts/writing_contracts/accounts/how_to_authwit.md
@@ -3,6 +3,10 @@ title: Authentication Witness
 description: Developer Documentation to use Authentication Witness for authentication actions on Aztec.
 ---
 
+This page introduces the authwit library and how you can use it in your Aztec.nr smart contracts. [Skip to the usage](#usage).
+
+For a guide on using authwit in Aztec.js, [read this](../../../aztecjs/guides/authwit.md).
+
 ## Prerequisite reading
 
 - [Authwit](./../../../../learn/concepts/accounts/authwit.md)
@@ -117,7 +121,7 @@ Very similar to the above, we have variations that work in the public domain. Th
 
 ## Usage
 
-Ok, enough talking, how the hell do we use this?
+Ok, enough talking, how do we use this?
 
 ### Importing it
 
diff --git a/yarn-project/end-to-end/src/e2e_authwit.test.ts b/yarn-project/end-to-end/src/e2e_authwit.test.ts
index 42865d4793a..d80af30af8f 100644
--- a/yarn-project/end-to-end/src/e2e_authwit.test.ts
+++ b/yarn-project/end-to-end/src/e2e_authwit.test.ts
@@ -17,7 +17,9 @@ describe('e2e_authwit_tests', () => {
 
   beforeAll(async () => {
     ({ wallets } = await setup(2));
+    // docs:start:public_deploy_accounts
     await publicDeployAccounts(wallets[0], wallets.slice(0, 2));
+    // docs:start:public_deploy_accounts
 
     const nodeInfo = await wallets[0].getNodeInfo();
     chainId = new Fr(nodeInfo.chainId);
diff --git a/yarn-project/end-to-end/src/fixtures/utils.ts b/yarn-project/end-to-end/src/fixtures/utils.ts
index e1d257d8204..1b0543c81dd 100644
--- a/yarn-project/end-to-end/src/fixtures/utils.ts
+++ b/yarn-project/end-to-end/src/fixtures/utils.ts
@@ -502,6 +502,8 @@ export async function setup(
  * @param sender - Wallet to send the deployment tx.
  * @param accountsToDeploy - Which accounts to publicly deploy.
  */
+
+// docs:start:public_deploy_accounts
 export async function publicDeployAccounts(sender: Wallet, accountsToDeploy: Wallet[]) {
   const accountAddressesToDeploy = accountsToDeploy.map(a => a.getAddress());
   const instances = await Promise.all(accountAddressesToDeploy.map(account => sender.getContractInstance(account)));
@@ -511,6 +513,7 @@ export async function publicDeployAccounts(sender: Wallet, accountsToDeploy: Wal
   ]);
   await batch.send().wait();
 }
+// docs:end:public_deploy_accounts
 
 /**
  * Sets the timestamp of the next block.

From 4070694ebabaf04fd6a44c011c2d0a6c4b9d306e Mon Sep 17 00:00:00 2001
From: Cat McGee <hello@mcgee.cat>
Date: Mon, 6 May 2024 14:31:17 +0300
Subject: [PATCH 02/11] include_code

---
 .../docs/developers/aztecjs/guides/authwit.md | 45 +++++++++++++++++--
 .../accounts/how_to_authwit.md                |  2 +
 docs/sidebars.js                              | 20 ++-------
 .../transfer_private.test.ts                  |  4 ++
 .../transfer_public.test.ts                   |  4 +-
 5 files changed, 54 insertions(+), 21 deletions(-)

diff --git a/docs/docs/developers/aztecjs/guides/authwit.md b/docs/docs/developers/aztecjs/guides/authwit.md
index 06a4c4dd43e..548ec061b0a 100644
--- a/docs/docs/developers/aztecjs/guides/authwit.md
+++ b/docs/docs/developers/aztecjs/guides/authwit.md
@@ -16,8 +16,8 @@ This is only required if you are using authwits in public
 
 If you are using public authwit (ie using `assert_current_call_valid_authwit_public` in your contract), you will need to deploy the following accounts publicly:
 
-1. The account that is giving permission to an account to act on behalf of it (gives the authwit)
-2. The account that does the action (receives the authwit)
+1. The account that is giving permission to an account to act on behalf of it (authwit giver)
+2. The account that does the action (authwit receiver)
 
 Here is an example implementation:
 
@@ -29,8 +29,47 @@ You would then call this like so:
 
 ## Define the action
 
-## Set the authwit
+The next steps are assuming that you do not already have the message hash. If you have this, skip to [the guide for creating authwits with pre-calculated message hashes](#if-message-hash-is-already-computed).
+
+When creating an authwit, you will need to pass the authwit givier, the authwit receiver (who will perform the action), and the action that is being authorized. 
+
+You can define the action like this:
+
+#include_code authwit_computeAuthWitMessageHash yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts typescript
+
+In this example,
+* `asset` refers to a token contract
+* `withWallet(wallets[1])` is specifying the authwit receiver (`wallets[1]` will do this action
+* `.methods.transfer()` is specifying that the action is calling the `transfer` method on the token contract
+* `(wallets[0].getAddress(), wallets[1].getAddress(), amount, nonce);` are the args of this method - it will send the `amount` from `wallets[0]` to `wallets[1]`
+
+## Create the authwit
 
 ### Public
 
+This is expected to be used alongside [public authwits in Aztec.nr contract](../../contracts/writing_contracts/accounts/how_to_authwit.md#public-functions).
+
+Set a public authwit like this:
+
+#include_code set_public_authwit yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_public.test.ts typescript
+
+In this example,
+* `wallets[0]` is the authwit giver
+* `wallets[1]` is the authwit reciever and caller of the function
+* `action` was [defined previously](#define-the-action)
+* `true` sets the `authorized` boolean (`false` would revoke this authwit)
+
 ### Private
+
+This is expected to be used alongside [private authwits in Aztec.nr contract](../../contracts/writing_contracts/accounts/how_to_authwit.md#private-functions).
+
+Create a private authwit like this:
+
+#include_code create_authwit yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts typescript
+
+Then add it to a wallet:
+
+#include_code add_authwit yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts typescript
+
+# If message hash is already computed
+
diff --git a/docs/docs/developers/contracts/writing_contracts/accounts/how_to_authwit.md b/docs/docs/developers/contracts/writing_contracts/accounts/how_to_authwit.md
index c5481c0bf64..8ce50499258 100644
--- a/docs/docs/developers/contracts/writing_contracts/accounts/how_to_authwit.md
+++ b/docs/docs/developers/contracts/writing_contracts/accounts/how_to_authwit.md
@@ -155,6 +155,8 @@ Cool, so we have a function that checks if the current call is authenticated, bu
 
 #include_code authwit_transfer_example /yarn-project/end-to-end/src/e2e_token_contract/transfer_private.test.ts typescript
 
+Learn more about authwits in Aztec.js by [following this guide](../../../aztecjs/guides/authwit.md).
+
 ### Public Functions
 
 With private functions covered, how can we use this in a public function? Well, the answer is that we simply change one name of a function and then we are good to go :eyes: (almost).
diff --git a/docs/sidebars.js b/docs/sidebars.js
index b2272172ad8..6db2a8cb429 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -363,7 +363,8 @@ const sidebars = {
               label: "Accounts and Account Contracts",
               type: "category",
               items: [
-                "developers/contracts/writing_contracts/accounts/write_accounts_contract",
+                "developers/contracts/writing_contracts/accounts/how_to_authwit",
+                "developers/contracts/writing_contracts/accounts/authwit",
               ],
             },
             {
@@ -463,22 +464,8 @@ const sidebars = {
           type: "category",
           items: [
             "developers/contracts/resources/dependencies",
+            "developers/contracts/resources/common_patterns/main",
             //"developers/contracts/resources/style_guide",
-            {
-              label: "Common Patterns",
-              type: "category",
-              link: {
-                type: "doc",
-                id: "developers/contracts/resources/common_patterns/main",
-              },
-              items: [
-                "developers/contracts/resources/common_patterns/authwit",
-                //         "developers/contracts/resources/common_patterns/sending_tokens_to_user",
-                //         "developers/contracts/resources/common_patterns/sending_tokens_to_contract",
-                //         "developers/contracts/resources/common_patterns/access_control",
-                //         "developers/contracts/resources/common_patterns/interacting_with_l1",
-              ],
-            },
           ],
         },
         // {
@@ -515,6 +502,7 @@ const sidebars = {
             "developers/aztecjs/guides/deploy_contract",
             "developers/aztecjs/guides/send_transaction",
             "developers/aztecjs/guides/call_view_function",
+            "developers/aztecjs/guides/authwit",
           ],
         },
         {
diff --git a/yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts b/yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts
index ed78def1481..ced33c3d585 100644
--- a/yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts
+++ b/yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts
@@ -158,8 +158,12 @@ describe('e2e_blacklist_token_contract transfer private', () => {
         action.request(),
       );
 
+      // docs:start:create_authwit
       const witness = await wallets[0].createAuthWit({ caller: wallets[1].getAddress(), action });
+      // docs:end:create_authwit
+      // docs:start:add_authwit
       await wallets[2].addAuthWitness(witness);
+      // docs:end:add_authwit
 
       await expect(action.prove()).rejects.toThrow(
         `Unknown auth witness for message hash ${expectedMessageHash.toString()}`,
diff --git a/yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_public.test.ts b/yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_public.test.ts
index 1459704e8aa..7f24bf77192 100644
--- a/yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_public.test.ts
+++ b/yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_public.test.ts
@@ -112,8 +112,9 @@ describe('e2e_blacklist_token_contract transfer public', () => {
         .methods.transfer_public(wallets[0].getAddress(), wallets[1].getAddress(), amount, nonce);
 
       // We need to compute the message we want to sign and add it to the wallet as approved
+      // docs:start:set_public_authwit
       await wallets[0].setPublicAuthWit({ caller: wallets[1].getAddress(), action }, true).send().wait();
-
+      // docs:end:set_public_authwit
       // Perform the transfer
       await expect(action.prove()).rejects.toThrow(U128_UNDERFLOW_ERROR);
 
@@ -154,7 +155,6 @@ describe('e2e_blacklist_token_contract transfer public', () => {
         .withWallet(wallets[1])
         .methods.transfer_public(wallets[0].getAddress(), wallets[1].getAddress(), amount, nonce);
       await wallets[0].setPublicAuthWit({ caller: wallets[0].getAddress(), action }, true).send().wait();
-
       // Perform the transfer
       await expect(action.prove()).rejects.toThrow('Assertion failed: Message not authorized by account');
 

From d063f2f05528773f9ef4b4d8ad6663ac5f9a6b93 Mon Sep 17 00:00:00 2001
From: Cat McGee <hello@mcgee.cat>
Date: Wed, 8 May 2024 14:20:14 +0300
Subject: [PATCH 03/11] added arbitrary data in authwits

---
 .../docs/developers/aztecjs/guides/authwit.md | 65 ++++++++++++++-----
 .../end-to-end/src/e2e_authwit.test.ts        | 11 +++-
 .../transfer_private.test.ts                  |  9 ++-
 3 files changed, 62 insertions(+), 23 deletions(-)

diff --git a/docs/docs/developers/aztecjs/guides/authwit.md b/docs/docs/developers/aztecjs/guides/authwit.md
index 548ec061b0a..0b54d065124 100644
--- a/docs/docs/developers/aztecjs/guides/authwit.md
+++ b/docs/docs/developers/aztecjs/guides/authwit.md
@@ -8,6 +8,14 @@ For an introduction to authentication witnesses on Aztec, [read this explainer](
 
 ## Import libraries
 
+These are all the libraries you will need for the various ways of using authwits in Aztec.js:
+
+```typescript
+import { computeAuthWitMessageHash, computeInnerAuthWitHash, computeOuterAuthWitHash } from '@aztec/aztec.js';
+```
+
+You may not need all of these.
+
 ## Publicly deploy accounts
 
 :::note
@@ -29,9 +37,9 @@ You would then call this like so:
 
 ## Define the action
 
-The next steps are assuming that you do not already have the message hash. If you have this, skip to [the guide for creating authwits with pre-calculated message hashes](#if-message-hash-is-already-computed).
+When creating an authwit, you will need to pass the authwit givier, the authwit receiver (who will perform the action), and the action that is being authorized. The action can be a smart contract function call, or alternatively arbitrary data.
 
-When creating an authwit, you will need to pass the authwit givier, the authwit receiver (who will perform the action), and the action that is being authorized. 
+### When the action is a function call
 
 You can define the action like this:
 
@@ -39,25 +47,23 @@ You can define the action like this:
 
 In this example,
 * `asset` refers to a token contract
-* `withWallet(wallets[1])` is specifying the authwit receiver (`wallets[1]` will do this action
+* `withWallet(wallets[1])` is specifying the authwit receiver (`wallets[1]`) will do this action
 * `.methods.transfer()` is specifying that the action is calling the `transfer` method on the token contract
 * `(wallets[0].getAddress(), wallets[1].getAddress(), amount, nonce);` are the args of this method - it will send the `amount` from `wallets[0]` to `wallets[1]`
 
-## Create the authwit
+### Arbitrary message
 
-### Public
+You can hash your own authwit message by creating an inner hash with the data, like this:
 
-This is expected to be used alongside [public authwits in Aztec.nr contract](../../contracts/writing_contracts/accounts/how_to_authwit.md#public-functions).
+#include_code compute_inner_authwit_hash yarn-project/end-to-end/src/e2e_authwit.test.ts typescript
 
-Set a public authwit like this:
+Then create the outer hash by hashing the inner hash with the authwit receiver address, chainId, and version:
 
-#include_code set_public_authwit yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_public.test.ts typescript
+#include_code compute_outer_authwit_hash yarn-project/end-to-end/src/e2e_authwit.test.ts typescript
 
-In this example,
-* `wallets[0]` is the authwit giver
-* `wallets[1]` is the authwit reciever and caller of the function
-* `action` was [defined previously](#define-the-action)
-* `true` sets the `authorized` boolean (`false` would revoke this authwit)
+## Create the authwit
+
+These are slightly different interfaces depending on whether your contract is checking the authwit in private or public. As public authwits are stored in the account contract and batched with the authwit action call, it is done with one transaction. Private execution uses oracles, so the authwit needs to be created by the authwit giver and then added to the receiver's wallet. 
 
 ### Private
 
@@ -67,9 +73,38 @@ Create a private authwit like this:
 
 #include_code create_authwit yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts typescript
 
-Then add it to a wallet:
+In this example,
+* `wallets[0]` is the authwit giver
+* `wallets[1]` is the authwit reciever and caller of the function
+* `action` was [defined previously](#define-the-action)
+
+If you created an artbitrary message, you can create the authwit by replacing these params with the outer hash:
+
+#include_code compute_outer_authwit_hash yarn-project/end-to-end/src/e2e_authwit.test.ts typescript
+
+Then add it to the wallet of the authwit receiver (the caller of the transaction):
 
 #include_code add_authwit yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts typescript
 
-# If message hash is already computed
+### Public
+
+This is expected to be used alongside [public authwits in Aztec.nr contract](../../contracts/writing_contracts/accounts/how_to_authwit.md#public-functions).
+
+Set a public authwit like this:
+
+#include_code set_public_authwit yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_public.test.ts typescript
+
+Remember it is a transaction and calls a method in the account contract. In this example,
+* `wallets[0]` is the authwit giver
+* `wallets[1]` is the authwit reciever and caller of the function
+* `action` was [defined previously](#define-the-action)
+* `true` sets the `authorized` boolean (`false` would revoke this authwit)
+
+If you created an arbitrary message, you would replace the first param struct with the outer hash:
+
+#include_code set_public_authwit yarn-project/end-to-end/src/e2e_authwit.test.ts typescript
+
+# Further reading
 
+* [An explainer of authentication witnesses](../../../learn/concepts/accounts/authwit.md)
+* [Authwits in Aztec.nr](../../contracts/writing_contracts/accounts/how_to_authwit.md)
diff --git a/yarn-project/end-to-end/src/e2e_authwit.test.ts b/yarn-project/end-to-end/src/e2e_authwit.test.ts
index d80af30af8f..7a5eff42cf5 100644
--- a/yarn-project/end-to-end/src/e2e_authwit.test.ts
+++ b/yarn-project/end-to-end/src/e2e_authwit.test.ts
@@ -29,10 +29,15 @@ describe('e2e_authwit_tests', () => {
   describe('Private', () => {
     describe('arbitrary data', () => {
       it('happy path', async () => {
+        // docs:start:compute_inner_authwit_hash
         const innerHash = computeInnerAuthWitHash([Fr.fromString('0xdead')]);
+        // docs:end:compute_inner_authwit_hash
+        // docs:start:compute_outer_authwit_hash
         const outerHash = computeOuterAuthWitHash(wallets[1].getAddress(), chainId, version, innerHash);
-
+        // docs:end:compute_outer_authwit_hash
+        // docs:start:create_authwit
         const witness = await wallets[0].createAuthWit(outerHash);
+        // docs:end:create_authwit
         await wallets[1].addAuthWitness(witness);
 
         // Check that the authwit is valid in private for wallets[0]
@@ -187,14 +192,14 @@ describe('e2e_authwit_tests', () => {
       it('happy path', async () => {
         const innerHash = computeInnerAuthWitHash([Fr.fromString('0xdead'), Fr.fromString('0x01')]);
         const outerHash = computeOuterAuthWitHash(wallets[1].getAddress(), chainId, version, innerHash);
-
         expect(await wallets[0].lookupValidity(wallets[0].getAddress(), outerHash)).toEqual({
           isValidInPrivate: false,
           isValidInPublic: false,
         });
 
+        // docs:start:set_public_authwit
         await wallets[0].setPublicAuthWit(outerHash, true).send().wait();
-
+        // docs:end:set_public_authwit
         expect(await wallets[0].lookupValidity(wallets[0].getAddress(), outerHash)).toEqual({
           isValidInPrivate: false,
           isValidInPublic: true,
diff --git a/yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts b/yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts
index ced33c3d585..50f846f9169 100644
--- a/yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts
+++ b/yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts
@@ -53,9 +53,12 @@ describe('e2e_blacklist_token_contract transfer private', () => {
       .withWallet(wallets[1])
       .methods.transfer(wallets[0].getAddress(), wallets[1].getAddress(), amount, nonce);
     // docs:end:authwit_computeAuthWitMessageHash
-
+    // docs:start:create_authwit
     const witness = await wallets[0].createAuthWit({ caller: wallets[1].getAddress(), action });
+    // docs:end:create_authwit
+    // docs:start:add_authwit
     await wallets[1].addAuthWitness(witness);
+    // docs:end:add_authwit
     // docs:end:authwit_transfer_example
 
     // Perform the transfer
@@ -158,12 +161,8 @@ describe('e2e_blacklist_token_contract transfer private', () => {
         action.request(),
       );
 
-      // docs:start:create_authwit
       const witness = await wallets[0].createAuthWit({ caller: wallets[1].getAddress(), action });
-      // docs:end:create_authwit
-      // docs:start:add_authwit
       await wallets[2].addAuthWitness(witness);
-      // docs:end:add_authwit
 
       await expect(action.prove()).rejects.toThrow(
         `Unknown auth witness for message hash ${expectedMessageHash.toString()}`,

From d3f5198ea4b5a70dc2dd088ebcb8acec3ffa22b6 Mon Sep 17 00:00:00 2001
From: Josh Crites <jc@joshcrites.com>
Date: Thu, 9 May 2024 15:32:40 -0400
Subject: [PATCH 04/11] fix test reference

---
 .../docs/developers/aztecjs/guides/authwit.md | 39 +++++++++++--------
 .../end-to-end/src/e2e_authwit.test.ts        |  2 +-
 2 files changed, 24 insertions(+), 17 deletions(-)

diff --git a/docs/docs/developers/aztecjs/guides/authwit.md b/docs/docs/developers/aztecjs/guides/authwit.md
index 0b54d065124..7ebe618c25d 100644
--- a/docs/docs/developers/aztecjs/guides/authwit.md
+++ b/docs/docs/developers/aztecjs/guides/authwit.md
@@ -11,7 +11,11 @@ For an introduction to authentication witnesses on Aztec, [read this explainer](
 These are all the libraries you will need for the various ways of using authwits in Aztec.js:
 
 ```typescript
-import { computeAuthWitMessageHash, computeInnerAuthWitHash, computeOuterAuthWitHash } from '@aztec/aztec.js';
+import {
+  computeAuthWitMessageHash,
+  computeInnerAuthWitHash,
+  computeOuterAuthWitHash,
+} from "@aztec/aztec.js";
 ```
 
 You may not need all of these.
@@ -33,7 +37,7 @@ Here is an example implementation:
 
 You would then call this like so:
 
-#include_code public_deploy_accounts yarn-project/end-to-end/src/e2e_authwit_test.ts typescript
+#include_code public_deploy_accounts yarn-project/end-to-end/src/e2e_authwit.test.ts typescript
 
 ## Define the action
 
@@ -46,10 +50,11 @@ You can define the action like this:
 #include_code authwit_computeAuthWitMessageHash yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts typescript
 
 In this example,
-* `asset` refers to a token contract
-* `withWallet(wallets[1])` is specifying the authwit receiver (`wallets[1]`) will do this action
-* `.methods.transfer()` is specifying that the action is calling the `transfer` method on the token contract
-* `(wallets[0].getAddress(), wallets[1].getAddress(), amount, nonce);` are the args of this method - it will send the `amount` from `wallets[0]` to `wallets[1]`
+
+- `asset` refers to a token contract
+- `withWallet(wallets[1])` is specifying the authwit receiver (`wallets[1]`) will do this action
+- `.methods.transfer()` is specifying that the action is calling the `transfer` method on the token contract
+- `(wallets[0].getAddress(), wallets[1].getAddress(), amount, nonce);` are the args of this method - it will send the `amount` from `wallets[0]` to `wallets[1]`
 
 ### Arbitrary message
 
@@ -63,7 +68,7 @@ Then create the outer hash by hashing the inner hash with the authwit receiver a
 
 ## Create the authwit
 
-These are slightly different interfaces depending on whether your contract is checking the authwit in private or public. As public authwits are stored in the account contract and batched with the authwit action call, it is done with one transaction. Private execution uses oracles, so the authwit needs to be created by the authwit giver and then added to the receiver's wallet. 
+These are slightly different interfaces depending on whether your contract is checking the authwit in private or public. As public authwits are stored in the account contract and batched with the authwit action call, it is done with one transaction. Private execution uses oracles, so the authwit needs to be created by the authwit giver and then added to the receiver's wallet.
 
 ### Private
 
@@ -74,9 +79,10 @@ Create a private authwit like this:
 #include_code create_authwit yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts typescript
 
 In this example,
-* `wallets[0]` is the authwit giver
-* `wallets[1]` is the authwit reciever and caller of the function
-* `action` was [defined previously](#define-the-action)
+
+- `wallets[0]` is the authwit giver
+- `wallets[1]` is the authwit reciever and caller of the function
+- `action` was [defined previously](#define-the-action)
 
 If you created an artbitrary message, you can create the authwit by replacing these params with the outer hash:
 
@@ -95,10 +101,11 @@ Set a public authwit like this:
 #include_code set_public_authwit yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_public.test.ts typescript
 
 Remember it is a transaction and calls a method in the account contract. In this example,
-* `wallets[0]` is the authwit giver
-* `wallets[1]` is the authwit reciever and caller of the function
-* `action` was [defined previously](#define-the-action)
-* `true` sets the `authorized` boolean (`false` would revoke this authwit)
+
+- `wallets[0]` is the authwit giver
+- `wallets[1]` is the authwit reciever and caller of the function
+- `action` was [defined previously](#define-the-action)
+- `true` sets the `authorized` boolean (`false` would revoke this authwit)
 
 If you created an arbitrary message, you would replace the first param struct with the outer hash:
 
@@ -106,5 +113,5 @@ If you created an arbitrary message, you would replace the first param struct wi
 
 # Further reading
 
-* [An explainer of authentication witnesses](../../../learn/concepts/accounts/authwit.md)
-* [Authwits in Aztec.nr](../../contracts/writing_contracts/accounts/how_to_authwit.md)
+- [An explainer of authentication witnesses](../../../learn/concepts/accounts/authwit.md)
+- [Authwits in Aztec.nr](../../contracts/writing_contracts/accounts/how_to_authwit.md)
diff --git a/yarn-project/end-to-end/src/e2e_authwit.test.ts b/yarn-project/end-to-end/src/e2e_authwit.test.ts
index 7a5eff42cf5..baa4d4a0fba 100644
--- a/yarn-project/end-to-end/src/e2e_authwit.test.ts
+++ b/yarn-project/end-to-end/src/e2e_authwit.test.ts
@@ -19,7 +19,7 @@ describe('e2e_authwit_tests', () => {
     ({ wallets } = await setup(2));
     // docs:start:public_deploy_accounts
     await publicDeployAccounts(wallets[0], wallets.slice(0, 2));
-    // docs:start:public_deploy_accounts
+    // docs:end:public_deploy_accounts
 
     const nodeInfo = await wallets[0].getNodeInfo();
     chainId = new Fr(nodeInfo.chainId);

From 178dc0c7754564135e3111dbc0240a4663c9a16e Mon Sep 17 00:00:00 2001
From: Cat McGee <hello@mcgee.cat>
Date: Fri, 10 May 2024 12:05:23 +0300
Subject: [PATCH 05/11] fix sidebar

---
 docs/sidebars.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/sidebars.js b/docs/sidebars.js
index abaac1d3a56..da8abdcb232 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -363,8 +363,8 @@ const sidebars = {
               label: "Accounts and Account Contracts",
               type: "category",
               items: [
+                "developers/contracts/writing_contracts/accounts/write_accounts_contract",
                 "developers/contracts/writing_contracts/accounts/how_to_authwit",
-                "developers/contracts/writing_contracts/accounts/authwit",
               ],
             },
             {

From 4c635699289f80d17d9117dcf7242427208233d6 Mon Sep 17 00:00:00 2001
From: Cat McGee <hello@mcgee.cat>
Date: Fri, 10 May 2024 12:06:18 +0300
Subject: [PATCH 06/11] suggestions

---
 docs/docs/developers/aztecjs/guides/authwit.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/docs/developers/aztecjs/guides/authwit.md b/docs/docs/developers/aztecjs/guides/authwit.md
index 7ebe618c25d..fa5361ac826 100644
--- a/docs/docs/developers/aztecjs/guides/authwit.md
+++ b/docs/docs/developers/aztecjs/guides/authwit.md
@@ -8,7 +8,7 @@ For an introduction to authentication witnesses on Aztec, [read this explainer](
 
 ## Import libraries
 
-These are all the libraries you will need for the various ways of using authwits in Aztec.js:
+These are all the libraries you might need for using authwits in Aztec.js:
 
 ```typescript
 import {
@@ -111,7 +111,7 @@ If you created an arbitrary message, you would replace the first param struct wi
 
 #include_code set_public_authwit yarn-project/end-to-end/src/e2e_authwit.test.ts typescript
 
-# Further reading
+## Further reading
 
 - [An explainer of authentication witnesses](../../../learn/concepts/accounts/authwit.md)
 - [Authwits in Aztec.nr](../../contracts/writing_contracts/accounts/how_to_authwit.md)

From 9d78d4a6ab1e73caa983d5afb6af798f027e7b3a Mon Sep 17 00:00:00 2001
From: Cat McGee <hello@mcgee.cat>
Date: Tue, 21 May 2024 12:44:28 +0300
Subject: [PATCH 07/11] tidy up

---
 .../{common_patterns => }/authwit.md          |   0
 docs/docs/tutorials/how_to_authwit.md         | 231 ------------------
 2 files changed, 231 deletions(-)
 rename docs/docs/guides/smart_contracts/writing_contracts/{common_patterns => }/authwit.md (100%)
 delete mode 100644 docs/docs/tutorials/how_to_authwit.md

diff --git a/docs/docs/guides/smart_contracts/writing_contracts/common_patterns/authwit.md b/docs/docs/guides/smart_contracts/writing_contracts/authwit.md
similarity index 100%
rename from docs/docs/guides/smart_contracts/writing_contracts/common_patterns/authwit.md
rename to docs/docs/guides/smart_contracts/writing_contracts/authwit.md
diff --git a/docs/docs/tutorials/how_to_authwit.md b/docs/docs/tutorials/how_to_authwit.md
deleted file mode 100644
index a2480fa0220..00000000000
--- a/docs/docs/tutorials/how_to_authwit.md
+++ /dev/null
@@ -1,231 +0,0 @@
----
-title: Authentication Witness
-description: Developer Documentation to use Authentication Witness for authentication actions on Aztec.
----
-
-This page introduces the authwit library and how you can use it in your Aztec.nr smart contracts. [Skip to the usage](#usage).
-
-For a guide on using authwit in Aztec.js, [read this](../../../aztecjs/guides/authwit.md).
-
-## Prerequisite reading
-
-- [Authwit](guides/smart_contracts/writing_contracts/common_patterns/authwit.md)
-
-## Introduction
-
-Authentication Witness is a scheme for authentication actions on Aztec, so users can allow third-parties (eg protocols or other users) to execute an action on their behalf.
-
-How it works logically is explained in the [concepts](guides/smart_contracts/writing_contracts/common_patterns/authwit.md) but we will do a short recap here.
-
-An authentication witness is defined for a specific action, such as allowing a Defi protocol to transfer funds on behalf of the user. An action is here something that could be explained as `A is allowed to perform X operation on behalf of B` and we define it as a hash computed as such:
-
-```rust
-authentication_witness_action = H(
-    caller: AztecAddress,
-    contract: AztecAddress,
-    selector: Field,
-    argsHash: Field
-);
-
-// Example action that authenticates:
-// defi contract to transfer 1000 tokens to itself on behalf of alice_account
-authentication_witness_action = H(
-  defi,
-  token,
-  transfer_selector,
-  H(alice_account, defi, 1000)
-);
-```
-
-Given the action, the developer can ask the `on_behalf_of` account contract if the action is authenticated or not.
-
-```mermaid
-sequenceDiagram
-    actor Alice
-    participant AC as Alice Account
-    participant Token
-    Alice->>AC: Defi.deposit(Token, 1000);
-    activate AC
-    AC->>Defi: deposit(Token, 1000);
-    activate Defi
-    Defi->>Token: transfer(Alice, Defi, 1000);
-    activate Token
-    Token->>AC: Check if Defi may call transfer(Alice, Defi, 1000);
-    AC-->>Alice: Please give me AuthWit for DeFi<br/> calling transfer(Alice, Defi, 1000);
-    activate Alice
-    Alice-->>Alice: Produces Authentication witness
-    Alice-->>AC: AuthWit for transfer(Alice, Defi, 1000);
-    AC->>Token: AuthWit validity
-    deactivate Alice
-    Token->>Token: throw if invalid AuthWit
-    Token->>Token: transfer(Alice, Defi, 1000);
-    Token->>Defi: success
-    deactivate Token
-    Defi->>Defi: deposit(Token, 1000);
-    deactivate Defi
-    deactivate AC
-```
-
-:::info
-Note in particular that the request for a witness is done by the token contract, and the user will have to provide it to the contract before it can continue execution. Since the request is made all the way into the contract where it is to be used, we don't need to pass it along as an extra input to the functions before it which gives us a cleaner interface.
-:::
-
-As part of `AuthWit` we are assuming that the `on_behalf_of` implements the private and/or public functions:
-
-```rust
-#[aztec(private)]
-fn spend_private_authwit(inner_hash: Field) -> Field;
-
-#[aztec(public)]
-fn spend_public_authwit(inner_hash: Field) -> Field;
-```
-
-Both return the value `0xabf64ad4` (`IS_VALID` selector) for a successful authentication, and `0x00000000` for a failed authentication. You might be wondering why we are expecting the return value to be a selector instead of a boolean. This is mainly to account for a case of selector collisions where the same selector is used for different functions, and we don't want an account to mistakenly allow a different function to be called on its behalf - it is hard to return the selector by mistake, but you might have other functions returning a bool.
-
-## The `AuthWit` library.
-
-As part of [Aztec.nr](https://aztec.nr), we are providing a library that can be used to implement authentication witness for your contracts.
-
-This library also provides a basis for account implementations such that these can more easily implement authentication witness. For more on the wallets, see [writing an account contract](/tutorials/write_accounts_contract.md).
-
-For our purposes here (not building a wallet), the most important part of the library is the `auth` utility which exposes a couple of helper methods for computing the action hash, retrieving witnesses, validating them and emitting the nullifier.
-
-### General utilities
-
-The primary general utility is the `compute_call_authwit_hash` function which computes the action hash from its components. This is useful for when you need to generate a hash that is not for the current call, such as when you want to update a public approval state value that is later used for [authentication in public](#updating-approval-state-in-noir). You can view the implementation of this function [here](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/authwit/src/auth.nr).
-
-#### TypeScript utilities
-
-To make it convenient to compute the message hashes in TypeScript, the `aztec.js` package includes a `computeAuthWitMessageHash` function that you can use. Implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec.js/src/utils/authwit.ts).
-
-### Utilities for private calls
-
-For private calls where we allow execution on behalf of others, we generally want to check if the current call is authenticated by `on_behalf_of`. To easily do so, we can use the `assert_current_call_valid_authwit` which fetches information from the current context without us needing to provide much beyond the `on_behalf_of`.
-
-This function will then make a to `on_behalf_of` to execute the `spend_private_authwit` function which validates that the call is authenticated.
-The `on_behalf_of` should assert that we are indeed authenticated and then emit a nullifier when we are spending the authwit to prevent replay attacks.
-If the return value is not as expected, we throw an error.
-This is to cover the case where the `on_behalf_of` might implemented some function with the same selector as the `spend_private_authwit` that could be used to authenticate unintentionally.
-
-#### Example
-
-#include_code assert_current_call_valid_authwit /noir-projects/noir-contracts/contracts/token_contract/src/main.nr rust
-
-### Utilities for public calls
-
-Very similar to the above, we have variations that work in the public domain. These functions are wrapped to give a similar flow for both cases, but behind the scenes the logic of the account contracts is slightly different since they cannot use the oracle as they are not in the private domain.
-
-#### Example
-
-#include_code assert_current_call_valid_authwit_public /noir-projects/noir-contracts/contracts/token_contract/src/main.nr rust
-
-## Usage
-
-Ok, enough talking, how do we use this?
-
-### Importing it
-
-To add it to your project, add the `authwit` library to your `Nargo.toml` file.
-
-```toml
-[dependencies]
-aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="noir-projects/aztec-nr/aztec" }
-authwit = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="noir-projects/aztec-nr/authwit"}
-```
-
-Then you will be able to import it into your contracts as follows.
-
-#include_code import_authwit /noir-projects/noir-contracts/contracts/token_contract/src/main.nr rust
-
-### Private Functions
-
-#### Checking if the current call is authenticated
-
-Based on the diagram earlier on this page let's take a look at how we can implement the `transfer` function such that it checks if the tokens are to be transferred `from` the caller or needs to be authenticated with an authentication witness.
-
-#include_code transfer /noir-projects/noir-contracts/contracts/token_contract/src/main.nr rust
-
-The first thing we see in the snippet above, is that if `from` is not the call we are calling the `assert_current_call_valid_authwit` function from [earlier](#private-functions). If the call is not throwing, we are all good and can continue with the transfer.
-
-In the snippet we are constraining the `else` case such that only `nonce = 0` is supported. This is not strictly necessary, but because I can't stand dangling useless values. By making it constrained, we can limit what people guess it does, I hope.
-
-#### Authenticating an action in TypeScript
-
-Cool, so we have a function that checks if the current call is authenticated, but how do we actually authenticate it? Well, assuming that we use a wallet that is following the spec, we import `computeAuthWitMessageHash` from `aztec.js` to help us compute the hash, and then we simply `addAuthWitness` to the wallet. Behind the scenes this will make the witness available to the oracle.
-
-#include_code authwit_transfer_example /yarn-project/end-to-end/src/e2e_token_contract/transfer_private.test.ts typescript
-
-Learn more about authwits in Aztec.js by [following this guide](../../../aztecjs/guides/authwit.md).
-
-### Public Functions
-
-With private functions covered, how can we use this in a public function? Well, the answer is that we simply change one name of a function and then we are good to go :eyes: (almost).
-
-#### Checking if the current call is authenticated
-
-#include_code transfer_public /noir-projects/noir-contracts/contracts/token_contract/src/main.nr rust
-
-#### Authenticating an action in TypeScript
-
-Authenticating an action in the public domain is quite similar to the private domain, with the difference that we are executing a function on the account contract to add the witness, if you recall, this is because we don't have access to the oracle in the public domain.
-
-In the snippet below, this is done as a separate contract call, but can also be done as part of a batch as mentioned in the [Accounts concepts](guides/smart_contracts/writing_contracts/common_patterns/authwit.md#what-about-public).
-
-#include_code authwit_public_transfer_example /yarn-project/end-to-end/src/e2e_token_contract/transfer_public.test.ts typescript
-
-#### Updating approval state in Noir
-
-We have cases where we need a non-wallet contract to approve an action to be executed by another contract. One of the cases could be when making more complex defi where funds are passed along. When doing so, we need the intermediate contracts to support approving of actions on their behalf.
-
-To support this, we must implement the `spend_public_authwit` function as seen in the snippet below.
-
-#include_code authwit_uniswap_get /noir-projects/noir-contracts/contracts/uniswap_contract/src/main.nr rust
-
-It also needs a way to update those storage values. Since we want the updates to be trustless, we can compute the action based on the function inputs, and then have the contract compute the key at which it must add a `true` to approve the action.
-
-An example of this would be our Uniswap example which performs a cross chain swap on L1. In here, we both do private and public auth witnesses, where the public is set by the uniswap L2 contract itself. In the below snippet, you can see that we compute the action hash, and then update an `approved_action` mapping with the hash as key and `true` as value. When we then call the `token_bridge` to execute afterwards, it reads this value, burns the tokens, and consumes the authentication.
-
-#include_code authwit_uniswap_set /noir-projects/noir-contracts/contracts/uniswap_contract/src/main.nr rust
-
-Outlining more of the `swap` flow: this simplified diagram shows how it will look for contracts that are not wallets but also need to support authentication witnesses.
-
-```mermaid
-sequenceDiagram
-    actor A as Alice
-    participant AC as Alice Account
-    participant CC as Crosschain Swap
-    participant TB as Token Bridge
-    participant T as Token
-
-    A->>AC: Swap 1000 token A to B on Uniswap L1
-    activate AC;
-    AC->>CC: Swap 1000 token A to B
-    activate CC;
-    CC->>T: unshield 1000 tokens from Alice Account to CCS
-    activate T;
-    T->>AC: Have you approved this??
-    AC-->>A: Please give me an AuthWit
-    A-->>AC: Here is AuthWit
-    AC-->>AC: Validate AuthWit
-    AC->>T: Yes
-    deactivate T;
-    CC-->>CC: Setting flag to true
-    CC->>TB: Exit 1000 tokens to CCS
-    activate TB;
-    TB->>T: Burn 1000 tokens from CCS
-    activate T;
-    T->>CC: Have you approved this?
-    CC->>T: Yes
-    T-->>T: Burn
-    Token->>Defi: success
-    deactivate T;
-    TB-->>TB: Emit L2->L1 message
-    deactivate TB;
-    CC-->>CC: Emit L2->L1 message
-    deactivate CC;
-    deactivate AC;
-```
-
-:::info **TODO**
-Add a link to the blog-posts.
-:::

From 0c96b816f6a2a8bb20ac1c18d50f716cb17ce5c2 Mon Sep 17 00:00:00 2001
From: Cat McGee <hello@mcgee.cat>
Date: Tue, 21 May 2024 12:52:24 +0300
Subject: [PATCH 08/11] link fixes

---
 docs/docs/guides/js_apps/authwit.md                  | 12 ++++++------
 .../smart_contracts/writing_contracts/authwit.md     | 10 +++++-----
 .../smart_contract_reference/dependencies.md         |  2 +-
 3 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/docs/guides/js_apps/authwit.md b/docs/docs/guides/js_apps/authwit.md
index fa5361ac826..61de1b23d0c 100644
--- a/docs/docs/guides/js_apps/authwit.md
+++ b/docs/docs/guides/js_apps/authwit.md
@@ -2,9 +2,9 @@
 title: How to use authentication witnesses (authwit)
 ---
 
-This page assumes you have authwit set up correctly in your contract. To learn how to do that, [go here](../../contracts/writing_contracts/accounts/how_to_authwit.md).
+This page assumes you have authwit set up correctly in your contract. To learn how to do that, [go here](../smart_contracts/writing_contracts/authwit.md).
 
-For an introduction to authentication witnesses on Aztec, [read this explainer](../../../learn/concepts/accounts/authwit.md).
+For an introduction to authentication witnesses on Aztec, [read this explainer](../../aztec/concepts/accounts/authwit.md).
 
 ## Import libraries
 
@@ -72,7 +72,7 @@ These are slightly different interfaces depending on whether your contract is ch
 
 ### Private
 
-This is expected to be used alongside [private authwits in Aztec.nr contract](../../contracts/writing_contracts/accounts/how_to_authwit.md#private-functions).
+This is expected to be used alongside [private authwits in Aztec.nr contract](../smart_contracts/writing_contracts/authwit.md#private-functions).
 
 Create a private authwit like this:
 
@@ -94,7 +94,7 @@ Then add it to the wallet of the authwit receiver (the caller of the transaction
 
 ### Public
 
-This is expected to be used alongside [public authwits in Aztec.nr contract](../../contracts/writing_contracts/accounts/how_to_authwit.md#public-functions).
+This is expected to be used alongside [public authwits in Aztec.nr contract](../smart_contracts/writing_contracts/authwit.md#public-functions).
 
 Set a public authwit like this:
 
@@ -113,5 +113,5 @@ If you created an arbitrary message, you would replace the first param struct wi
 
 ## Further reading
 
-- [An explainer of authentication witnesses](../../../learn/concepts/accounts/authwit.md)
-- [Authwits in Aztec.nr](../../contracts/writing_contracts/accounts/how_to_authwit.md)
+- [An explainer of authentication witnesses](../../aztec/concepts/accounts/authwit.md)
+- [Authwits in Aztec.nr](../smart_contracts/writing_contracts/authwit.md)
diff --git a/docs/docs/guides/smart_contracts/writing_contracts/authwit.md b/docs/docs/guides/smart_contracts/writing_contracts/authwit.md
index a2480fa0220..b262b65c25d 100644
--- a/docs/docs/guides/smart_contracts/writing_contracts/authwit.md
+++ b/docs/docs/guides/smart_contracts/writing_contracts/authwit.md
@@ -5,17 +5,17 @@ description: Developer Documentation to use Authentication Witness for authentic
 
 This page introduces the authwit library and how you can use it in your Aztec.nr smart contracts. [Skip to the usage](#usage).
 
-For a guide on using authwit in Aztec.js, [read this](../../../aztecjs/guides/authwit.md).
+For a guide on using authwit in Aztec.js, [read this](../../js_apps/authwit.md).
 
 ## Prerequisite reading
 
-- [Authwit](guides/smart_contracts/writing_contracts/common_patterns/authwit.md)
+- [Authwit](../../../aztec/concepts/accounts/authwit.md)
 
 ## Introduction
 
 Authentication Witness is a scheme for authentication actions on Aztec, so users can allow third-parties (eg protocols or other users) to execute an action on their behalf.
 
-How it works logically is explained in the [concepts](guides/smart_contracts/writing_contracts/common_patterns/authwit.md) but we will do a short recap here.
+How it works logically is explained in the [concepts](../../../aztec/concepts/accounts/authwit.md) but we will do a short recap here.
 
 An authentication witness is defined for a specific action, such as allowing a Defi protocol to transfer funds on behalf of the user. An action is here something that could be explained as `A is allowed to perform X operation on behalf of B` and we define it as a hash computed as such:
 
@@ -155,7 +155,7 @@ Cool, so we have a function that checks if the current call is authenticated, bu
 
 #include_code authwit_transfer_example /yarn-project/end-to-end/src/e2e_token_contract/transfer_private.test.ts typescript
 
-Learn more about authwits in Aztec.js by [following this guide](../../../aztecjs/guides/authwit.md).
+Learn more about authwits in Aztec.js by [following this guide](../../js_apps/authwit.md).
 
 ### Public Functions
 
@@ -169,7 +169,7 @@ With private functions covered, how can we use this in a public function? Well,
 
 Authenticating an action in the public domain is quite similar to the private domain, with the difference that we are executing a function on the account contract to add the witness, if you recall, this is because we don't have access to the oracle in the public domain.
 
-In the snippet below, this is done as a separate contract call, but can also be done as part of a batch as mentioned in the [Accounts concepts](guides/smart_contracts/writing_contracts/common_patterns/authwit.md#what-about-public).
+In the snippet below, this is done as a separate contract call, but can also be done as part of a batch as mentioned in the [Accounts concepts](../../../aztec/concepts/accounts/authwit.md#what-about-public).
 
 #include_code authwit_public_transfer_example /yarn-project/end-to-end/src/e2e_token_contract/transfer_public.test.ts typescript
 
diff --git a/docs/docs/reference/smart_contract_reference/dependencies.md b/docs/docs/reference/smart_contract_reference/dependencies.md
index 39ca07ee85c..b1864969740 100644
--- a/docs/docs/reference/smart_contract_reference/dependencies.md
+++ b/docs/docs/reference/smart_contract_reference/dependencies.md
@@ -19,7 +19,7 @@ This is the core Aztec library that is required for every Aztec.nr smart contrac
 authwit = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="noir-projects/aztec-nr/authwit"}
 ```
 
-This allows you to use authentication witnesses in your contract. Find more about its usage [here](guides/smart_contracts/writing_contracts/common_patterns/authwit.md).
+This allows you to use authentication witnesses in your contract. Find more about its usage [here](../../guides/smart_contracts/writing_contracts/authwit.md).
 
 ## Address note
 

From 1b23d0c798e2a2996428d48d337f74986a5f3b48 Mon Sep 17 00:00:00 2001
From: Cat McGee <hello@mcgee.cat>
Date: Tue, 21 May 2024 12:52:37 +0300
Subject: [PATCH 09/11] link fixes

---
 docs/docs/aztec/concepts/accounts/authwit.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/docs/aztec/concepts/accounts/authwit.md b/docs/docs/aztec/concepts/accounts/authwit.md
index f4ad3ea825c..d9b1c710988 100644
--- a/docs/docs/aztec/concepts/accounts/authwit.md
+++ b/docs/docs/aztec/concepts/accounts/authwit.md
@@ -178,7 +178,7 @@ For the transfer, this could be done simply by appending a nonce to the argument
 action = H(defi, token, transfer_selector, H(alice_account, defi, 1000, nonce));
 ```
 
-Beware that the account contract will be unable to emit the nullifier since it is checked with a static call, so the calling contract must do it. This is similar to nonces in ERC20 tokens today. We provide a small library that handles this which we will see in the [developer documentation](guides/smart_contracts/writing_contracts/common_patterns/authwit.md).
+Beware that the account contract will be unable to emit the nullifier since it is checked with a static call, so the calling contract must do it. This is similar to nonces in ERC20 tokens today. We provide a small library that handles this which we will see in the [developer documentation](../../../guides/smart_contracts/writing_contracts/authwit.md).
 
 ### Differences to approval
 
@@ -192,4 +192,4 @@ We don't need to limit ourselves to the `transfer` function, we can use the same
 
 ### Next Steps
 
-Check out the [developer documentation](guides/smart_contracts/writing_contracts/common_patterns/authwit.md) to see how to implement this in your own contracts.
+Check out the [developer documentation](../../../guides/smart_contracts/writing_contracts/authwit.md) to see how to implement this in your own contracts.

From e2a66fff602c9f5e1543e04a57568063c0ecb959 Mon Sep 17 00:00:00 2001
From: Cat McGee <helloworld@mcgee.cat>
Date: Wed, 22 May 2024 01:25:54 +0900
Subject: [PATCH 10/11] Apply suggestions from code review

Co-authored-by: josh crites <critesjosh@gmail.com>
---
 docs/docs/guides/js_apps/authwit.md | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/docs/guides/js_apps/authwit.md b/docs/docs/guides/js_apps/authwit.md
index 61de1b23d0c..1e9b364b38b 100644
--- a/docs/docs/guides/js_apps/authwit.md
+++ b/docs/docs/guides/js_apps/authwit.md
@@ -24,7 +24,7 @@ You may not need all of these.
 
 :::note
 This is only required if you are using authwits in public
-:::note
+:::
 
 If you are using public authwit (ie using `assert_current_call_valid_authwit_public` in your contract), you will need to deploy the following accounts publicly:
 
@@ -41,7 +41,7 @@ You would then call this like so:
 
 ## Define the action
 
-When creating an authwit, you will need to pass the authwit givier, the authwit receiver (who will perform the action), and the action that is being authorized. The action can be a smart contract function call, or alternatively arbitrary data.
+When creating an authwit, you will need to pass the authwit giver, the authwit receiver (who will perform the action), and the action that is being authorized. The action can be a smart contract function call, or alternatively, arbitrary data.
 
 ### When the action is a function call
 
@@ -68,7 +68,11 @@ Then create the outer hash by hashing the inner hash with the authwit receiver a
 
 ## Create the authwit
 
-These are slightly different interfaces depending on whether your contract is checking the authwit in private or public. As public authwits are stored in the account contract and batched with the authwit action call, it is done with one transaction. Private execution uses oracles, so the authwit needs to be created by the authwit giver and then added to the receiver's wallet.
+There are slightly different interfaces depending on whether your contract is checking the authwit in private or public. 
+
+Public authwits are stored in the account contract and batched with the authwit action call, so a user must send a transaction to update their account contract, authorizing an action before the authorized contract's public call will succeed. 
+
+Private execution uses oracles and are executed locally by the PXE, so the authwit needs to be created by the authwit giver and then added to the authwit receiver's PXE.
 
 ### Private
 

From 8a3b2fb792bfb3d8e73d7385b41c4ebabded8551 Mon Sep 17 00:00:00 2001
From: Cat McGee <hello@mcgee.cat>
Date: Tue, 21 May 2024 19:29:38 +0300
Subject: [PATCH 11/11] typo

---
 docs/docs/guides/js_apps/authwit.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/docs/guides/js_apps/authwit.md b/docs/docs/guides/js_apps/authwit.md
index 1e9b364b38b..5eadcf0cad6 100644
--- a/docs/docs/guides/js_apps/authwit.md
+++ b/docs/docs/guides/js_apps/authwit.md
@@ -92,7 +92,7 @@ If you created an artbitrary message, you can create the authwit by replacing th
 
 #include_code compute_outer_authwit_hash yarn-project/end-to-end/src/e2e_authwit.test.ts typescript
 
-Then add it to the wallet of the authwit receiver (the caller of the transaction):
+Then add it to the wallet of the authwit receiver (the caller of the function):
 
 #include_code add_authwit yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts typescript