Merge pull request #14 from AztecProtocol/ek/feat/add-account-contract-and-custom-note

feat: add password account contract and custom note contract

Author: sklppy88

account-contract/.gitignore

@@ -0,0 +1 @@
+node_modules

account-contract/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

account-contract/Nargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "custom_account"
+authors = [""]
+compiler_version = ">=1.0.0"
+type = "contract"
+
+[dependencies]
+aztec = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "v3.0.0-devnet.4", directory = "noir-projects/aztec-nr/aztec" }
+poseidon = { tag = "v0.1.1", git = "https://github.com/noir-lang/poseidon" }

account-contract/README.md

@@ -0,0 +1,213 @@
+# Password Account Contract
+
+A custom Aztec account contract that uses password-based authentication instead of traditional signature-based authentication. This example demonstrates how to implement a custom account contract with the Aztec protocol.
+
+## Overview
+
+This project implements a password-protected account contract for Aztec, showcasing how to create custom authentication logic for account contracts. Instead of using cryptographic signatures, transactions are authorized using a password hashed with Poseidon2.
+
+## Features
+
+- **Password-based Authentication**: Uses Poseidon2 hash for secure password verification
+- **Custom Account Entrypoint**: Implements a custom entrypoint interface for transaction execution
+- **Fee Payment Support**: Supports multiple fee payment methods (external, pre-existing FeeJuice, FeeJuice with claim)
+- **Authorization Witnesses**: Implements authwit verification for cross-contract calls
+- **Cancellable Transactions**: Optional transaction cancellation through nullifiers
+- **TypeScript Integration**: Complete TypeScript SDK for deployment and interaction
+
+## Contract Architecture
+
+### Core Contract (`PasswordAccount`)
+
+The main contract implements:
+
+- **constructor(password: Field)**: Initializes the account with a hashed password
+- **entrypoint(...)**: Main entrypoint for executing transactions with password authentication
+- **verify_private_authwit(...)**: Verifies authorization witnesses for cross-contract calls
+- **lookup_validity(...)**: Unconstrained function to check authwit validity
+
+### Storage
+
+```noir
+struct Storage<Context> {
+    hashed_password: PublicImmutable<Field, Context>,
+}
+```
+
+The contract stores only the Poseidon2 hash of the password in public state.
+
+### Account Actions
+
+The `AccountActions` module provides:
+
+- Transaction entrypoint logic with fee payment handling
+- Authorization witness verification
+- Support for cancellable transactions via nullifiers
+
+## TypeScript Integration
+
+### PasswordAccountContract
+
+Implements the `AccountContract` interface for easy deployment:
+
+```typescript
+const passwordAccountContract = new PasswordAccountContract(
+  new Fr(your_password)
+);
+```
+
+### PasswordAccountInterface
+
+Provides the account interface for creating transactions:
+
+```typescript
+const accountInterface = new PasswordAccountInterface(
+  authWitnessProvider,
+  address,
+  chainInfo,
+  password
+);
+```
+
+### PasswordAccountEntrypoint
+
+Handles transaction construction with custom entrypoint parameters:
+
+```typescript
+const entrypoint = new PasswordAccountEntrypoint(
+  address,
+  auth,
+  password,
+  chainId,
+  version
+);
+```
+
+## Building
+
+Compile the Noir contract:
+
+```bash
+aztec-nargo compile
+```
+
+Install TypeScript dependencies:
+
+```bash
+yarn install
+```
+
+Start the local network:
+
+```bash
+aztec start --local-network
+```
+
+Deploy the account contract to the local network:
+
+```bash
+npx tsx deploy-account-contract.ts
+```
+
+### Use the account contract as normal
+
+## Security Considerations
+
+- The password is hashed using Poseidon2 before storage
+- Password is required for every transaction (no caching)
+- Password is included in transaction data (encrypted in private state)
+- This is a demonstration contract - production use should consider additional security measures
+- Consider using signature-based accounts for most production use cases
+
+## Important Considerations
+
+When implementing custom account contracts in Aztec, be aware of these critical points:
+
+### All Execution Starts in Private
+
+**This is the most important gotcha**: In Aztec, all transaction execution begins in the private context, even if your contract only has public functions. The account contract's `entrypoint` function always executes in private first.
+
+- Your `entrypoint` function must be a `private` or `unconstrained private` function
+- Even when calling public functions on other contracts, the call originates from private execution
+- Authentication logic in the entrypoint runs in the private context
+- If you need to validate anything on-chain, you must enqueue public calls and handle them accordingly
+
+### Password/Secret Storage
+
+- **Never store passwords in plain text**: Always hash sensitive data before storage (like we do with Poseidon2)
+- The `hashed_password` is stored in `PublicImmutable` storage, meaning it's visible on-chain but cannot be changed
+- Consider whether your authentication secret should be changeable (would require mutable storage)
+
+### Entrypoint Function Signature
+
+- The entrypoint must match the expected signature for account contracts
+- It receives the payload (functions to call) and fee payment options
+
+### State Management
+
+- Private state is encrypted and only visible to those with the viewing key
+- Public state is visible to everyone on-chain
+- Choose storage types carefully: `PublicImmutable`, `PublicMutable`, `PrivateImmutable`, `PrivateMutable`, `PrivateSet`, etc.
+- Changing storage types after deployment requires a new contract deployment
+
+### Transaction Construction
+
+- Account contracts need TypeScript integration for proper transaction construction
+- You must implement the `AccountContract`, `AccountInterface`, and custom entrypoint classes
+- The entrypoint class handles encoding your authentication mechanism into the transaction payload
+- Mismatches between Noir and TypeScript implementations will cause authentication failures
+
+### Testing and Debugging
+
+- Private execution errors can be harder to debug since execution details aren't always visible
+- Test thoroughly with different fee payment methods
+- Ensure your authentication mechanism works for both direct calls and authwit flows
+
+### Gas and Fee Considerations
+
+- Account contracts are responsible for paying transaction fees
+- You must handle the fee payment method selection properly
+- Failed fee payments will cause the entire transaction to fail
+- Consider how users will fund their account contracts with Fee Asset
+
+## Dependencies
+
+### Noir Dependencies
+
+- **aztec**: v3.0.0-devnet.4
+- **poseidon**: v0.1.1
+
+### TypeScript Dependencies
+
+- **@aztec/aztec.js**: 3.0.0-devnet.4
+- **@aztec/accounts**: 3.0.0-devnet.4
+- **@aztec/stdlib**: 3.0.0-devnet.4
+- **@aztec/entrypoints**: Included in aztec.js
+
+## Project Structure
+
+```
+account-contract/
+├── Nargo.toml                        # Noir project configuration
+├── package.json                      # Node.js dependencies and scripts
+├── src/
+│   ├── main.nr                      # Main contract implementation
+│   └── account_actions.nr           # Account action handlers
+└── ts/
+    ├── deploy-account-contract.ts   # Deployment script
+    ├── password-account-entrypoint.ts         # TypeScript entrypoint implementation
+    └── password-account-contract-artifact.ts  # Contract artifact loader
+```
+
+## Learn More
+
+- [Aztec Account Contracts](https://docs.aztec.network/developers/contracts/writing_contracts/accounts)
+- [Account Abstraction in Aztec](https://docs.aztec.network/concepts/accounts/main)
+- [Aztec Documentation](https://docs.aztec.network/)
+- [Noir Language Documentation](https://noir-lang.org/)
+
+## Notes
+
+- This is an educational example demonstrating custom account contract patterns
+- For production use, consider using the standard ECDSA or Schnorr signature-based accounts
+- The password-based approach trades cryptographic security guarantees for simplicity

account-contract/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "account-contract",
+  "type": "module",
+  "scripts": {},
+  "devDependencies": {
+    "@jest/globals": "^29.0.0",
+    "@swc/core": "^1.3.0",
+    "@swc/jest": "^0.2.0",
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@aztec/accounts": "3.0.0-devnet.4",
+    "@aztec/aztec.js": "3.0.0-devnet.4",
+    "@aztec/foundation": "3.0.0-devnet.4",
+    "@aztec/noir-contracts.js": "3.0.0-devnet.4",
+    "@aztec/stdlib": "3.0.0-devnet.4",
+    "@aztec/test-wallet": "3.0.0-devnet.4",
+    "tsx": "^4.20.6"
+  }
+}

account-contract/src/account_actions.nr

@@ -0,0 +1,107 @@
+use dep::aztec::context::PrivateContext;
+
+use dep::aztec::protocol_types::{
+    constants::GENERATOR_INDEX__TX_NULLIFIER, hash::poseidon2_hash_with_separator, traits::Hash,
+};
+
+use dep::aztec::authwit::auth::{compute_authwit_message_hash, IS_VALID_SELECTOR};
+use dep::aztec::authwit::entrypoint::app::AppPayload;
+
+pub struct AccountActions<Context> {
+    context: Context,
+    is_valid_impl: fn(&mut PrivateContext, Field, Field) -> bool,
+}
+
+impl<Context> AccountActions<Context> {
+    pub fn init(context: Context, is_valid_impl: fn(&mut PrivateContext, Field, Field) -> bool) -> Self {
+        AccountActions { context, is_valid_impl }
+    }
+}
+
+// See AccountFeePaymentMethodOptions enum in Aztec.js for docs:
+// https://github.com/AztecProtocol/aztec-packages/blob/next/yarn-project/entrypoints/src/account_entrypoint.ts
+pub struct AccountFeePaymentMethodOptionsEnum {
+    pub EXTERNAL: u8,
+    pub PREEXISTING_FEE_JUICE: u8,
+    pub FEE_JUICE_WITH_CLAIM: u8,
+}
+
+pub global AccountFeePaymentMethodOptions: AccountFeePaymentMethodOptionsEnum = AccountFeePaymentMethodOptionsEnum {
+    EXTERNAL: 0,
+    PREEXISTING_FEE_JUICE: 1,
+    FEE_JUICE_WITH_CLAIM: 2,
+};
+
+/**
+ * An implementation of the Account Action struct for the private context.
+ *
+ * Implements logic to verify authorization and execute payloads.
+ */
+impl AccountActions<&mut PrivateContext> {
+
+    /// Verifies that the `app_hash` is authorized and executes the `app_payload`.
+    ///
+    /// @param app_payload The payload that contains the calls to be executed in the app phase.
+    ///
+    /// @param fee_payment_method The mechanism via which the account contract will pay for the transaction:
+    ///   - EXTERNAL (0): Signals that some other contract is in charge of paying the fee, nothing needs to be done.
+    ///   - PREEXISTING_FEE_JUICE (1): Makes the account contract publicly pay for the transaction with its own FeeJuice
+    ///                                 balance, which it must already have prior to this transaction. The contract will
+    ///                                 set itself as the fee payer and end the setup phase.
+    ///   - FEE_JUICE_WITH_CLAIM (2): Makes the account contract publicly pay for the transaction with its own FeeJuice
+    ///                                balance which is being claimed in the same transaction. The contract will set
+    ///                                itself as the fee payer but not end setup phase - this is done by the FeeJuice
+    ///                                contract after enqueuing a public call, which unlike most public calls is
+    ///                                whitelisted to be executable during setup.
+    ///
+    /// @param cancellable Controls whether to emit app_payload.tx_nonce as a nullifier, allowing a subsequent
+    /// transaction to be sent with a higher priority fee. This can be used to cancel the first transaction sent,
+    /// assuming it hasn't been mined yet.
+    ///
+    // docs:start:entrypoint
+    pub fn entrypoint(self, app_payload: AppPayload, fee_payment_method: u8, cancellable: bool, password: Field) {
+        let valid_fn = self.is_valid_impl;
+
+        assert(valid_fn(self.context, app_payload.hash(), password));
+
+        if fee_payment_method == AccountFeePaymentMethodOptions.PREEXISTING_FEE_JUICE {
+            self.context.set_as_fee_payer();
+            self.context.end_setup();
+        }
+        if fee_payment_method == AccountFeePaymentMethodOptions.FEE_JUICE_WITH_CLAIM {
+            self.context.set_as_fee_payer();
+        }
+        app_payload.execute_calls(self.context);
+
+        if cancellable {
+            let tx_nullifier = poseidon2_hash_with_separator(
+                [app_payload.tx_nonce],
+                GENERATOR_INDEX__TX_NULLIFIER,
+            );
+            self.context.push_nullifier(tx_nullifier);
+        }
+    }
+
+    /// Verifies that the `msg_sender` is authorized to consume `inner_hash` by the account.
+    ///
+    /// Computes the `message_hash` using the `msg_sender`, `chain_id`, `version` and `inner_hash`.
+    /// Then executes the `is_valid_impl` function to verify that the message is authorized.
+    ///
+    /// Will revert if the message is not authorized.
+    ///
+    /// @param inner_hash The hash of the message that the `msg_sender` is trying to consume.
+    pub fn verify_private_authwit(self, inner_hash: Field, password: Field) -> Field {
+        // The `inner_hash` is "siloed" with the `msg_sender` to ensure that only it can
+        // consume the message.
+        // This ensures that contracts cannot consume messages that are not intended for them.
+        let message_hash = compute_authwit_message_hash(
+            self.context.msg_sender().unwrap(),
+            self.context.chain_id(),
+            self.context.version(),
+            inner_hash,
+        );
+        let valid_fn = self.is_valid_impl;
+        assert(valid_fn(self.context, message_hash, password), "Message not authorized by account");
+        IS_VALID_SELECTOR
+    }
+}