Passa al contenuto principale

Guida rapida

Da zero a una transazione inviata. Questa pagina utilizza l'SDK TypeScript (@qorechain/sdk); brevi snippet di connessione e lettura per Python, Go e Rust si trovano alla fine.

1. Connessione​

createClient() risolve una rete e compone i client di lettura, un helper per le commissioni e un punto di ingresso pigro per la firma. Per impostazione predefinita punta alla testnet pubblica (qorechain-diana), sugli endpoint pubblici (questo è cambiato nell'SDK 0.12.0: le release precedenti usavano per default localhost e richiedevano endpoints). Passa endpoints per usare il tuo nodo, oppure seleziona localnet per un nodo sulla tua macchina. Gli endpoint pubblici sono elencati nel riferimento di rete.

import { createClient } from "@qorechain/sdk";

// Testnet (chain id "qorechain-diana"), public testnet endpoints (SDK 0.12.0+).
const client = createClient();

// A node on this machine (chain id "qorechain-devnet", localhost ports).
const local = createClient({ network: "localnet" });

// Your own node: override any endpoint, the rest keep the preset's values.
const remote = createClient({
endpoints: {
rest: "https://lcd.my-node.example", // Native REST (LCD)
rpc: "https://rpc.my-node.example", // consensus RPC (for signing)
},
});

La mainnet (chain id qorechain-vladi) è attiva. Selezionala; il preset porta gli endpoint pubblici della mainnet. La chiamata qui sotto li esplicita, cosa di cui ha bisogno un SDK precedente alla 0.12.0:

const main = createClient({
network: "mainnet",
endpoints: {
rest: "https://api.qore.host",
rpc: "https://rpc.qore.host",
evmRpc: "https://evm.qore.host",
},
});

2. Derivare un account​

Una singola mnemonica deriva account native (qor1…), EVM (0x…) e SVM (base58) tramite percorsi di derivazione indipendenti.

import {
generateMnemonic,
deriveNativeAccount,
} from "@qorechain/sdk";

const mnemonic = generateMnemonic(); // 12 words (pass 256 for 24 words)

const native = await deriveNativeAccount(mnemonic);
console.log(native.address); // "qor1..." (Native secp256k1, coin type 118)

A partire dalla 0.6.0 puoi invece derivare un account unificato eth-native — una sola chiave eth_secp256k1 rappresentata come tutti e tre gli indirizzi (qor1…, 0x…, base58 SVM) con un unico saldo condiviso:

import { deriveUnifiedAccount } from "@qorechain/sdk";

const unified = await deriveUnifiedAccount(mnemonic);
console.log(unified.cosmos); // "qor1..."
console.log(unified.evm); // "0x..."
console.log(unified.svm); // base58 (same 20 bytes + 12 zero bytes)

Vedi Account e firma PQC per la derivazione EVM/SVM, gli account unificati e la tabella di derivazione completa.

3. Leggere un saldo​

// Native bank balances over REST.
const balances = await client.rest.getAllBalances(native.address);

// Any REST route works through the typed escape hatch, for example the burn
// statistics.
const burn = await client.rest.getBurnStats();

client.qor (le chiamate JSON-RPC qor_ tipizzate) non è utilizzabile sugli endpoint pubblici: nessuna build del nodo rilasciata serve quel namespace, quindi ogni chiamata restituisce -32601 (metodo non trovato). Leggi invece tramite REST. Vedi il namespace qor_.

4. Inviare un trasferimento QOR​

Su mainnet e testnet ogni transazione del percorso Native deve portare la firma ibrida (secp256k1 classica più ML-DSA-87), e la chiave ML-DSA-87 dell'account deve essere registrata prima on-chain. La registrazione è esplicita: non esiste alcuna registrazione automatica alla prima transazione. Una transazione firmata solo in modo classico viene rifiutata dalle reti live, quindi dai al client delle transazioni la coppia di chiavi ML-DSA-87 dell'account e firmerà ogni transazione in modo ibrido. I due passaggi seguenti richiedono SDK 0.9.0 o successivo (la 0.14.0 è quella attuale) e un account con fondi:

npm i @qorechain/sdk

4a. Registrare la tua chiave post-quantistica (una sola volta)​

L'account paga la commissione: la chiave da 2.592 byte richiede un gas limit di circa 600.000. ensurePqcRegistered legge prima lo stato della chiave via REST (rest), quindi salta la transazione quando la chiave è già registrata, e lancia PqcKeyMismatchError senza inviare nulla quando l'account detiene una chiave diversa (una seconda registrazione viene rifiutata dopo che la commissione è stata prelevata). La registrazione è l'unica transazione firmata in modo classico che la chain accetta da un account senza chiave, quindi il client ibrido la invia da sé in modo classico. Una volta che la rete ha applicato la v3.2.3 (lo hanno fatto entrambe le reti), l'helper allega anche la prova di possesso opzionale. La chain rifiuta chiavi deboli, degeneri o riutilizzate; una chiave ottenuta da derivePqcCanonical va bene.

import {
createClient,
deriveNativeAccount,
directSignerFromPrivateKey,
derivePqcCanonical,
ensurePqcRegistered,
} from "@qorechain/sdk";

const REST = "https://api-testnet.qore.host";
const RPC = "https://rpc-testnet.qore.host";

const client = createClient({ endpoints: { rest: REST, rpc: RPC } });

const account = await deriveNativeAccount(mnemonic);
const signer = await directSignerFromPrivateKey(account.privateKey, "qor");

// The address-bound ML-DSA-87 key, recoverable from { address, mnemonic }.
const pqcKeypair = derivePqcCanonical(account.address, mnemonic);

// With the keypair, every transaction this client sends is signed hybrid.
const tx = await client.connectTx(signer, { pqcKeypair });

const res = await ensurePqcRegistered(tx, {
pqcKeypair,
rest: client.network.endpoints.rest, // reads the status first; never registers blind
fee: { amount: [{ denom: "uqor", amount: "60000" }], gas: "600000" },
});
console.log(res.alreadyRegistered ? "already registered" : res.txHash);

4b. Inviare con una firma ibrida​

tx.bankSend ora firma in modo ibrido. La commissione è "auto" per impostazione predefinita: il client simula da sé la transazione ibrida. Su una rete che ha applicato la v3.2.5 (lo hanno fatto entrambe), l'SDK 0.12.0 imposta il limite di gas a ceil(simulated x 1.02) + 2000, perché la simulazione addebita già la verifica post-quantistica: un invio bancario ibrido richiede circa 171,600 di gas. Sulle reti più vecchie, e con l'SDK 0.10.0 o precedente, il client aggiunge da sé il gas della verifica post-quantistica (circa 289,000 per lo stesso invio). Il prezzo minimo del gas della rete è 0,1 uqor per unità di gas (il client applica 0,15). Usa toBase("1.5") per convertire QOR in uqor base.

import { toBase } from "@qorechain/sdk";

const result = await tx.bankSend("qor1recipientaddress...", [
{ denom: "uqor", amount: toBase("1.5") },
]);
console.log(result.transactionHash);

toBase("1.5") restituisce "1500000" (QOR ha 10^6 unità base uqor). Per inviare allo stesso modo qualsiasi altro messaggio, passalo a tx.signAndBroadcast([message], "auto"). Per un controllo esplicito di commissione, numero di account e sequence, usa signAndBroadcastHybrid (vedi Account e firma PQC).

Account unificati

Per un account unificato eth-native (deriveUnifiedAccount), usa invece EthNativeSigner; gli esempi di registrazione e invio si trovano in Account e firma PQC.

Senza una coppia di chiavi il client firma in modo classico

client.connectTx(signer) senza pqcKeypair firma solo in modo classico. Le reti pubbliche lo accettano soltanto per la registrazione della chiave (un account senza ancora una chiave); contro un nodo che non richiede l'estensione ibrida (un nodo di sviluppo locale) invia anche i trasferimenti ordinari. Le versioni dell'SDK precedenti alla 0.9.0 non hanno un TxClient ibrido: invia tramite signAndBroadcastHybrid (vedi Versioni precedenti alla 0.9.0).

Altri linguaggi: connessione e lettura​

Questi rispecchiano gli stessi preset di rete e la stessa superficie di lettura. Usano gli endpoint della testnet pubblica; per la mainnet passa "mainnet" e gli URL della mainnet.

Python​

from qorsdk import create_client

client = create_client(
network="testnet",
endpoints={
"rest": "https://api-testnet.qore.host",
"rpc": "https://rpc-testnet.qore.host",
"evm_rpc": "https://evm-testnet.qore.host",
},
)
print(client.network.chain_id) # "qorechain-diana"

balances = client.rest.get_all_balances("qor1...")
burn = client.rest.get_burn_stats()
client.close()

Go​

import (
"fmt"

"github.com/qorechain/qorechain-sdk/packages/go/qorechain/client"
)

c, err := client.CreateClient(client.Options{
Network: "testnet",
Endpoints: client.EndpointOverrides{
REST: "https://api-testnet.qore.host",
RPC: "https://rpc-testnet.qore.host",
EVMRPC: "https://evm-testnet.qore.host",
},
})
if err != nil {
panic(err)
}
fmt.Println(c.Network.ChainID) // qorechain-diana

balances, err := c.REST.GetAllBalances("qor1...")
burn, err := c.REST.GetBurnStats()

Rust​

use qorechain::ClientBuilder;

#[tokio::main]
async fn main() -> qorechain::Result<()> {
let client = ClientBuilder::new()
.network("testnet")
.rest("https://api-testnet.qore.host")
.rpc("https://rpc-testnet.qore.host")
.evm_rpc("https://evm-testnet.qore.host")
.build()?;
let balances = client.rest.get_all_balances("qor1...").await?;
let burn = client.rest.get_burn_stats().await?;
let _ = (balances, burn);
Ok(())
}

Prossimi passi​