feat(docs): Authwit how tos (#6220)

Please read [contributing guidelines](CONTRIBUTING.md) and remove this
line.

---------

Co-authored-by: Josh Crites <[email protected]>

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.

docs/docs/guides/js_apps/authwit.md

@@ -0,0 +1,121 @@
+---
+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](../smart_contracts/writing_contracts/authwit.md).
+
+For an introduction to authentication witnesses on Aztec, [read this explainer](../../aztec/concepts/accounts/authwit.md).
+
+## Import libraries
+
+These are all the libraries you might need for 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
+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 (authwit giver)
+2. The account that does the action (authwit receiver)
+
+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
+
+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
+
+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]`
+
+### Arbitrary message
+
+You can hash your own authwit message by creating an inner hash with the data, like this:
+
+#include_code compute_inner_authwit_hash yarn-project/end-to-end/src/e2e_authwit.test.ts typescript
+
+Then create the outer hash by hashing the inner hash with the authwit receiver address, chainId, and version:
+
+#include_code compute_outer_authwit_hash yarn-project/end-to-end/src/e2e_authwit.test.ts typescript
+
+## Create the authwit
+
+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
+
+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:
+
+#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)
+
+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 function):
+
+#include_code add_authwit yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts typescript
+
+### Public
+
+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:
+
+#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](../../aztec/concepts/accounts/authwit.md)
+- [Authwits in Aztec.nr](../smart_contracts/writing_contracts/authwit.md)

docs/docs/guides/smart_contracts/writing_contracts/common_patterns/authwit.md → docs/docs/guides/smart_contracts/writing_contracts/authwit.md

@@ -3,15 +3,19 @@ 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](../../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:
 
@@ -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
 
@@ -151,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](../../js_apps/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).
@@ -163,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
 

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
 

yarn-project/end-to-end/src/e2e_authwit.test.ts

@@ -18,7 +18,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:end:public_deploy_accounts
 
     const nodeInfo = await wallets[0].getNodeInfo();
     chainId = new Fr(nodeInfo.chainId);
@@ -28,10 +30,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]
@@ -186,14 +193,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,

yarn-project/end-to-end/src/e2e_blacklist_token_contract/transfer_private.test.ts

@@ -54,9 +54,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

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');
 

yarn-project/end-to-end/src/fixtures/utils.ts

@@ -443,6 +443,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)));
@@ -452,6 +454,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.