Noble Restricted Authz Example

This TypeScript project demonstrates how to use CosmJS to set up and execute restricted authz (authorization) grants on the Noble testnet, with specific allow lists controlling where funds can be sent.

Quick Start

# Clone and setup
git clone <repository-url>
cd noble-authz
npm install

# Generate accounts
npm run generate

# Fund accounts from faucet, then run demo
npm run start

Features

• Generate Noble testnet accounts with private keys
• Create restricted authz grants with allow lists - only specified addresses can receive funds
• Execute authorized transactions within the granted permissions
• Automatic denial of unauthorized recipients

Prerequisites

• Node.js 16+
• npm or yarn

Setup

1. Clone the repository:

git clone <repository-url>
cd noble-authz

2. Install dependencies:

npm install

3. Generate new accounts:

npm run generate

This creates a .env.local file with three new accounts (granter, grantee, and test recipient).

4. Fund your accounts with testnet USDC:

   • Visit https://faucet.testnet.noble.strange.love/
   • Copy the addresses from the generation output
   • Request testnet tokens for both accounts

5. Check account balances:

npm run check-balance

Usage

Once your accounts have testnet USDC:

npm run start

This will:

1. Grant the grantee permission to spend up to 1 USDC from the granter's account only to the grantee's address
2. Test 1: Successfully send 0.3 USDC from the granter to the grantee (allowed recipient)
3. Test 2: Attempt to send to a random third party address - this will fail with "unauthorized"
4. Test 3: Attempt to send back to the granter - this will also fail with "unauthorized"

The demo shows both successful and failed transactions to demonstrate how the allow list works.

Scripts

• npm run generate - Generate new accounts and save to .env.local
• npm run start - Run the restricted authz example
• npm run check-balance - Check account balances
• npm run build - Compile TypeScript to JavaScript
• npm run typecheck - Check TypeScript types
• npm run dev - Run with file watching

Project Structure

src/
├── noble-authz-example.ts  # Main authz example
├── generate-accounts.ts    # Account generation script
└── check-balances.ts      # Balance checking utility

Environment Variables

The .env.local file contains:

• GRANTER_PRIVATE_KEY - Hex-encoded private key for the granter
• GRANTEE_PRIVATE_KEY - Hex-encoded private key for the grantee
• GRANTER_ADDRESS - Noble address of the granter
• GRANTEE_ADDRESS - Noble address of the grantee
• NOBLE_RPC - RPC endpoint for Noble testnet

Security

⚠️ Never commit your .env.local file or share your private keys! The .env.local file is already covered by .gitignore.

How Restricted Authz Works

1. Grant with Allow List: The granter creates an authorization that restricts where funds can be sent
2. Execute: The grantee can only send funds to addresses in the allow list
3. Automatic Denial: Any attempt to send to unauthorized addresses fails immediately
4. Expiration: Grants expire quickly (default 5 minutes) for security

Key Security Features

• Allow List: Only pre-approved addresses can receive funds
• Spend Limit: Maximum amount that can be spent through the authorization
• Short Expiration: Grants expire in minutes, not days, for better security
• Use Cases:
  • Recurring payments to specific vendors
  • Child allowances restricted to approved merchants
  • Corporate spending controls
  • Automated payments with recipient restrictions

Troubleshooting

• If RPC connection fails, the check-balances script tries multiple endpoints
• Ensure accounts have sufficient USDC for gas fees (transactions cost ~0.25 USDC in fees)
• Check that private keys are 64 character hex strings without '0x' prefix

Resources

• Noble Documentation
• CosmJS Documentation
• Cosmos Authz Module