User Creation Guide

How to Create a User in O Blockchain Database

There are two ways to create a user in the O Blockchain system:

1. User Verification Transaction (Recommended for production) - Creates a blockchain transaction
2. Direct User Registration (For testing) - Registers directly via RPC

Method 1: User Verification Transaction (Recommended)

This method creates a blockchain transaction that is stored and synced across all nodes.

RPC Command

./build/bin/bitcoin-cli -regtest submituserverificationtx \
  "user_id" \
  "identity_provider" \
  "country_code" \
  "birth_currency" \
  "verification_data" \
  "provider_signature" \
  [expiration] \
  [o_pubkey]

Parameters

• user_id: Unique user ID from identity provider (e.g., "0x1a2b3c...")
• identity_provider: Provider name ("brightid", "kyc_usa", "worldcoin", etc.)
• country_code: ISO 3166-1 alpha-3 country code ("USA", "FRA", "MEX")
• birth_currency: Birth currency for UBI ("OUSD", "OEUR", "OMXN") - IMMUTABLE!
• verification_data: JSON string with verification data (e.g., '{"score":95}')
• provider_signature: Provider's signature in hex (64 bytes, e.g., "0xabcd...")
• expiration: (Optional) Expiration timestamp, 0 = never expires
• o_pubkey: (Optional) O Blockchain pubkey, defaults to wallet's pubkey

Example

# Create a test user with BrightID
./build/bin/bitcoin-cli -regtest submituserverificationtx \
  "test_user_123" \
  "brightid" \
  "USA" \
  "OUSD" \
  '{"score":95,"verified":true}' \
  "0x0000000000000000000000000000000000000000000000000000000000000000"

# Mine a block to include the transaction
./build/bin/bitcoin-cli -regtest generatetoaddress 1 $(./build/bin/bitcoin-cli -regtest getnewaddress)

Verify User Created

After mining a block, you can verify the user was created:

# Check user statistics
./build/bin/bitcoin-cli -regtest getuserstatistics

# Check if user exists (if query RPC is available)
# The user will be stored in the brightid_users database

Method 2: Direct User Registration (For Testing)

This method registers a user directly via the registeruser RPC command.

RPC Command

./build/bin/bitcoin-cli -regtest registeruser \
  "public_key_hex" \
  "government_id" \
  "birth_currency" \
  "country_code" \
  "identity_proof"

Parameters

• public_key_hex: User's public key in hex format (e.g., "02f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9")
• government_id: Government ID number (will be hashed)
• birth_currency: Birth currency code ("USD", "EUR", etc.)
• country_code: ISO country code ("US", "FR", etc.)
• identity_proof: Identity proof hash/string

Example

# Get a public key from your wallet
PUBKEY=$(./build/bin/bitcoin-cli -regtest getaddressinfo $(./build/bin/bitcoin-cli -regtest getnewaddress) | jq -r '.pubkey')

# Register user
./build/bin/bitcoin-cli -regtest registeruser \
  "$PUBKEY" \
  "123456789" \
  "USD" \
  "US" \
  "identity_proof_hash_abc123"

Testing Workflow

Here's a complete workflow for testing:

Step 1: Setup Environment

# Start node if not running
./build/bin/bitcoind -regtest -daemon

# Wait for node to be ready
./build/bin/bitcoin-cli -regtest getblockchaininfo

# Generate blocks to maturity
./build/bin/bitcoin-cli -regtest generatetoaddress 101 $(./build/bin/bitcoin-cli -regtest getnewaddress)

Step 2: Create a User

# Create user verification transaction
USER_ID="test_user_$(date +%s)"
TX_RESULT=$(./build/bin/bitcoin-cli -regtest submituserverificationtx \
  "$USER_ID" \
  "brightid" \
  "USA" \
  "OUSD" \
  '{"score":95,"verified":true}' \
  "0x$(head -c 64 < /dev/urandom | xxd -p -c 256)")

echo "Transaction ID: $(echo $TX_RESULT | jq -r '.txid')"

Step 3: Mine Block to Confirm

# Mine a block to include the transaction
./build/bin/bitcoin-cli -regtest generatetoaddress 1 $(./build/bin/bitcoin-cli -regtest getnewaddress)

Step 4: Verify User Creation

# Check user statistics
./build/bin/bitcoin-cli -regtest getuserstatistics

# Check logs for confirmation
tail -n 50 ~/.bitcoin/regtest/debug.log | grep -i "user verification"

Step 5: Check for Invites (After User Creation)

Once users are created, invites may become available:

# Generate blocks (invites created every 10 blocks)
./build/bin/bitcoin-cli -regtest generatetoaddress 10 $(./build/bin/bitcoin-cli -regtest getnewaddress)

# Check for active invites
./build/bin/bitcoin-cli -regtest getactiveinvites

Database Storage

Users are stored in the BrightID database (brightid_users/):

• Location: ~/.bitcoin/regtest/brightid_users/ (LevelDB)
• Key Format: provider:user_id (e.g., "brightid:test_user_123")
• Data: User verification data, pubkey, country, birth currency, etc.

Notes

1. Birth Currency is IMMUTABLE: Once set, the birth currency cannot be changed

2. Provider Signature: For testing, you can use dummy signatures (64 bytes of zeros or random data)

3. Identity Provider: Common providers include:

   • brightid - BrightID social graph verification
   • kyc_usa - KYC verification for USA
   • worldcoin - Worldcoin verification
   • manual - Manual verification (for testing)

4. Verification Data: Should be a JSON string with provider-specific data:

   {
     "score": 95,
     "verified": true,
     "trust_level": "high"
   }

Troubleshooting

"Wallet context not found" error

Note: The submituserverificationtx command currently has a known issue where it cannot find the wallet context. This appears to be a bug in the implementation that needs to be fixed.

Workarounds:

1. Check if the command implementation is complete - There are TODO comments in the code for getting the pubkey from wallet
2. Use alternative methods - For testing, you may need to create users directly via the consensus layer or through other RPC commands if available
3. Check the code - The command is in src/rpc/o_blockchain_tx_rpc.cpp and may need fixes to properly access wallet context

Make sure you have a wallet loaded:

./build/bin/bitcoin-cli -regtest loadwallet "test_wallet"
# or
./build/bin/bitcoin-cli -regtest createwallet "test_wallet"

Command not found errors

If registeruser is not found, it may not be registered in the RPC table. Check src/rpc/register.h to see if RegisterOBlockchainRPCCommands is commented out or not being called.

User not appearing after transaction

1. Make sure you mined a block after creating the transaction
2. Check debug logs: tail -f ~/.bitcoin/regtest/debug.log | grep -i user
3. Verify transaction was included: ./build/bin/bitcoin-cli -regtest getrawmempool

No invites after creating users

• Invites are created automatically every 10 blocks
• Users need to be verified and active
• Check measurement readiness: ./build/bin/bitcoin-cli -regtest getreadinessstatistics

Quick Test Script

Save this as create_test_user.sh:

#!/bin/bash
set -e

CLI="./build/bin/bitcoin-cli -regtest"
WALLET_NAME="test_wallet"

# Load wallet
$CLI loadwallet "$WALLET_NAME" >/dev/null 2>&1 || $CLI createwallet "$WALLET_NAME" >/dev/null 2>&1

# Generate blocks if needed
BLOCKS=$($CLI getblockchaininfo | jq -r '.blocks')
if [ "$BLOCKS" -lt 101 ]; then
    echo "Generating blocks to maturity..."
    $CLI generatetoaddress $((101 - BLOCKS)) $($CLI getnewaddress) >/dev/null
fi

# Create user
USER_ID="test_user_$(date +%s)"
echo "Creating user: $USER_ID"

TX_RESULT=$($CLI submituserverificationtx \
  "$USER_ID" \
  "brightid" \
  "USA" \
  "OUSD" \
  '{"score":95,"verified":true}' \
  "0x$(openssl rand -hex 32)")

TXID=$(echo "$TX_RESULT" | jq -r '.txid')
echo "Transaction created: $TXID"

# Mine block
echo "Mining block to confirm..."
$CLI generatetoaddress 1 $($CLI getnewaddress) >/dev/null

echo "✅ User created successfully!"
echo "Check logs: tail -f ~/.bitcoin/regtest/debug.log | grep -i 'user verification'"

Make it executable and run:

chmod +x create_test_user.sh
./create_test_user.sh