Skip to content

Commit dfb2ffa

Browse files
critesjoshcritesjosh
committed
add readme, consistency
1 parent 62ef80a commit dfb2ffa

File tree

4 files changed

+6401
-8714
lines changed

4 files changed

+6401
-8714
lines changed

‎account-contract/Nargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,5 @@ compiler_version = ">=1.0.0"
55
type = "contract"
66

77
[dependencies]
8-
aztec = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "v3.0.0-nightly.20251107", directory = "noir-projects/aztec-nr/aztec" }
8+
aztec = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "v3.0.0-devnet.4", directory = "noir-projects/aztec-nr/aztec" }
99
poseidon = { tag = "v0.1.1", git = "https://github.com/noir-lang/poseidon" }

‎account-contract/README.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Password Account Contract
2+
3+
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.
4+
5+
## Overview
6+
7+
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.
8+
9+
## Features
10+
11+
- **Password-based Authentication**: Uses Poseidon2 hash for secure password verification
12+
- **Custom Account Entrypoint**: Implements a custom entrypoint interface for transaction execution
13+
- **Fee Payment Support**: Supports multiple fee payment methods (external, pre-existing FeeJuice, FeeJuice with claim)
14+
- **Authorization Witnesses**: Implements authwit verification for cross-contract calls
15+
- **Cancellable Transactions**: Optional transaction cancellation through nullifiers
16+
- **TypeScript Integration**: Complete TypeScript SDK for deployment and interaction
17+
18+
## Contract Architecture
19+
20+
### Core Contract (`PasswordAccount`)
21+
22+
The main contract implements:
23+
24+
- **constructor(password: Field)**: Initializes the account with a hashed password
25+
- **entrypoint(...)**: Main entrypoint for executing transactions with password authentication
26+
- **verify_private_authwit(...)**: Verifies authorization witnesses for cross-contract calls
27+
- **lookup_validity(...)**: Unconstrained function to check authwit validity
28+
29+
### Storage
30+
31+
```noir
32+
struct Storage<Context> {
33+
hashed_password: PublicImmutable<Field, Context>,
34+
}
35+
```
36+
37+
The contract stores only the Poseidon2 hash of the password in public state.
38+
39+
### Account Actions
40+
41+
The `AccountActions` module provides:
42+
43+
- Transaction entrypoint logic with fee payment handling
44+
- Authorization witness verification
45+
- Support for cancellable transactions via nullifiers
46+
47+
## TypeScript Integration
48+
49+
### PasswordAccountContract
50+
51+
Implements the `AccountContract` interface for easy deployment:
52+
53+
```typescript
54+
const passwordAccountContract = new PasswordAccountContract(
55+
new Fr(your_password)
56+
);
57+
```
58+
59+
### PasswordAccountInterface
60+
61+
Provides the account interface for creating transactions:
62+
63+
```typescript
64+
const accountInterface = new PasswordAccountInterface(
65+
authWitnessProvider,
66+
address,
67+
chainInfo,
68+
password
69+
);
70+
```
71+
72+
### PasswordAccountEntrypoint
73+
74+
Handles transaction construction with custom entrypoint parameters:
75+
76+
```typescript
77+
const entrypoint = new PasswordAccountEntrypoint(
78+
address,
79+
auth,
80+
password,
81+
chainId,
82+
version
83+
);
84+
```
85+
86+
## Building
87+
88+
Compile the Noir contract:
89+
90+
```bash
91+
aztec-nargo compile
92+
```
93+
94+
Install TypeScript dependencies:
95+
96+
```bash
97+
yarn install
98+
```
99+
100+
## Usage
101+
102+
### 1. Deploy the Account Contract
103+
104+
```typescript
105+
import { PasswordAccountContract } from "./ts/password-account-entrypoint";
106+
import { Fr } from "@aztec/foundation/fields";
107+
108+
// Create account contract with password
109+
const password = new Fr(123456789);
110+
const accountContract = new PasswordAccountContract(password);
111+
112+
// Get artifact and initialization args
113+
const artifact = await accountContract.getContractArtifact();
114+
const { constructorName, constructorArgs } =
115+
await accountContract.getInitializationFunctionAndArgs();
116+
117+
// Deploy using DeployMethod
118+
// See ts/deploy-account-contract.ts for full example
119+
```
120+
121+
### 2. Create Transactions
122+
123+
The account contract authenticates transactions by verifying the password hash:
124+
125+
```typescript
126+
// Transactions automatically include the password in the entrypoint call
127+
// The password is hashed with Poseidon2 and compared to stored hash
128+
```
129+
130+
### 3. Authorization Witnesses
131+
132+
For cross-contract calls requiring authorization:
133+
134+
```typescript
135+
// The account can authorize actions for other contracts
136+
// Password is used to verify the authorization
137+
```
138+
139+
## Fee Payment Methods
140+
141+
The contract supports three fee payment options:
142+
143+
1. **EXTERNAL (0)**: Another contract pays the fee
144+
2. **PREEXISTING_FEE_JUICE (1)**: Account pays with existing FeeJuice balance
145+
3. **FEE_JUICE_WITH_CLAIM (2)**: Account pays with FeeJuice claimed in same transaction
146+
147+
## Security Considerations
148+
149+
- The password is hashed using Poseidon2 before storage
150+
- Password is required for every transaction (no caching)
151+
- Password is included in transaction data (encrypted in private state)
152+
- This is a demonstration contract - production use should consider additional security measures
153+
- Consider using signature-based accounts for most production use cases
154+
155+
## Dependencies
156+
157+
### Noir Dependencies
158+
159+
- **aztec**: v3.0.0-devnet.4
160+
- **poseidon**: v0.1.1
161+
162+
### TypeScript Dependencies
163+
164+
- **@aztec/aztec.js**: 3.0.0-devnet.4
165+
- **@aztec/accounts**: 3.0.0-devnet.4
166+
- **@aztec/stdlib**: 3.0.0-devnet.4
167+
- **@aztec/entrypoints**: Included in aztec.js
168+
169+
## Project Structure
170+
171+
```
172+
account-contract/
173+
├── Nargo.toml # Noir project configuration
174+
├── package.json # Node.js dependencies and scripts
175+
├── src/
176+
│ ├── main.nr # Main contract implementation
177+
│ └── account_actions.nr # Account action handlers
178+
└── ts/
179+
├── deploy-account-contract.ts # Deployment script
180+
├── password-account-entrypoint.ts # TypeScript entrypoint implementation
181+
└── password-account-contract-artifact.ts # Contract artifact loader
182+
```
183+
184+
## Learn More
185+
186+
- [Aztec Account Contracts](https://docs.aztec.network/developers/contracts/writing_contracts/accounts)
187+
- [Account Abstraction in Aztec](https://docs.aztec.network/concepts/accounts/main)
188+
- [Aztec Documentation](https://docs.aztec.network/)
189+
- [Noir Language Documentation](https://noir-lang.org/)
190+
191+
## Notes
192+
193+
- This is an educational example demonstrating custom account contract patterns
194+
- For production use, consider using the standard ECDSA or Schnorr signature-based accounts
195+
- The password-based approach trades cryptographic security guarantees for simplicity

‎account-contract/package.json‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,7 @@
11
{
22
"name": "account-contract",
33
"type": "module",
4-
"scripts": {
5-
"clean": "rm -rf data.json",
6-
"ccc": "cd sample-contract && aztec-nargo compile && aztec-postprocess-contract && aztec codegen target -o ../contract/artifacts",
7-
"data": "tsx scripts/generate_data.ts",
8-
"create-note": "tsx scripts/create_note.ts",
9-
"test": "npm run clean && jest",
10-
"test:watch": "jest --watch"
11-
},
4+
"scripts": {},
125
"devDependencies": {
136
"@jest/globals": "^29.0.0",
147
"@swc/core": "^1.3.0",

0 commit comments

Comments
 (0)