feat(docs): Authwit how tos

docs/docs/developers/aztecjs/guides/authwit.md

@@ -0,0 +1,110 @@
+---
+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
+
+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
+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 (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 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 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
+
+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
+
+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
+
+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
+
+### 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)

docs/docs/developers/contracts/resources/common_patterns/authwit.md → 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
 
@@ -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](../../../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).

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",
           ],
         },
         {

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);
@@ -27,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]
@@ -185,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,

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

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

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