docs: adding some authwit docs #2711

LHerskind · 2023-10-05T15:36:27Z

Writing docs for AuthWit as part of #2710.

I'm not fully satisfied with the naming for messages/actions etc. Don't really like the message hash because we already have multiple types of these things but right not it is a little inconsistent.

Checklist:

Remove the checklist to signal you've completed it. Enable auto-merge if the PR is ready to merge.

If the pull request requires a cryptography review (e.g. cryptographic algorithm implementations) I have added the 'crypto' tag.
I have reviewed my diff in github, line by line and removed unexpected formatting changes, testing logs, or commented-out code.
Every change is related to the PR description.
I have linked this pull request to relevant issues (if any exist).

catmcgee · 2023-10-06T14:46:01Z

@LHerskind hope you don't mind I pushed some grammar fixes

catmcgee · 2023-10-06T14:46:51Z

docs/docs/dev_docs/contracts/resources/common_patterns/authwit.md

+    deactivate AC;
+```
+
+:::info **TODO**


do we have the blogs now?

Its the ones @rahul-kothari have been working on, so partially.

spalladino

Looks good to me! I added a bunch of suggestions, but none that prevents from merging. I do think there's a pass needed for reviewing styling issues, but maybe devrel can own it?

docs/docs/concepts/foundation/accounts/authwit.md

spalladino · 2023-10-06T14:54:25Z

docs/docs/concepts/foundation/accounts/authwit.md

+
+In the EVM world, this is often accomplished by having the user `approve` the protocol to transfer funds from their account, and then calling a `deposit` function on it afterwards.
+
+```mermaid


Whoa, fancy! Does our docusaurus support this..?

Yep, it is quite nice for making it easier to update the docs without leaving the markdown files.

spalladino · 2023-10-06T14:56:16Z

docs/docs/concepts/foundation/accounts/authwit.md

+
+To limit the annoyance for return-users, some front-ends will use the `approve` function with an infinite amount, which means that the user will only has to sign the `approve` transaction once, and every future `deposit` with then use some of that "allowance" to transfer funds from the user's account to the protocol's account.
+
+This can lead to a series of issues though, eg:


I'd argue that another issue is that you cannot know for sure how your approval will be used by the protocol. You just give them carte blanche to manage your funds, and hope that the protocol is properly designed so they are not lost.

Here you kinda still know how your funds are getting used, just where the transfer is going, but it could be lost or send it into the abyss afterwards still 🤷.

spalladino · 2023-10-06T14:57:58Z

docs/docs/concepts/foundation/accounts/authwit.md

+
+If you recall from [State model](./../state_model.md), private state is generally only known by its owner and those they have shared it with. Because it relies on secrets, private state might be "owned" by a contract, but it needs someone with knowledge of these secrets to actually spend it. You might see where this is going.
+
+If we were to implement the `approve` with an allowance in private, you might know the allowance, but unless you also know about the individual notes that make up the user's balances, it would be of no use to you! It is private after all.


I'd clarify that "know about the individual notes that make up the user's balances" requires access to the user's decryption keys, to make it even more obvious

docs/docs/concepts/foundation/accounts/authwit.md

spalladino · 2023-10-06T15:16:02Z

docs/docs/dev_docs/contracts/resources/common_patterns/authwit.md

+
+// Example action that authenticates:
+// defi to transfer 1000 tokens to itself on behalf of alice_account
+action = H(


Let's use the same name authentication_witness_action as above

spalladino · 2023-10-06T15:17:41Z

docs/docs/dev_docs/contracts/resources/common_patterns/authwit.md

+
+Given the action, the developer can ask the `on_behalf_of` account contract if the action is authenticated or not.
+
+```mermaid


I'd personally remove the diagram from here to avoid duplication

spalladino · 2023-10-06T15:19:05Z

docs/docs/dev_docs/contracts/resources/common_patterns/authwit.md

+
+### General utilities
+
+The primary general utility is the `compute_authwit_message_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).


This is useful for when you need to generate a hash that is not for the current call

I get the sense that generating a hash for the current call is the most common use case, right? If so, I'd introduce it first, and then present this utility later.

If the action is mainly one-step yes, but when doing more complex where the contract also need to approve we want to use it.

spalladino · 2023-10-06T16:12:57Z

docs/docs/dev_docs/contracts/resources/common_patterns/authwit.md

+
+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.


😆, but it feels odd for the "I" to suddenly pop up in the middle of the doc

docs/docs/dev_docs/contracts/resources/common_patterns/authwit.md

docs/docs/concepts/foundation/accounts/authwit.md

rahul-kothari · 2023-10-09T09:57:59Z

docs/docs/concepts/foundation/accounts/authwit.md

+
+To outline an example as mentioned earlier, let's say that we have a token that implements `AuthWit` such that transfer funds from A to B is valid if A is doing the transfer, or there is a witness that authenticates the caller to transfer funds from A's account. While this specifies the spending rules, one must also know of the notes to use them for anything. This means that a witness in itself is only half the information.
+
+Creating the authentication action for the transfer of funds to the Defi contract would look like this:


Suggested change

Creating the authentication action for the transfer of funds to the Defi contract would look like this:

Creating the authentication action for the transfer of funds to a Defi contract would look like this:

the was used as it was that specific defi and not just any

rahul-kothari · 2023-10-09T10:40:11Z

docs/docs/concepts/foundation/accounts/authwit.md

+
+The main difference is that we are not setting up an allowance, but allowing the execution of a specific action. We decided on this option as the default since it is more explicit and the user can agree exactly what they are signing.
+
+Also, most uses of the approvals are for contracts where the following interactions are called by the user themselves, so it is not a big issue that they are not as easily "transferrable" as the `permit`s.


Another difference - in the public case, all "approvals" are stored in your contract as opposed to being spread out across all contracts

rahul-kothari · 2023-10-09T10:43:56Z

docs/docs/concepts/foundation/accounts/authwit.md

+
+### Other use-cases
+
+We don't need to limit ourselves to the `transfer` function, we can use the same scheme for any function that requires authentication. For example, for authenticating to burn or shield assets or to vote in a governance contract or perform an operation on a lending protocol.


+1 need next steps that link to the common patterns and the dev docs on how to actually use authwit.

Also in both the pages (dev docs, common patterns), lets link this too

rahul-kothari · 2023-10-09T10:57:00Z

docs/docs/dev_docs/contracts/resources/common_patterns/authwit.md

+
+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 [foundational concepts](./../../../../concepts/foundation/accounts/authwit.md) but we will do a short recap here.


add prerequisite reading at the top in a separate section?

docs/docs/dev_docs/contracts/resources/common_patterns/authwit.md

rahul-kothari · 2023-10-09T11:07:01Z

docs/docs/concepts/foundation/accounts/authwit.md

+
+All of these issues have been discussed in the community for a while, and there are many proposals to solve them. However, none of them have been widely adopted - ERC20 is so commonly used and changing a standard is hard.
+
+## In Aztec


do we not want to talk about how partial addresses are used to generate this witness?

Can you elaborate on what you mean here? What would you want to be added?

Co-authored-by: Santiago Palladino <santiago@aztecprotocol.com> Co-authored-by: Rahul Kothari <rahul.kothari.201@gmail.com>

AztecBot · 2023-10-11T10:25:35Z

Benchmark results

All benchmarks are run on txs on the Benchmarking contract on the repository. Each tx consists of a batch call to create_note and increment_balance, which guarantees that each tx has a private call, a nested private call, a public call, and a nested public call, as well as an emitted private note, an unencrypted log, and public storage read and write.

L2 block published to L1

Each column represents the number of txs on an L2 block published to L1.

Metric	8 txs	32 txs	128 txs
l1_rollup_calldata_size_in_bytes	45444	179588	716132
l1_rollup_calldata_gas	223020	868268	3449552
l1_rollup_execution_gas	842107	3595376	22204921
l2_block_processing_time_in_ms	1049	3998	15755
note_successful_decrypting_time_in_ms	322	1017	3755
note_trial_decrypting_time_in_ms	24	108	137
l2_block_building_time_in_ms	9183	36618	152605
l2_block_rollup_simulation_time_in_ms	6852	27343	107876
l2_block_public_tx_process_time_in_ms	2290	9140	44251

L2 chain processing

Each column represents the number of blocks on the L2 chain where each block has 16 txs.

Metric	10 blocks	20 blocks	30 blocks
node_history_sync_time_in_ms	31524	77086	137450
note_history_successful_decrypting_time_in_ms	4745	13061	20093
note_history_trial_decrypting_time_in_ms	146	240	268
node_database_size_in_bytes	1193949	1902581	2755204
pxe_database_size_in_bytes	54187	108338	162578

Circuits stats

Stats on running time and I/O sizes collected for every circuit run across all benchmarks.

Circuit	circuit_simulation_time_in_ms	circuit_input_size_in_bytes	circuit_output_size_in_bytes
private-kernel-init	56.158742331288344	56577	14745
private-kernel-ordering	30.506134969325153	20137	8089
base-rollup	870	631604	810
root-rollup	38.09756097560975	4072	1097
private-kernel-inner	53.286265432098766	72288	14745
public-kernel-private-input	51.80941358024691	37359	14745
public-kernel-non-first-iteration	31.15354938271605	37401	14745
merge-rollup	1.0116279069767442	2592	873

LHerskind requested review from spalladino, rahul-kothari and catmcgee October 5, 2023 15:37

catmcgee reviewed Oct 6, 2023

View reviewed changes

spalladino approved these changes Oct 6, 2023

View reviewed changes

rahul-kothari reviewed Oct 9, 2023

View reviewed changes

rahul-kothari approved these changes Oct 9, 2023

View reviewed changes

LHerskind force-pushed the lh/authwit-docs branch from 2c82481 to 5db7cb6 Compare October 10, 2023 09:29

catmcgee approved these changes Oct 10, 2023

View reviewed changes

LHerskind and others added 4 commits October 11, 2023 10:35

docs: adding some authwit docs

4bed35e

put description in text + grammar fixes

eb69877

Apply suggestions from code review

fc72af0

Co-authored-by: Santiago Palladino <santiago@aztecprotocol.com> Co-authored-by: Rahul Kothari <rahul.kothari.201@gmail.com>

chore: address comments

2130583

LHerskind force-pushed the lh/authwit-docs branch from 5db7cb6 to 2130583 Compare October 11, 2023 09:35

LHerskind enabled auto-merge (squash) October 11, 2023 09:35

LHerskind merged commit afc23f4 into master Oct 11, 2023
78 of 80 checks passed

LHerskind deleted the lh/authwit-docs branch October 11, 2023 10:01

AztecBot mentioned this pull request Oct 11, 2023

chore(master): Release 0.8.10 #2766

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: adding some authwit docs #2711

docs: adding some authwit docs #2711

LHerskind commented Oct 5, 2023 •

edited

Loading

catmcgee commented Oct 6, 2023

catmcgee Oct 6, 2023

LHerskind Oct 9, 2023

spalladino left a comment

spalladino Oct 6, 2023

LHerskind Oct 7, 2023

spalladino Oct 6, 2023

LHerskind Oct 9, 2023

spalladino Oct 6, 2023

spalladino Oct 6, 2023

spalladino Oct 6, 2023

spalladino Oct 6, 2023

LHerskind Oct 9, 2023

spalladino Oct 6, 2023

rahul-kothari Oct 9, 2023

LHerskind Oct 9, 2023

rahul-kothari Oct 9, 2023

rahul-kothari Oct 9, 2023

rahul-kothari Oct 9, 2023

rahul-kothari Oct 9, 2023

LHerskind Oct 9, 2023

AztecBot commented Oct 11, 2023


		In the EVM world, this is often accomplished by having the user `approve` the protocol to transfer funds from their account, and then calling a `deposit` function on it afterwards.

		```mermaid


		To limit the annoyance for return-users, some front-ends will use the `approve` function with an infinite amount, which means that the user will only has to sign the `approve` transaction once, and every future `deposit` with then use some of that "allowance" to transfer funds from the user's account to the protocol's account.

		This can lead to a series of issues though, eg:


		If you recall from [State model](./../state_model.md), private state is generally only known by its owner and those they have shared it with. Because it relies on secrets, private state might be "owned" by a contract, but it needs someone with knowledge of these secrets to actually spend it. You might see where this is going.

		If we were to implement the `approve` with an allowance in private, you might know the allowance, but unless you also know about the individual notes that make up the user's balances, it would be of no use to you! It is private after all.


		Given the action, the developer can ask the `on_behalf_of` account contract if the action is authenticated or not.

		```mermaid


		### General utilities

		The primary general utility is the `compute_authwit_message_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).


		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.


		To outline an example as mentioned earlier, let's say that we have a token that implements `AuthWit` such that transfer funds from A to B is valid if A is doing the transfer, or there is a witness that authenticates the caller to transfer funds from A's account. While this specifies the spending rules, one must also know of the notes to use them for anything. This means that a witness in itself is only half the information.

		Creating the authentication action for the transfer of funds to the Defi contract would look like this:


		The main difference is that we are not setting up an allowance, but allowing the execution of a specific action. We decided on this option as the default since it is more explicit and the user can agree exactly what they are signing.

		Also, most uses of the approvals are for contracts where the following interactions are called by the user themselves, so it is not a big issue that they are not as easily "transferrable" as the `permit`s.


		### Other use-cases

		We don't need to limit ourselves to the `transfer` function, we can use the same scheme for any function that requires authentication. For example, for authenticating to burn or shield assets or to vote in a governance contract or perform an operation on a lending protocol.


		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 [foundational concepts](./../../../../concepts/foundation/accounts/authwit.md) but we will do a short recap here.


		All of these issues have been discussed in the community for a while, and there are many proposals to solve them. However, none of them have been widely adopted - ERC20 is so commonly used and changing a standard is hard.

		## In Aztec

docs: adding some authwit docs #2711

docs: adding some authwit docs #2711

Conversation

LHerskind commented Oct 5, 2023 • edited Loading

Checklist:

catmcgee commented Oct 6, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

spalladino left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AztecBot commented Oct 11, 2023

Benchmark results

L2 block published to L1

L2 chain processing

Circuits stats

LHerskind commented Oct 5, 2023 •

edited

Loading