Overview

The Universal Gateway Transaction Protocol (UGTP) gives every user a single blockchain address that works across every supported network. Built on EIP-7702 set-code delegation, UGTP transforms an ordinary EOA into a full smart account — same address, same key, six mainnets.

The protocol is organized as a monorepo with six packages:

Quickstart

Clone the monorepo and install dependencies with pnpm:

# Install dependencies
pnpm install

# Build core packages (required before other packages)
pnpm --filter @ugtp/core build
pnpm --filter @ugtp/sdk build

# Start the API server
pnpm --filter ugtp-api dev

# Start the portal
pnpm --filter ugtp-portal dev

Server-side (WaaS)

For institutional integrations, install the WaaS SDK directly:

pnpm add @ugtp/waas @ugtp/core @ugtp/sdk

Authentication

UGTP supports two authentication paths:

Wallet Connect (Portal)

End users connect via MetaMask, WalletConnect, or any injected wallet. The connected address becomes their Universal Crypto Account. No additional signup or key generation is required.

Service Account (WaaS)

Server-side integrations authenticate through the external signer (e.g., Dfns). Credentials are loaded from environment variables and never exposed to the client:

# .env.local (server-side only — never commit)
DFNS_AUTH_TOKEN=              # service-account token
DFNS_ORG_ID=
DFNS_CRED_ID=
DFNS_PRIVATE_KEY_PATH=./.secrets/dfns-private.pem
DFNS_BASE_URL=https://api.dfns.io

Account Model

A Universal Crypto Account (UCA) is one persistent user identity across public, smart, and private execution. Your EOA address becomes your UCA — the same address on Ethereum, Base, Arbitrum, Optimism, Polygon, and Avalanche.

EOA = Smart = Private

On EIP-7702 chains, delegation upgrades the EOA to a full smart account — batch execution, session keys, sponsored gas — while preserving the original address. There is no separate smart-account contract to deploy; the delegation itself confers smart-account capabilities.

On Avalanche (the coordination chain), the account operates in standard EOA mode until ACP-209 enables 7702 support. Privacy features on Avalanche use a separate escrow pattern that does not require delegation.

Delegation Lifecycle

// 1. Build the authorization
import { DelegationHelper } from '@ugtp/sdk';
const auth = DelegationHelper.buildAuthorization(chainId, nonce);

// 2. Sign with the user's wallet
const signed = await wallet.signAuthorization(auth);

// 3. Submit to the API for on-chain execution
await fetch('/api/delegate', {
  method: 'POST',
  body: JSON.stringify({ authorization: signed }),
});

Operation Rails

UGTP selects the optimal execution path for each transaction based on chain capabilities and delegation status:

import { ExecutionOptimizer } from '@ugtp/sdk';

const optimizer = new ExecutionOptimizer();
const mode = optimizer.selectMode(chainId, isDelegated);
// Returns: '7702' | '4337' | 'eoa'

Avalanche C-Chain

Avalanche C-Chain (43114) is the coordination chain — the source of truth for account state, privacy registration, and cross-chain routing.

Privacy Layer

Avalanche hosts the privacy escrow contracts that enable confidential transfers using Encrypted ERC (eERC) tokens. Users register for privacy on the coordination chain, then shield and unshield assets through the escrow contract.

EIP-7702 Status

Avalanche C-Chain does not yet support EIP-7702 set-code transactions. The community proposal ACP-209 is in progress. Until then, accounts on Avalanche operate as standard EOAs. Once ACP-209 is activated, delegation will unlock smart-account features on the coordination chain as well.

WaaS SDK

The @ugtp/waas package is a server-side SDK for creating and operating UGTP wallets with institutional key management.

Initialize

import { createUgtpWaas, JsonFileWalletStore } from '@ugtp/waas';
import { dfnsFromEnv } from '@ugtp/waas/signer/dfns';

const waas = createUgtpWaas({
  signer: dfnsFromEnv(),
  store: new JsonFileWalletStore('./data/waas.json'),
  allowMainnet: true,
});

Create a Wallet

// Dfns MPC key → same address on all 6 chains
const wallet = await waas.wallets.create({ name: 'treasury-1' });

Plan & Execute

// Plan a batch transaction
const plan = await waas.batch.plan({
  walletId: wallet.id,
  recipient: '0x...',
  target: { chainId: 1, symbol: 'ETH', amount: '500000000000000' },
  sources: [{ chainId: 1, symbol: 'ETH' }],
});

// Execute (signs with Dfns, broadcasts, tracks stages)
const flow = await waas.batch.execute(plan.planId);

// Poll status
const status = await waas.batch.status(flow.flowId);

Full API

Error Codes

Safety Rails

• ALLOW_MAINNET_TRANSACTIONS — must be explicitly true; the executor rejects every mainnet step otherwise.
• MAX_NATIVE_VALUE_WEI — per-step native value cap (default 0.002 ETH). Any step exceeding it is rejected before signing.
• Simulation — eth_call / estimateGas before every broadcast. Reverts are caught before the transaction reaches the mempool.
• Pending policy status — when Dfns policies require multi-party approval, the executor surfaces Pending as a stage status rather than failing.

External Signers

UGTP's Wallet as a Service architecture decouples key management from protocol logic through the SignerProvider interface. Any institutional key management system that can sign EVM transactions can be plugged in as an external signer.

SignerProvider Interface

Every external signer implements this interface. Four EVM signing kinds are supported: Transaction, Eip7702, Eip712, and Eip191.

interface SignerProvider {
  id: string;
  createSigner(params: CreateSignerParams): Promise<SignerRecord>;
  signTransaction(signerId: string, tx: Record<string, unknown>): Promise<string>;
  signAuthorization(signerId: string, auth: Record<string, unknown>): Promise<SignedAuthorization>;
  signTypedData(signerId: string, data: Record<string, unknown>): Promise<string>;
  signMessage(signerId: string, message: string): Promise<string>;
  healthCheck(): Promise<{ ok: boolean; latencyMs: number }>;
}

The toProviderAccount() bridge wraps any SignerProvider as a viem Account so the full @ugtp/sdk works unchanged.

Dfns — Production Signer

Dfns is the production external signer for UGTP. It provides MPC-based key management with hardware-backed key shares, programmable policy engine, and multi-party approval workflows.

Architecture

• MPC key generation — private key shares are distributed across Dfns infrastructure. No single party (including Dfns) ever holds the complete key.
• Deterministic addressing — one MPC key derives the same Ethereum address on all six UGTP chains. The wallet is portable without bridging.
• Policy engine — configurable rules (spend limits, allowlists, time locks) enforced at the signing layer. Policies requiring multi-party approval surface as Pending status in the WaaS executor.
• Service-account auth — the customer's institutional signer holds the key. Authentication uses asymmetric credentials (RSA key pair). The private key never leaves the server.

Configuration

# .env.local (server-side only)
DFNS_AUTH_TOKEN=sa_...           # service-account token
DFNS_ORG_ID=or_...              # organization ID
DFNS_CRED_ID=cr_...             # credential ID
DFNS_PRIVATE_KEY_PATH=./.secrets/dfns-private.pem
DFNS_BASE_URL=https://api.dfns.io
DFNS_DEFAULT_NETWORK=Ethereum

Usage

import { dfnsFromEnv } from '@ugtp/waas/signer/dfns';

// Initialize from environment variables
const signer = dfnsFromEnv();

// Or configure explicitly
import { DfnsSignerProvider } from '@ugtp/waas/signer/dfns';

const signer = new DfnsSignerProvider({
  authToken: process.env.DFNS_AUTH_TOKEN,
  orgId: process.env.DFNS_ORG_ID,
  credId: process.env.DFNS_CRED_ID,
  privateKeyPath: process.env.DFNS_PRIVATE_KEY_PATH,
  baseUrl: process.env.DFNS_BASE_URL,
});

Supported Operations

Utila

Cobo

Adding a Custom Provider

To integrate a new key-management system, implement the SignerProvider interface in a single adapter file and register it:

import { createUgtpWaas } from '@ugtp/waas';
import { MyCustomProvider } from './my-provider';

const waas = createUgtpWaas({
  signer: new MyCustomProvider({ /* config */ }),
  store: new JsonFileWalletStore('./data/waas.json'),
});

Transactions

UGTP transactions are expressed as intents — declarative descriptions of what the user wants to accomplish. The SDK resolves intents into executable steps.

Intent Builder

import { IntentBuilder } from '@ugtp/sdk';

// Native transfer
const intent = IntentBuilder.transfer({
  from: address,
  to: recipient,
  chainId: 1,
  asset: 'ETH',
  amount: '1000000000000000000', // 1 ETH in wei
});

// ERC-20 transfer
const tokenIntent = IntentBuilder.transfer({
  from: address,
  to: recipient,
  chainId: 43114,
  asset: 'USDt',
  amount: '2000000', // 2 USDt (6 decimals)
});

Batch Execution

On delegated accounts, multiple operations can be batched into a single transaction. The batch planner quotes fees, selects source chains, and produces an ordered list of steps:

const plan = await waas.batch.plan({
  walletId: wallet.id,
  recipient: '0x...',
  target: { chainId: 1, symbol: 'ETH', amount: '500000000000000' },
  sources: [
    { chainId: 1, symbol: 'ETH' },
    { chainId: 8453, symbol: 'ETH' },  // fallback to Base
  ],
});

// Each step: { chainId, type, to, value, data, gasEstimate }
console.log(plan.steps);

Private Tokens

UGTP integrates with Encrypted ERC (eERC) tokens on Avalanche C-Chain for confidential transfers. Amounts and balances are encrypted on-chain; only the account holder (and authorized auditors) can decrypt them.

Privacy Lifecycle

1. Register — derive a privacy key pair from the account, register the public key on the coordination chain.
2. Shield — deposit tokens into the privacy escrow. The escrow mints an equivalent encrypted balance.
3. Transfer — send encrypted tokens to another registered account. The transfer is visible on-chain but the amount is encrypted.
4. Unshield — withdraw from the escrow back to a standard ERC-20 balance.

Swaps & Routing

Cross-chain routing selects the cheapest path to fulfill a transfer intent. When the source and destination chains differ, the router computes bridge fees, DEX swap quotes, and gas costs to find the optimal route.

The batch planner integrates routing automatically — specify multiple source chains in the sources array, and the planner picks the best combination:

const plan = await waas.batch.plan({
  walletId: wallet.id,
  recipient: '0x...',
  target: { chainId: 1, symbol: 'ETH', amount: '1000000000000000' },
  sources: [
    { chainId: 1, symbol: 'ETH' },
    { chainId: 8453, symbol: 'ETH' },
    { chainId: 42161, symbol: 'ETH' },
  ],
});
// plan.route describes the chosen path and estimated costs

Network Support

UGTP supports six production mainnets. Each chain has a specific capability profile based on EIP support and contract deployment status:

Fees & Lifecycle

UGTP applies a transparent fee model on every batch execution:

Fees are calculated fee-from-amount — deducted from the transfer value, not added on top. The recipient receives the amount minus fees.

Execution Lifecycle

A batch flow moves through these stages:

1. Plan — intent is resolved into steps with fee quotes
2. Simulate — each step is dry-run via eth_call
3. Sign — external signer signs each transaction
4. Broadcast — signed transactions are submitted to the network
5. Confirm — receipts are collected and the flow is marked complete

API Reference

The ugtp-api server exposes the following REST endpoints:

WaaS Endpoints

Deployed Contracts

Canonical contract addresses — deployed once, reused across the protocol:

Protocol Constants

Links