WalletCore API

Overview

WalletCore is a backend service built with Node.js and Express.js, designed to manage Starknet blockchain wallets. It provides a RESTful API for creating, pre-funding, and deploying Starknet accounts programmatically.

Features

• Node.js / Express: Provides a robust and scalable server for the REST API.
• starknet.js: Facilitates all interactions with the Starknet blockchain, including key generation, address calculation, and contract deployment.
• dotenv: Manages environment variables for secure configuration.
• Node Crypto: Offers built-in cryptographic functions for securing sensitive data like private keys.

Getting Started

Installation

1. Clone the repository:

   git clone https://github.com/ANAMBRA-X/WalletCore.git
   cd WalletCore

2. Install dependencies:

   npm install

3. Set up environment variables: Create a .env file in the root directory and add the variables listed below.

4. Start the server:

   # For development with live reloading
   npm run dev
   
   # For production
   npm run start

Environment Variables

Create a .env file in the project root and populate it with the following required variables:

# Server Configuration
PORT=3000

# Starknet Configuration
# The class hash of the OpenZeppelin account contract you intend to deploy
OZ_ACCOUNT_CLASS_HASH=0x05400e90f7e0ae78bd02c77cd75527280470e2c19c54e99c1233c680d070b853

# The RPC endpoint for the Starknet network (e.g., Sepolia Testnet)
RPC_NETWORK=https://starknet-sepolia.public.blastapi.io/rpc/v0_7

# Funder Account Details (Admin wallet for pre-funding new accounts)
ADMIN_ADDRESS=0x04e...
ADMIN_PRIVATE_KEY=0x01a...

# Security
# A 64-character hex string (32 bytes) for AES-256-GCM encryption
ENCRYPTION_SECRET=...

API Documentation

Base URL

The API base URL is the root path of the server (e.g., http://localhost:3000).

Endpoints

POST /createAccount

Generates a new Starknet private key, derives the corresponding public key, and pre-calculates the future contract address for an OpenZeppelin account.

Request: No request body is required.

{}

Response: Success (200 OK)

{
  "message": "Account generated successfully",
  "publicKey": "0x...",
  "contractAddress": "0x...",
  "privateKey": "0x..."
}

Errors:

• 500 Internal Server Error: {"error": "Failed to create account"} - Occurs if there is an unexpected server-side issue during key generation or address calculation.

---

POST /prefund

Transfers STRK tokens from the admin/funder wallet to a specified address. This is used to fund a new account's address before it is deployed, covering the deployment fees.

Request:

{
  "futureAddress": "0x...",
  "amount": "4"
}

Note: amount should be specified in wei (e.g., 1 STRK = 10^18 wei).

Response: Success (200 OK)

{
  "message": "STRK Prefund complete",
  "token": "STRK",
  "amount": "1000000000000000",
  "to": "0x...",
  "transactionHash": "0x..."
}

Errors:

• 400 Bad Request: {"error": "Missing required parameters: futureAddress, amount"} - One or both required fields are missing from the request body.
• 500 Internal Server Error: {"error": "Prefunding failed", "details": "..."} - The transfer transaction failed, potentially due to insufficient funds in the funder wallet or other network errors.
• 500 Internal Server Error: {"error": "Configuration error: Funder details or RPC URL missing. Check your .env file."} - ADMIN_ADDRESS, ADMIN_PRIVATE_KEY, or RPC_NETWORK is missing.
• 500 Internal Server Error: {"error": "Failed to load contract ABI required for interaction."} - The server failed to fetch the STRK token contract ABI from the network.

---

POST /deployAccount

Deploys a pre-calculated Starknet account contract to the network. The account must be funded with enough ETH for the deployment fee prior to calling this endpoint.

Request:

{
  "privateKey": "0x..."
}

Response: Success (200 OK)

{
  "message": "Account deployed successfully",
  "contractAddress": "0x...",
  "transactionHash": "0x..."
}

Errors:

• 400 Bad Request: {"error": "Missing required parameter: privateKey"} - The privateKey field is missing from the request body.
• 500 Internal Server Error: {"error": "Deploy Account failed", "details": "..."} - The deployment transaction failed. This could be due to insufficient funds, network issues, or an invalid private key.
• 500 Internal Server Error: {"error": "Configuration error: RPC URL missing. Check your .env file."} - The RPC_NETWORK environment variable is not set.