Coala POC - Vault & Wallet Management System

A Next.js application for managing vaults, wallets, users, and policies for NGO administration.

Features

• ✅ Create vaults for NGO admins (by email) - Integrated with Dynamic Labs
• ✅ Create multiple wallets under a vault - Dynamic wallet creation via Dynamic Labs API
• ✅ Associate wallets with user identities (email)
• ✅ Delegate access to other users (by email) - Integrated with Dynamic Labs Delegated Access
• ✅ Create and retrieve policies (spending limits, multi-sig rules, etc.) for wallets or vaults - Integrated with Dynamic Labs Policy Engine
• ✅ Simple internal UI for all operations

Dynamic Labs Integration

This POC integrates with Dynamic Labs for:

• Vault Creation: Creates users in Dynamic Labs when creating vaults
• Wallet Creation: Creates embedded wallets using Dynamic Labs API
• Policy Management: Creates and manages policies via Dynamic Labs Policy Engine
• Delegated Access: Allows delegating wallet access to other users via Dynamic Labs Delegated Access

The integration is optional - if Dynamic Labs credentials are not configured, the app will work in local-only mode.

Getting Started

Prerequisites

• Node.js 18+ installed
• npm or yarn package manager
• Dynamic Labs account and API credentials (optional, for full integration)

Installation

1. Install dependencies:

npm install

2. Set up environment variables (optional, for Dynamic Labs integration):

cp .env.example .env

Edit .env and add your Dynamic Labs credentials:

DYNAMIC_ENVIRONMENT_ID=your_environment_id_here
DYNAMIC_AUTH_TOKEN=your_auth_token_here

Getting Dynamic Labs Credentials:

• Go to Dynamic Labs Dashboard
• Navigate to Developers → API Tokens
• Create a new API token with Policies and WaaS permissions
• Copy the token (starts with dyn_...)
• Get your Environment ID from the dashboard

Note: If you don't set up Dynamic Labs credentials, the app will still work but will only store data locally (in-memory). Vaults and wallets will be created locally without Dynamic Labs integration.

3. Run the development server:

npm run dev

4. Open http://localhost:3000 in your browser

Usage

Create a Vault

1. Enter the admin email (e.g., admin@ngo.org)
2. Enter a vault name
3. Click "Create Vault"

Create a Wallet

1. Select a vault from the dropdown
2. Enter the associated email (user identity)
3. Click "Create Wallet"

Delegate Access

1. Select a vault
2. Enter the delegate email (the user who will receive delegated access)
3. (Optional) Select a wallet to delegate access to
4. Click "Delegate Access (Local)" to store delegate email locally
5. If a wallet is selected, use "Trigger Delegation (Client-side SDK)" to trigger Dynamic Labs delegation flow
6. The delegate user will need to approve the delegation request
7. After approval, your server will receive a webhook with encrypted delegation materials

Create a Policy

1. Enter a policy name
2. Select policy type:
   • Spending Limit: Set maximum spending amount
   • Multi-Signature: Require multiple signatures for transactions
   • Time Lock: Lock funds until a specific time
   • Approval Required: Require approval for transactions
3. Select target type (Wallet or Vault)
4. Select the target wallet/vault
5. Fill in policy-specific configuration
6. Click "Create Policy"

API Endpoints

Vaults

• POST /api/vaults - Create a vault
• GET /api/vaults - Get all vaults (optional: ?adminEmail=email)
• GET /api/vaults/[id] - Get vault by ID
• POST /api/vaults/[id]/delegate - Delegate access to a vault

Wallets

• POST /api/wallets - Create a wallet
• GET /api/wallets - Get all wallets (optional: ?vaultId=id or ?email=email)

Policies

• POST /api/policies - Create a policy
• GET /api/policies - Get all policies (optional: ?targetType=wallet&targetId=id)
• GET /api/policies/[id] - Get policy by ID

Delegated Access

• POST /api/webhooks/delegation - Webhook endpoint for receiving delegation materials from Dynamic Labs
• GET /api/delegated-accesses - Get all delegated accesses (optional: ?vaultId=id, ?walletId=id, ?delegateEmail=email)

Data Storage

This POC uses in-memory storage. Data will be reset when the server restarts. For production, you would integrate with a database (PostgreSQL, MongoDB, etc.) or a blockchain service.

Project Structure

coala-poc/
├── app/
│   ├── api/           # API routes
│   ├── globals.css    # Global styles
│   ├── layout.tsx     # Root layout
│   └── page.tsx       # Main dashboard page
├── lib/
│   ├── services/
│   │   └── dynamicLabsService.ts  # Dynamic Labs API integration
│   ├── store.ts       # In-memory data store
│   └── utils.ts       # Utility functions
├── types/
│   └── index.ts       # TypeScript type definitions
└── package.json

Technologies

• Next.js 14 (App Router)
• TypeScript
• React 18
• CSS (no external UI library for simplicity)

Notes

• This is a proof of concept (POC) for internal use
• All data is stored in memory and will be lost on server restart
• With Dynamic Labs integration: Real wallets are created on Dynamic Labs platform
• Without Dynamic Labs: Wallet addresses are randomly generated (not real blockchain addresses)
• For production, integrate with a database (PostgreSQL, MongoDB, etc.) for persistent storage

Dynamic Labs Setup

For Policies API

To use the Policies feature, you need to configure the following in Dynamic Labs Dashboard:

1. Enable Policy Engine Feature:

• Go to Dynamic Labs Dashboard
• Navigate to your Environment settings
• Go to Wallets → Policies (or Settings → Features)
• Enable "Policy Engine" or "WaaS Policies" feature
• Save the changes

2. Configure API Token (for server-side use):

• Go to Developers → API Tokens
• Create a new API token with the following permissions:
  • ✅ WaaS (Wallet as a Service)
  • ✅ Policies (if available as a separate permission)
• Token should start with dyn_... (not SDK key sk_...)
• Copy and save the token securely (you won't be able to see it again)

3. Verify Environment Configuration:

• Ensure your Environment ID is correct
• Check that the environment has Policy Engine enabled
• Verify that embedded wallets are enabled (required for policies)

4. For Client-side JWT Token:

• Policy API requires JWT token from authenticated user (via SDK)
• User must be logged in with Dynamic Labs SDK
• JWT token is obtained via getAuthToken() from SDK
• Important: The JWT token must be from the user who owns the wallet, not from admin/dashboard account

5. Troubleshooting 401 "Unauthorized Dynamic User":

If you get this error, check:

• ✅ Policy Engine is enabled in dashboard
• ✅ User is logged in with correct account (the one that owns the wallet)
• ✅ JWT token is not expired (check exp field)
• ✅ JWT token has correct environment_id matching your environment
• ✅ Wallet address in policy matches a wallet owned by the authenticated user
• ✅ User has permission to create policies (may require specific user role)

6. Check Policy API Access:

• Test by calling the Policy API endpoint directly
• Use the JWT token from getAuthToken() in Authorization header
• If you get 401/403 errors, verify all above configurations

Policy Types Supported

• Spending Limit: Set maximum spending amount per transaction
• Multi-Signature: Require multiple signatures for transactions
• Time Lock: Lock funds until a specific time
• Approval Required: Require approval before transactions

See Dynamic Labs Policies Documentation for more details.

For Delegated Access

To use the Delegated Access feature, you need to configure the following:

1. Enable Delegated Access in Dashboard:

• Go to Dynamic Labs Dashboard
• Navigate to Developers → Delegated Access (or Settings → Features)
• Enable "Delegated Access" feature
• Save the changes

2. Register Webhook Endpoint:

• In the Dashboard, go to Webhooks section
• Add a new webhook endpoint: https://your-domain.com/api/webhooks/delegation
• Subscribe to wallet.delegation.created event
• Save the webhook configuration

3. Register RSA Public Key:

• Generate an RSA key pair (2048-bit or 4096-bit)
• Register the public key in Dynamic Labs Dashboard
• Keep the private key secure (store in environment variable DYNAMIC_DELEGATION_PRIVATE_KEY)
• Dynamic Labs will use this public key to encrypt delegation materials

4. Configure Environment Variables:

Add to your .env file:

DYNAMIC_DELEGATION_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----
DYNAMIC_WEBHOOK_SECRET=your_webhook_secret_here  # Optional, for webhook signature verification

5. Delegation Flow:

1. Wallet owner triggers delegation via client-side SDK (using DelegateAccessClient component)
2. Delegate user receives a request to approve delegation
3. After approval, Dynamic Labs sends webhook to your server
4. Server verifies webhook signature, decrypts materials, and stores securely
5. Delegated materials can be used to act on behalf of the wallet owner

6. Security Notes:

• ⚠️ Store delegated materials securely: Use envelope encryption, KMS, or at-rest encryption
• ⚠️ Never expose private key: Keep DYNAMIC_DELEGATION_PRIVATE_KEY secure
• ⚠️ Verify webhook signatures: Always verify webhook signatures before processing
• ⚠️ Use HTTPS: Webhook endpoint must use HTTPS in production

See Dynamic Labs Delegated Access Documentation for more details.