Skip to content

Core Package (@humanwallet/core)

HumanWallet Core@humanwallet/core

The @humanwallet/core package provides the foundational functionality for HumanWallet, including authentication, account management, and blockchain interactions using passkey-based authentication and account abstraction.

Overview

HumanWallet Core enables:

  • Passkey Authentication: Secure biometric and hardware-based authentication using WebAuthn
  • Account Abstraction: Gasless transactions with smart contract wallets
  • Session Management: Persistent authentication sessions with secure key storage
  • Ethereum Integration: Full blockchain interaction capabilities
  • TypeScript Support: Complete type safety with comprehensive TypeScript definitions

Installation

npm install @humanwallet/core

Browser Compatibility

When using HumanWallet in browser environments, you need to configure Buffer:

npm install buffer

Create a polyfills file:

// src/polyfills.ts
import { Buffer } from "buffer"
 
// Make Buffer available globally
window.Buffer = Buffer

Import it at the beginning of your main entry file:

import "./polyfills"
// ... rest of your imports

And add to your index.html <head>:

<script>
  var global = global || window
</script>

For more details, see the React Integration Guide.

Quick Start

import { createConfig, register, login, writeContract } from "@humanwallet/core"
import { sepolia } from "viem/chains"
 
// Create configuration
const config = createConfig({
  passkeyUrl: "https://passkeys.example.com/api/v3/your-project-id",
  bundlerRpc: "https://rpc.example.com/api/v3/your-project-id/chain/11155111",
  paymasterRpc: "https://rpc.example.com/api/v3/your-project-id/chain/11155111",
  chain: sepolia,
})
 
// Register a new user
const { sessionKeyAccount, kernelClient } = await register("alice", config)
 
// Execute a transaction
const hash = await writeContract(config, {
  address: "0x...",
  abi: contractAbi,
  functionName: "transfer",
  args: ["0x...", BigInt(1000)],
})

Core Functions

The core package is organized into several categories of functionality:

Configuration

  • createConfig() - Initialize HumanWallet configuration

Authentication

  • register() - Create new passkey-based accounts
  • login() - Authenticate existing users
  • reconnect() - Restore previous sessions
  • disconnect() - End sessions and clear data
  • hasAccount() - Check if user has existing account

Contract Interactions

  • writeContract() - Execute contract transactions
  • writeContracts() - Execute multiple transactions in batch
  • readContract() - Read contract state
  • signTypedData() - Sign structured data

Transaction Management

  • waitForTransaction() - Wait for transaction confirmation
  • waitForUserOperation() - Wait for user operation completion

Architecture

HumanWallet Core is built on several key technologies:

  • WebAuthn: For secure, passwordless authentication using passkeys
  • Account Abstraction: Smart contract wallets that enable gasless transactions
  • Account Abstraction Infrastructure: Bundler and paymaster services for AA transactions
  • Viem: Low-level Ethereum interactions and type safety
  • Session Keys: Temporary keys for seamless user experience

Error Handling

All core functions can throw errors that should be handled appropriately:

try {
  const result = await login("username", config)
  // Handle success
} catch (error) {
  if (error.message.includes("User rejected")) {
    // Handle user rejection
  } else if (error.message.includes("not found")) {
    // Handle account not found
  } else {
    // Handle other errors
  }
}

Next Steps