Saltar al contenido principal

App en Java: Q-Day Tip Jar

El Q-Day Tip Jar es un pequeño programa en Java para la testnet de QoreChain (qorechain-diana, EVM chain ID 9800). Envía propinas con una firma híbrida: una firma clásica secp256k1 más una firma poscuántica ML-DSA-87 (FIPS 204). También puede vigilar una dirección "bote" (jar), como lo haría el backend de una tienda, y distinguir las propinas resistentes a la computación cuántica de las clásicas.

Cuánto tarda: unos 20 minutos la primera vez (10 minutos instalando herramientas, 5 de configuración y 5 enviando y comprobando).

No necesitas saber Java. Solo escribes los comandos de abajo, uno por uno, y comparas el resultado con "Qué deberías ver".

Qué demuestra​

  • Firma híbrida ML-DSA-87 + secp256k1 desde Java con una sola llamada del SDK.
  • Una transacción firmada de forma híbrida y verificada en la cadena: la cadena registra un evento pqc_hybrid_verify con status=verified, y la transacción lleva una firma ML-DSA-87 de 4.627 bytes.
  • Un backend que distingue las propinas resistentes a la computación cuántica de las clásicas: watch etiqueta cada transferencia entrante como QUANTUM-SAFE o classical only.

Por qué importa: se espera que un ordenador cuántico futuro pueda romper una firma solo clásica. Un servicio que consulta el registro de verificación de la propia cadena puede decidir cuánta confianza dar a cada pago. Consulta Transacciones resistentes a la computación cuántica.

Solo testnet

Usa solo una cuenta de testnet desechable. Los QOR de la testnet no tienen valor. No uses en este tutorial tu wallet real, tu frase de recuperación real ni fondos reales.

Palabras que verás​

PalabraSignificado
TestnetUna copia de práctica de QoreChain. Sus monedas son gratis y no valen nada.
QOR y uqorDos nombres de la misma moneda. 1 QOR = 1.000.000 uqor. La app pide QOR. Las comisiones se muestran en uqor.
MemoUn texto corto adjunto a una transacción, como la nota de una transferencia bancaria.
DirecciónTu número de cuenta público. En QoreChain empieza por qor1. Es seguro compartirla.
Archivo de claveUn archivo con tu frase de recuperación secreta. No lo compartas nunca.
FaucetUn sitio web que da QOR de testnet gratis.
HashEl identificador único de una transacción. Sirve para buscarla.

Antes de empezar​

Necesitas tres herramientas: Git (descarga el código), Java 21 o superior (ejecuta la app) y Maven (compila la app). Tras cada instalación, cierra la terminal y abre una nueva, y luego ejecuta el comando de comprobación.

HerramientamacOSWindowsLinux (Debian o Ubuntu)Comprobación
Gitbrew install git (Homebrew desde https://brew.sh)https://git-scm.com/download/win (esto también te da "Git Bash")sudo apt install gitgit --version
Java 21+brew install openjdk@21https://adoptium.net (elige Temurin 21, el instalador .msi)sudo apt install openjdk-21-jdkjava -version debe decir 21 o superior
Mavenbrew install mavenDescarga el zip desde https://maven.apache.org/download.cgi y sigue https://maven.apache.org/install.htmlsudo apt install mavenmvn -version

En Windows, usa Git Bash (se instala con Git) como terminal para este tutorial, porque el lanzador tipjar es un script de shell. En macOS usa Terminal. En Linux usa cualquier terminal. Si prefieres PowerShell a secas, mira la nota del paso 3.

En macOS con Homebrew: brew install openjdk@21 puede decirte que lo enlaces. Si java -version sigue mostrando una versión antigua, ejecuta lo que Homebrew imprime bajo "For the system Java wrappers to find this JDK" y abre una terminal nueva.

Consigue una wallet de testnet y QOR gratis​

La app crea su propia clave desechable (paso 4 de abajo), así que no necesitas estrictamente una app de wallet para este tutorial. Sí necesitas un lugar donde conseguir QOR de testnet. Si además quieres ver tu cuenta en QoreX:

  1. App QoreX: abre Ajustes y activa Use testnet (developers).
  2. Extensión de navegador de QoreX: desbloquéala, toca 7 veces el número de versión de la parte inferior y elige Switch to testnet (diana).

Los QOR gratis salen del faucet en https://dashboard.qorechain.io/faucet. Inicias sesión, pegas la dirección y haces la solicitud. Da 100 QOR cada 24 horas por cuenta.

La primera transacción de una cuenta nueva registra en la cadena su clave poscuántica ML-DSA-87. Es un paso único con una tarifa de unos 0,09 QOR. La app lo hace por ti con el comando register.

Paso a paso​

1. Descarga el código​

git clone https://github.com/qorechain/build-before-qday
cd build-before-qday/workshop-1/05-java-tipjar

Qué hace

  • git clone <address>: copia el proyecto desde GitHub a una carpeta nueva llamada build-before-qday en tu ordenador.
  • cd <folder>: mueve tu terminal a la carpeta de la app en Java. Todos los comandos posteriores deben ejecutarse desde esta carpeta.

Qué deberías ver: líneas como Cloning into 'build-before-qday'... y después tu prompt en la carpeta nueva.

2. Compila la app​

mvn -q package

Qué hace: Maven descarga el SDK de QoreChain desde Maven Central y empaqueta la app en un único archivo ejecutable, target/tipjar.jar.

ParteSignificado
mvnLa herramienta de compilación Maven.
packageCompila el código y lo empaqueta en un archivo .jar.
-qModo silencioso: imprime solo los problemas.

Qué deberías ver: nada durante unos segundos (unos 10 segundos la primera vez, algo más con una conexión lenta) y luego vuelve tu prompt. Comprueba que el archivo existe:

ls target/tipjar.jar

Qué deberías ver: target/tipjar.jar.

3. Haz ejecutable el lanzador y pruébalo​

chmod +x tipjar
./tipjar

Qué hace

ParteSignificado
chmod +x tipjarPermite que el archivo tipjar se ejecute como un programa. Una descarga recién hecha no tiene este permiso.
./tipjarEjecuta el lanzador de esta carpeta. Arranca java -jar target/tipjar.jar. Sin ningún comando imprime la ayuda.

Qué deberías ver: una lista de comandos: new, status, register, tip, watch.

PowerShell a secas en Windows

Omite chmod. Sustituye ./tipjar por java -jar target/tipjar.jar en todos los comandos de abajo.

4. Crea tu cuenta de testnet desechable​

./tipjar new

Qué hace: crea una cuenta nueva. Escribe una frase de recuperación secreta en el archivo de clave ~/.config/qday/java.env (en tu carpeta personal, legible solo por tu usuario) e imprime únicamente la dirección pública.

ParteSignificado
newCrea un archivo de clave nuevo e imprime su dirección.
new --forceReemplaza un archivo de clave existente. La clave anterior se pierde.

Qué deberías ver: new jar key, la ruta del archivo de clave y una address que empieza por qor1.... La frase de recuperación nunca se imprime.

Copia la dirección qor1.... Si la pierdes, ./tipjar status la imprime de nuevo. No compartas nunca el archivo de clave, no lo subas nunca a Git y no lo reutilices nunca en la mainnet. Para guardar la clave en otro lugar, define primero TIPJAR_KEY: TIPJAR_KEY=/path/to/file ./tipjar status (en PowerShell: $env:TIPJAR_KEY="C:\path\file").

5. Consigue QOR de testnet en el faucet​

  1. Abre https://dashboard.qorechain.io/faucet e inicia sesión.
  2. Pega tu dirección qor1... y pulsa el botón de solicitud.
  3. Espera unos segundos y ejecuta:
./tipjar status

Qué hace: le pregunta a la testnet tu saldo y si tu clave poscuántica está registrada.

Qué deberías ver: balance 100 QOR (o la cantidad del faucet) y una línea que dice que la clave ML-DSA-87 aún no está registrada. Si el saldo es 0, espera 10 segundos y ejecútalo otra vez.

6. Registra tu clave poscuántica​

./tipjar register

Qué hace: registra tu clave ML-DSA-87 en la cadena, una sola vez. Es seguro ejecutarlo de nuevo. Esta primera transacción se firma solo con la clave clásica, porque todavía no hay en la cadena ninguna clave poscuántica con la que firmar. Cuesta unos 0,09 QOR. Cada transacción posterior se firma de forma híbrida.

Qué deberías ver: un hash de transacción y un mensaje de que la clave está registrada. Ejecuta ./tipjar status otra vez y ahora debería mostrar la clave como registrada.

Cuánto tarda: unos segundos (un bloque).

7. Crea una segunda dirección para recibir propinas​

Una propina necesita a alguien que la reciba. Crea una segunda cuenta desechable, el "bote" (jar), con su propio archivo de clave:

TIPJAR_KEY=~/.config/qday/jar.env ./tipjar new

Qué hace: la parte anterior a ./tipjar define el archivo de clave solo para este comando (TIPJAR_KEY), así que la cuenta nueva no sobrescribe la primera. En PowerShell de Windows ejecuta antes $env:TIPJAR_KEY="$HOME\.config\qday\jar.env", después java -jar target/tipjar.jar new, y restablécelo al final con Remove-Item Env:TIPJAR_KEY.

Qué deberías ver: una dirección qor1... nueva. Cópiala. Esta es tu dirección del bote. El bote no necesita ningún QOR para recibir propinas.

8. Envía una propina con firma híbrida​

./tipjar tip qor1...JAR_ADDRESS 1 "my first quantum-safe tip"

Sustituye qor1...JAR_ADDRESS por la dirección del bote del paso 7.

ParteSignificado
tipEnvía una propina.
qor1...JAR_ADDRESSQuién recibe la propina.
1La cantidad en QOR (es decir, 1 QOR = 1.000.000 uqor).
"my first quantum-safe tip"El memo, un texto corto adjunto a la transacción. Opcional. Mantén las comillas si tiene espacios.

Qué hace: la app le pregunta a la cadena cuánto gas necesita la transacción (una ejecución de prueba), añade un 30 por ciento como margen de seguridad, firma con las dos claves, la envía, espera al bloque y después comprueba el propio registro de la cadena.

Qué deberías ver: el hash de la transacción, la altura del bloque y el resultado QUANTUM-SAFE. Si ves CHECK FAILED, consulta la Solución de problemas. Copia el hash.

Cuánto tarda: unos 10 segundos.

9. Vigila el bote, como lo haría el backend de una tienda​

Abre una segunda terminal, ve a la misma carpeta e inicia el vigilante:

cd build-before-qday/workshop-1/05-java-tipjar
./tipjar watch qor1...JAR_ADDRESS

Ahora vuelve a la primera terminal y envía una propina más (paso 8, con un memo nuevo).

Qué hace: watch le pregunta a la cadena cada 3 segundos por nuevas transferencias al bote y etiqueta cada una. NO_COLOR=1 ./tipjar watch ... desactiva los colores. Detenlo con Ctrl+C.

Qué deberías ver: cada propina listada con la etiqueta QUANTUM-SAFE. Una propina enviada sin una firma híbrida verificada mostraría classical only.

Verifica la transacción tú mismo​

No tienes que fiarte de la app. Pregúntale directamente a la cadena.

Forma 1, en el navegador. Abre https://explore.qore.network/tx/<HASH> (pon tu hash en lugar de <HASH>) y cambia el explorador a Testnet. Deberías ver una transacción exitosa.

Forma 2, un comando. Pon tu hash en lugar de <HASH>:

curl -s https://api-testnet.qore.host/cosmos/tx/v1beta1/txs/<HASH>
ParteSignificado
curlUna herramienta que descarga una dirección web. Viene incluida en macOS, Windows 10+ y la mayoría de Linux.
-sSilencioso: oculta la barra de progreso.
la direcciónLa API REST pública de la testnet. Devuelve el registro completo de la transacción en JSON.

Qué deberías ver en la salida larga (usa un visor de JSON o añade | jq . si instalaste jq):

  • "code": 0 significa que la transacción tuvo éxito.
  • Una extensión PQCHybridSignature con un pqc_signature de 4.627 bytes (esa es la firma ML-DSA-87).
  • Un evento pqc_hybrid_verify con status igual a verified para tu dirección.

Cómo funciona la prueba​

La app lee el mismo registro de GET /cosmos/tx/v1beta1/txs/\{hash\} y busca el evento pqc_hybrid_verify (address=<signer>, status=verified) y la extensión /qorechain.pqc.v1.PQCHybridSignature con una firma de 4.627 bytes. El vigilante hace lo mismo con cada transferencia entrante.

Solución de problemas​

Qué vesPor quéQué hacer
./tipjar: Permission deniedUna descarga nueva no está marcada como ejecutable.Ejecuta chmod +x tipjar.
build first: (cd ... && mvn -q package)Falta el archivo jar.Ejecuta mvn -q package en esta carpeta (paso 2).
mvn: command not found o java: command not foundLa herramienta no está instalada, o la terminal no se reabrió.Instálala (consulta Antes de empezar), abre una terminal nueva y comprueba la versión.
Java dice versión 17 o inferiorUna versión antigua de Java va primero en tu ruta.Instala Java 21, abre una terminal nueva y ejecuta java -version otra vez.
no key file at ..., run new firstTe saltaste el paso 4, o TIPJAR_KEY apunta a otro sitio.Ejecuta ./tipjar new.
key file already existsYa creaste una clave.Consérvala, o reemplázala con ./tipjar new --force (la clave anterior se pierde).
account has no PQC key and classical fallback is disabledLa clave poscuántica aún no está registrada.Ejecuta primero ./tipjar register.
EVM authorisation window exhaustedEste mensaje pertenece a las apps EVM (counter, guestbook). El Tip Jar no lo usa.En las apps EVM, abre una ventana nueva con pnpm window open.
HHE10402 tras abrir la ventanaSolo en las apps de Hardhat: la ventana aún no estaba activa.En las apps de Hardhat, vuelve a ejecutar el despliegue.
El saldo es 0 o not on chain yetLos tokens del faucet aún no han llegado.Espera 10 segundos y ejecuta ./tipjar status. Comprueba que pegaste la dirección correcta.
El faucet dice límite de solicitudesUna solicitud cada 24 horas por cuenta.Espera, o usa una segunda cuenta desechable.
chain refused the tx o poll failedLa testnet está ocupada o en actualización, o el endpoint público limita las solicitudes por dirección IP.Espera un minuto y vuelve a ejecutar el comando.
recipient must be a qor1... addressLa dirección es incorrecta o tiene espacios.Copia de nuevo la dirección qor1... completa.
Errores de CORS en un navegadorSolo ocurren cuando una página web llama a la cadena directamente. Esta app no lo hace.En una app de navegador, usa el proxy /lcd de la plantilla.
pnpm: command not foundpnpm no está instalado. Aquí no hace falta.Solo para el tutorial de Hardhat: ejecuta npm install -g pnpm.

El código del SDK que importa​

PqcDx.Signer signer = new PqcDx.Signer(); // keys, chain id, account number, sequence
signer.secp256k1PrivateKey = account.privateKey; // classical half
signer.pqcKeypair = Authenticator.derivePqcCanonical(account.address, mnemonic); // ML-DSA-87 half
signer.chainId = "qorechain-diana";
signer.restUrl = Networks.get("testnet").endpoints.rest; // sign-bytes version and key checks

PqcDx.HybridSendPath path = PqcDx.migrateToHybrid(signer, new Broadcaster(rpc), null, opts); // registers once
TypedMessage tip = NativeTx.bankSend(from, to, List.of(new StdFee.Coin("uqor", "500000")));
var sent = path.sendAuto(List.of(tip), "0.15uqor", 1.3); // simulate, price, hybrid-sign, broadcast
TxTracker.waitForTx(new RestClient(rest), sent.result.transactionHash, null);

El gas nunca es fijo: cada transacción se simula primero y recibe el gas simulado multiplicado por 1,3, con un precio de 0,15 uqor por unidad de gas.

La cuenta es una cuenta clásica de QoreChain con coin 118 (m/44'/118'/0'/0/0). La clave ML-DSA-87 se deriva de la misma frase de recuperación y se liga a la dirección con Authenticator.derivePqcCanonical. Si creas tu propia app con las ayudas basadas en semilla, el SDK 0.13.0 necesita un código de recuperación o un secreto PQC independiente de 32 bytes; consulta Instalación del SDK. No imprimas nunca un código de recuperación.

Paquetes usados​

ElementoVersión
io.github.qorechain:qorechain-sdk (Maven Central)0.13.0
com.fasterxml.jackson.core:jackson-databind2.17.2
org.codehaus.mojo:exec-maven-plugin3.5.0
org.apache.maven.plugins:maven-shade-plugin3.6.0
Java (maven.compiler.release)21
App demo:tipjar1.0.0

Consulta Instalación del SDK para ver la tabla de versiones de todos los lenguajes.

Dónde consultar cada cosa​

QuéDónde
RESThttps://api-testnet.qore.host
RPChttps://rpc-testnet.qore.host
EVMhttps://evm-testnet.qore.host
Exploradorhttps://explore.qore.network (cambia a Testnet)
Faucethttps://dashboard.qorechain.io/faucet
Códigohttps://github.com/qorechain/build-before-qday/tree/main/workshop-1/05-java-tipjar