Smart accounts for social login

Use dashboard and view stats here.

Table of Contents

• Overview
• Addresses
• How it works
• Version Management
• Project Structure
• Getting Started

Overview

This is a simplified version of the Account Abstraction pattern for the vechain blockchain. Concepts like UserOperation, Bundler, and EntryPoint are not implemented, only the basic account abstraction pattern is implemented, in order to provide a light-weight solution for social login and for developers.

Currently the smart accounts created through this factory are used to enable social login on VeChain.

Addresses

Mainnet

0xC06Ad8573022e2BE416CA89DA47E8c592971679A

Testnet

0x713b908Bcf77f3E00EFEf328E50b657a1A23AeaF

How it works

There are 2 contracts that work together to enable social login and account abstraction:

• SimpleAccount: A smart contract wallet owned by the user that can:

  • Execute transactions directly from the owner or through signed messages
  • Handle both single and batch transactions
  • Be upgraded by the owner
  • Transfer ownership to another address
  • Use time-based validity windows for transactions
  • Prevent replay attacks using nonces for batch transactions

• SimpleAccountFactory: Factory contract that creates and manages SimpleAccount contracts:

  • Creates new accounts with deterministic addresses using CREATE2
  • Get the account address of a smart account without deploying it
  • Supports multiple accounts per owner through custom salts
  • Manages different versions of the SimpleAccount implementation

How to use the smart accounts

1. Account Creation: When a user wants to create a smart account, they interact with the SimpleAccountFactory, which creates a new SimpleAccount instance with the user as the owner.

2. Transaction Execution: The SimpleAccount can execute transactions in several ways:

   • Direct execution by the owner
   • Batch execution of multiple transactions
   • Signature-based execution (useful for social login)
   • Batch signature-based execution with replay protection (useful for social login + multiclause)

3. Nonce Management: For batch transactions with authorization (executeBatchWithAuthorization), a nonce is required to protect users against replay attacks:

   • The nonce should be generated when requesting the signature
   • Best practice is to use Date.now() as the nonce value
   • Each nonce can only be used once per account
   • Without proper nonce management, malicious actors could replay the same signed transaction multiple times
   • Nonces are only used and required for executeBatchWithAuthorization method

4. Social Login Integration: This system enables social login by creating deterministic account addresses for each user and allowing transactions to be signed off-chain and executed by anyone. This creates a seamless experience where users can interact with dApps using their social credentials.

Version Management

The system has evolved through multiple versions to improve functionality and security:

• SimpleAccount:

  • V1: Basic account functionality with single transaction execution
  • V2: Skipped for misconfiguration during upgrade
  • V3: Introduced batch transactions with nonce-based replay protection, ownership transfer and version tracking

• SimpleAccountFactory:

  • V1: Basic account creation and management
  • V2: Added support for multiple accounts per owner using custom salts
  • V3: Support for V3 SimpleAccounts, enhanced version management and backward compatibility with legacy accounts

The factory maintains compatibility with all account versions, ensuring a smooth experience across different dApps and versions.

Project Structure

Frontend (apps/frontend) 🌐

There's a frontend (powered by React/Vite) that shows useful information about how the smart accounts are being used. It also offers a convenient way to interact with and view statistics for the deployed contracts.

Contracts (packages/contracts) 📜

The smart contracts in this project are managed using Hardhat, specifically configured to work with the VeChain Thor network. This setup allows you to compile, test, and deploy the contracts seamlessly to VeChain testnet or mainnet environments.

Getting Started

Clone the repository and install dependencies with ease:

yarn # Run this at the root level of the project

Place your .env files in the root folder, you can copy .env.example

Run the whole project (frontend + contracts):

The following commands will check if the contracts are alrady deployed on the selected network, if not it will deploy them, then start the frontend web app.

  yarn dev:mainnet

  yarn dev:testnet

Deploy contracts:

  yarn contracts:deploy:testnet

Run tests

  yarn contracts:test

Run tests with coverage

  yarn contracts:test:coverage

Open the coverage report in the packages/contracts/coverage/index.html file in your browser to see the test coverage.

Generate documentation

  yarn contracts:generate-docs

Verify contracts (Optional)

Optionally verify your smart contracts on Sourcify. This allows 3rd to view and independently verify all of the following:

• Source code
• Metadata
• Contract ABI
• Contract Bytecode
• Contract transaction ID

After deploying SimpleStorage, the console will print the address of the deployed contract. You can verify the contract on sourcify.eth:

yarn contracts:verify:mainnet 0x98307db87474fc30d6e022e2b31f384b134c2c2a

Note: Hardhat throws an error when verifying contracts on VeChain networks. This error can be ignored as the contract is still verified on Sourcify. See an example here

Documentation

Detailed documentation for the smart contracts is available:

• SimpleAccount Documentation - Complete API reference and implementation details for the SimpleAccount contract
• SimpleAccountFactory Documentation - Complete API reference and implementation details for the SimpleAccountFactory contract

Social Login with Smart Accounts

Implement the Social Login with Smart Accounts in your app with VeChain Kit.

Documentation and examples are available in the VeChain Kit Docs.