Blockchain quickstart¶
Prerequisites: a reachable PQWERAI node (local node on 127.0.0.1:8545 or an endpoint from the network
operator), Foundry 1.8.5, curl, openssl and Python 3.
Environment constraints: private testnet only; amounts are test PQAI.
mkdir pqwerai-quickstart && cd pqwerai-quickstart
# save env.sh from the Getting Started page here, then:
export PQWERAI_RPC=http://127.0.0.1:8545 # or the endpoint you were given
. ./env.sh
1. Check the network¶
Never sign anything for an endpoint that reports another chain. The PQWERAI testnet chain ID is 77240 (0x12db8).
# 1. Refuse to continue unless the endpoint is the PQWERAI testnet (chain ID 77240).
test "$(cast chain-id --rpc-url "$RPC")" = "$CHAIN_ID" || { echo "not chain $CHAIN_ID" >&2; exit 1; }
# 2. Client and protocol identity.
cast client --rpc-url "$RPC"
# 3. The same check as a raw JSON-RPC request.
curl -s -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}' "$RPC"; echo
Expected output:
2. Inspect a block¶
# Current height and the latest block header fields.
cast block-number --rpc-url "$RPC"
cast block latest --rpc-url "$RPC" --field number
cast block latest --rpc-url "$RPC" --field miner
cast block latest --rpc-url "$RPC" --field baseFeePerGas
# PQWERAI finality: the last BFT-finalized checkpoint (epochs of 32 blocks).
cast rpc g4_status --rpc-url "$RPC" | python3 -c \
'import json,sys; s=json.load(sys.stdin); print("head", s["head"], "finalized", s["finalized_height"], s["finalized_hash"])'
Expected output (numbers will differ):
4386
4386
0x94e398784fEBBB1C56DDC2E4bc10D6Edc4924F70
7
head 4386 finalized 4352 0xa2ea9dbbf755eada81a6c7a6c5cf8b14632b2d810dc90ca34524dfb3a86f85b5
The base fee is in wei. It started at 1 gwei in genesis and falls toward a few wei while blocks are mostly empty
(EIP-1559). finalized is the last BFT-finalized checkpoint, always a multiple of 32.
3. Create an account¶
The key is generated locally and stored as an encrypted Web3 Secret Storage (V3) keystore — the same format the
PQWERAI Windows Wallet and pqwerai-cli import.
# Create an encrypted keystore for a NEW test account. The key never leaves this machine.
umask 077
mkdir -p keystore
openssl rand -hex 24 > keystore/dev.password # random password, readable only by you
cast wallet new keystore dev --unsafe-password "$(cat keystore/dev.password)" > /dev/null
ME=$(cast wallet address --keystore keystore/dev --password-file keystore/dev.password)
echo "address: $ME"
cast balance "$ME" --ether --rpc-url "$RPC"
Created new encrypted keystore file: …/keystore/dev
Address: 0x85dbc49268BFB4C8EBad1ac24f0E1084074ddC8b
address: 0x85dbc49268BFB4C8EBad1ac24f0E1084074ddC8b
0.000000000000000000
Interactive password instead of a file
--unsafe-password puts the password in the process list for a moment. On a shared machine use
cast wallet new keystore dev -p and type the password, then store it in a mode-0600 file for the later steps.
Fund the account. There is no public faucet yet (faucet design). Ask the network operator,
or on your own disposable network send test PQAI from a genesis allocation:
cast send <your address> --value 20ether --keystore <funded keystore> --rpc-url "$RPC".
4. Send a test transaction¶
# Send 0.01 test PQAI (EIP-1559; cast fills nonce, gas and fees from the node).
ME=$(cast wallet address --keystore "$KEYSTORE" --password-file "$PASSWORD_FILE")
TO=0x000000000000000000000000000000000000dEaD
TX=$(cast send "$TO" --value 0.01ether --async \
--keystore "$KEYSTORE" --password-file "$PASSWORD_FILE" --rpc-url "$RPC")
echo "tx: $TX"
cast receipt "$TX" status --rpc-url "$RPC" # waits for inclusion; prints true on success
BLOCK=$(cast receipt "$TX" blockNumber --rpc-url "$RPC")
echo "included in block $BLOCK"
cast balance "$ME" --ether --rpc-url "$RPC"
tx: 0x3d4ab2e584d4b8260dceaff66ff4f3a99b7f310e2764dcf062f0fc7cfe39cf69
true
included in block 4389
19.989999999999832000
5. Wait for finality¶
A receipt means the transaction is in the current canonical chain. On PQWERAI a block becomes irreversible when a BFT checkpoint at or above it is finalized by more than 2/3 of the Smartnode stake (details).
# Inclusion is not finality. Wait until the block is at or below the BFT-finalized checkpoint
# and still canonical (same hash). Typical delay: one to two 32-block epochs.
BLOCK=$(cast receipt "$TX" blockNumber --rpc-url "$RPC")
HASH=$(cast receipt "$TX" blockHash --rpc-url "$RPC")
for i in $(seq 1 120); do
FIN=$(cast rpc g4_status --rpc-url "$RPC" | python3 -c 'import json,sys; print(json.load(sys.stdin)["finalized_height"])')
if [ "$FIN" -ge "$BLOCK" ]; then
test "$(cast block "$BLOCK" --field hash --rpc-url "$RPC")" = "$HASH" && { echo "finalized (checkpoint $FIN)"; break; }
echo "block was reorganised out; resubmit" >&2; exit 1
fi
sleep 10
done
In the tested run this took about 8 minutes (two 32-block epochs at 3–7 s per block).
Common errors¶
| Symptom | Cause | Fix |
|---|---|---|
not chain 77240 |
Wrong endpoint or a different network | Use a PQWERAI testnet node; never override the chain ID check |
Connection refused on 127.0.0.1:8545 |
Node not running, or RPC on another port | pqwerai-health, or check PQWERAI_RPC_PORT in /etc/pqwerai/core.env |
HTTP 401 unauthorized |
Remote node uses --rpc.token-file |
Add -H "Authorization: Bearer …" (curl) or use a local node |
insufficient funds for gas * price + value |
Account not funded | Fund it (step 3) |
nonce too low |
Another transaction from the same account was mined | Re-run; cast fetches the next nonce |
| Finality loop never ends | Less than 2/3 of validator stake online; PoW continues but finality stalls | Check g4_status; the network operator must restore validator quorum |
unknown account |
You called eth_sendTransaction; the node holds no keys |
Sign locally (cast, wallet) — PQWERAI never unlocks accounts on nodes |
Sources at 72057fe3ec: developers/examples/quickstart/check-network.sh · developers/examples/quickstart/inspect-block.sh · developers/examples/quickstart/create-account.sh · developers/examples/quickstart/send-transaction.sh · developers/examples/quickstart/wait-finality.sh
Found a problem? Report a documentation issue · Build testnet-rc1+72057fe3ec