Un flag confidencial suele ser un marcador definido por la aplicación que indica al software que debe tratar un registro, una solicitud o una transacción como información sensible; no implica automáticamente cifrado ni privacidad on-chain. Por lo general, los protocolos de blockchain públicos no ofrecen un campo JSON-RPC universal denominado confidential, por lo que la aplicación, el contrato inteligente, la wallet, el indexador o el protocolo con funciones de privacidad deben definir el flag. Esta guía explica el modelo mental, muestra patrones de implementación con placeholders como RPC_URL y PRIVATE_KEY, y proporciona un procedimiento de verificación reproducible. También identifica los límites de seguridad de un flag y los controles necesarios cuando la confidencialidad es un requisito real.
Significado y alcance de un flag confidencial
Un flag confidencial es un valor booleano o enumerado que cambia la forma en que el software gestiona los datos. Por ejemplo, una aplicación podría establecer confidential: true para suprimir campos sensibles de los registros, restringir el acceso en una API, seleccionar un payload cifrado o indicar a un indexador que no exponga metadatos opcionales. El comportamiento exacto depende del sistema que define el campo.
El flag por sí solo no es un mecanismo primitivo de privacidad. Si un valor en texto plano se publica en la entrada de una transacción, un evento, un campo de calldata, un bloque o una base de datos pública, añadir un marcador confidencial no lo oculta. Cualquiera que tenga acceso a esos datos públicos puede inspeccionarlos, copiarlos y archivarlos.
En un RPC blockchain convencional, trata confidential como metadatos de la aplicación, a menos que la documentación del protocolo de la red defina explícitamente un mecanismo criptográfico de privacidad. Esta distinción evita un error de diseño habitual: asumir que una etiqueta cambia la visibilidad de los datos después de su publicación.
- Marcador: registra la política de gestión prevista.
- Cifrado: transforma los datos para que los lectores no autorizados no puedan entenderlos.
- Control de acceso: determina quién puede recuperarlos o descifrarlos.
- Protocolo de transacciones confidenciales: cambia la forma en que se revelan los contenidos de las transacciones o el estado.
Límites del protocolo y visibilidad de los datos
La mayoría de los métodos JSON-RPC estándar de blockchain describen operaciones de transporte y del ledger, como recuperar bloques, enviar transacciones o leer el estado de un contrato. Un proveedor puede reenviar una solicitud que contenga campos de aplicación personalizados, rechazarlos o ignorarlos según la implementación del nodo y del middleware. No debes inferir que la red admite un campo basándote únicamente en su nombre.
Antes de usar el flag, identifica dónde se define: una ABI de contrato inteligente, un SDK de wallet, un esquema de API, un indexador, un servicio de transacciones privadas o una función de privacidad específica de la red. La fuente autorizada debe especificar los valores aceptados, el comportamiento predeterminado, si el campo se conserva y qué partes pueden observarlo.
En redes públicas compatibles con EVM, un contrato puede almacenar un flag en el estado o emitirlo en un evento, pero tanto la transición de estado como el evento suelen ser observables. Una ruta RPC privada puede proteger el transporte entre tu aplicación y un proveedor, pero no necesariamente hace privado el estado resultante de la blockchain.
- Documenta el propietario y la versión del campo antes de integrarlo.
- Separa la confidencialidad del transporte de la confidencialidad del ledger.
- Comprueba si los logs, las trazas, los datos del mempool y las bases de datos de los indexadores exponen el contenido marcado.
- Usa una guía específica de la red del directorio de redes compatibles cuando el comportamiento de privacidad dependa de una cadena concreta.
Modelo de seguridad y supuestos sobre las amenazas
Define qué debe permanecer confidencial antes de elegir una implementación. La amenaza puede ser un observador externo, un indexador público, otro usuario de la aplicación, una credencial RPC comprometida o un operador con acceso a los logs. Un único booleano no puede abordar todas estas amenazas.
Un modelo útil separa cuatro ubicaciones: el cliente, el transporte RPC, la transacción pendiente o mempool y los datos finalizados de la cadena. TLS protege la conexión con un endpoint HTTPS, pero el operador del endpoint aún puede procesar la solicitud. Una vez que los datos en texto plano entran en una transacción o evento público, el cifrado o la redacción posteriores no pueden restaurar la confidencialidad.
Escribe una política explícita para cada campo. Por ejemplo, los identificadores públicos pueden almacenarse on-chain; los valores sensibles pueden cifrarse en el cliente; puede publicarse un commitment o hash para su verificación posterior; y la clave de descifrado puede distribuirse mediante un servicio off-chain autenticado. No trates un hash como algo automáticamente privado: las entradas con baja entropía pueden adivinarse y compararse.
- Objetivo de confidencialidad: ¿quién no debe ver el valor?
- Objetivo de conservación: ¿durante cuánto tiempo debe permanecer protegido?
- Objetivo de integridad: ¿deben los lectores demostrar que el valor no se modificó?
- Objetivo de disponibilidad: ¿quién puede recuperar el valor si el cliente original no está disponible?
Patrón de implementación a nivel de aplicación
En una aplicación convencional, define el flag en un esquema versionado en lugar de colocar una propiedad no documentada junto a un parámetro RPC estándar. Un registro práctico puede contener un identificador de registro público, una versión de política, un booleano o modo, un texto cifrado o commitment y una referencia off-chain. Después, la aplicación aplica la política de forma coherente durante la incorporación, el almacenamiento, el registro y la recuperación.
No envíes valores privados a un endpoint que no sea de confianza solo porque la solicitud incluye confidential: true. Si el valor no debe ser visible para el operador RPC, cífralo antes de crear la solicitud. Mantén las claves fuera del control de versiones y evita incluirlas en bundles del navegador o en el calldata de las transacciones.
El siguiente ejemplo envía un documento JSON definido por la aplicación a una ruta de API. No es un método JSON-RPC estándar de blockchain; reemplaza RPC_URL por una ruta documentada por tu propio servicio. El ejemplo demuestra la semántica del flag sin afirmar que un nodo vaya a aplicarla.
- Valida
schemaVersiony rechaza los modos de política desconocidos. - Redacta el payload y las credenciales en los logs de la aplicación.
- Devuelve un resultado de política explícito, como
accepted,rejectedounsupported. - Prueba tanto la ruta confidencial como la no confidencial.
curl -X POST "$RPC_URL/v1/records" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_TOKEN" \
--data '{
"schemaVersion": 1,
"confidential": true,
"payload": "CLIENT_SIDE_CIPHERTEXT",
"commitment": "OPTIONAL_COMMITMENT"
}'Representación on-chain y verificación del contrato
Si un contrato necesita registrar que un flujo de trabajo sigue una política de confidencialidad, almacena únicamente los metadatos públicos mínimos. Un contrato de Solidity podría registrar un booleano y un commitment, pero el booleano seguirá siendo público y no ocultará el valor comprometido. El commitment solo demuestra coherencia cuando el valor subyacente y el nonce se revelan y comprueban posteriormente.
Cuando el flag forma parte de una transacción, verifica el comportamiento real del contrato en lugar de confiar en la visualización de una wallet o en una propiedad del SDK. Confirma la codificación de la ABI, el evento emitido, el estado del recibo y el estado resultante. Si un contrato ignora un campo adicional del lado del cliente, la transacción puede completarse correctamente aunque la política prevista nunca se registre.
El siguiente JavaScript utiliza un endpoint JSON-RPC compatible con EVM mediante ethers. Lee el flag público y el commitment de un contrato después del despliegue. Reemplaza los placeholders por valores de tu despliegue; no incluyas una clave privada en el código frontend.
- Confirma la dirección del contrato y el chain ID antes de leer el estado.
- Compara el flag devuelto con la entrada de la transacción o la configuración del despliegue.
- Trata el commitment devuelto como metadatos públicos, no como el secreto en sí.
- Usa la documentación de endpoints RPC para distinguir la configuración del endpoint del comportamiento del contrato.
import { ethers } from "ethers";
const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
const contract = new ethers.Contract(
process.env.CONTRACT_ADDRESS,
[
"function confidential() view returns (bool)",
"function commitment() view returns (bytes32)"
],
provider
);
const [confidential, commitment] = await Promise.all([
contract.confidential(),
contract.commitment()
]);
console.log(JSON.stringify({ confidential, commitment }, null, 2));Inspección de solicitudes y respuestas RPC
Cuando el flag lo implementa un middleware o una API gateway, inspecciona la solicitud y la respuesta sin procesar antes de depurar la cadena. Una respuesta HTTP correcta aún puede contener un rechazo a nivel de aplicación, mientras que un error JSON-RPC puede indicar que el método o el parámetro no son compatibles.
Empieza con una solicitud mínima y después añade el campo confidencial para comparar las respuestas. Registra el estado HTTP, el objeto de error JSON-RPC, el identificador de solicitud, el estado de política devuelto y cualquier hash de transacción. Nunca pegues tokens de API, claves privadas, secretos en texto plano ni transacciones raw firmadas en tickets compartidos.
Este ejemplo en Python compara dos llamadas de aplicación documentadas. Supone que el servicio acepta un método definido por el contrato de tu propia API; no afirma que todos los nodos blockchain implementen setConfidentialFlag.
- Usa un ID de solicitud único para correlacionar reintentos y logs del proveedor.
- Comprueba si el endpoint espera parámetros posicionales o con nombre.
- Compara el esquema de la respuesta, no solo el estado HTTP.
- Ejecuta las pruebas con un registro de desarrollo antes de usar identificadores de producción.
import os
import json
import requests
rpc_url = os.environ["RPC_URL"]
headers = {"Content-Type": "application/json"}
def call(params):
body = {
"jsonrpc": "2.0",
"id": 1,
"method": "setConfidentialFlag",
"params": params
}
response = requests.post(rpc_url, headers=headers, json=body, timeout=20)
response.raise_for_status()
result = response.json()
if "error" in result:
raise RuntimeError(json.dumps(result["error"]))
return result["result"]
print("without flag:", call({"recordId": os.environ["RECORD_ID"], "confidential": False}))
print("with flag:", call({"recordId": os.environ["RECORD_ID"], "confidential": True}))Resultados de verificación y procedimiento de medición
Una prueba fiable demuestra tanto la semántica como la exposición. Crea dos registros de prueba equivalentes en todo lo demás: uno con el flag desactivado y otro activado. Usa un payload no sensible o un secreto de prueba generado localmente; después, inspecciona los logs del cliente, los logs del gateway, la respuesta RPC, el recibo de la transacción, el evento del contrato, el explorador público o la consulta al nodo y el indexador posterior.
Registra los resultados en una tabla en lugar de confiar en una etiqueta del dashboard. Deja los valores medidos en blanco hasta ejecutar la prueba en tu entorno. Una tabla de resultados útil incluye estas columnas: Test, Expected behavior, Observed result, Evidence y Pass/Fail. Las filas recomendadas incluyen aceptación de la API, cambio de estado, visibilidad del evento, exposición del payload, comportamiento de los reintentos y recuperación no autorizada.
Para medir el rendimiento, repite cada caso con el mismo tamaño de solicitud y nivel de concurrencia. Mide por separado la latencia percibida por el cliente, la tasa de errores, el tiempo de confirmación y el tamaño del payload. No compares proveedores o redes a partir de una única ejecución sin control; registra la cadena, la región, la versión del software, el estado del bloque, la concurrencia y la marca de tiempo.
- Aceptación de la API: la ruta documentada acepta el modo o devuelve un error claro de incompatibilidad.
- Persistencia: el estado o los metadatos previstos están presentes después de la confirmación.
- Exposición: el valor sensible está ausente de todas las ubicaciones en las que la política exige protección.
- Control de acceso: una identidad no autorizada no puede recuperar ni descifrar el valor.
- Recuperación: una identidad autorizada puede recuperar el valor mediante el proceso de claves documentado.
Modos de fallo y rutas de resolución de problemas
Si una solicitud devuelve un error de parámetro no válido, comprueba primero el esquema de la API o del contrato. El nombre confidential no basta para demostrar que existe compatibilidad. Algunos sistemas rechazan los campos desconocidos; otros los ignoran, lo cual es más peligroso porque el emisor puede asumir una protección que nunca se aplicó.
Si el flag aparece en una respuesta de la aplicación, pero no en el estado de la cadena, determina si solo se trata de metadatos del gateway. Inspecciona la transacción firmada, el recibo, los topics del evento y el almacenamiento del contrato. Si el valor está presente en el calldata o en un evento, considéralo público aunque la interfaz de usuario lo oculte.
Si la confidencialidad falla de forma intermitente, inspecciona los reintentos, los workers asíncronos, los payloads de las colas, los sistemas de trazas y el almacenamiento de mensajes fallidos. Los datos sensibles suelen filtrarse fuera de la base de datos principal. Rota las credenciales o claves de cifrado expuestas según tu procedimiento de incidentes; cambiar únicamente el flag no es una medida correctiva.
Si las lecturas difieren entre endpoints, compara el chain ID, la etiqueta del bloque, el estado finalizado y la respuesta del proveedor. Es posible que una transacción reciente no sea visible al mismo tiempo en todas las rutas de lectura. Consulta la guía de fiabilidad y consistencia de RPC para aplicar un enfoque estructurado a las discrepancias entre endpoints.
- Campo no compatible: elimina el campo o impleméntalo en la capa de aplicación documentada.
- Campo ignorado: adopta un comportamiento fail-closed y exige una confirmación explícita del servidor.
- Texto plano público: trata el valor como divulgado y rótalo o revócalo cuando sea posible.
- Estado obsoleto: compara los números de bloque y espera la política de confirmación requerida.
- Logs con filtraciones: redacta los datos en origen y revisa la telemetría y las copias de seguridad conservadas.
Compensaciones de diseño y límites operativos
Un marcador público es fácil de indexar, auditar e integrar, pero no proporciona secreto alguno. El cifrado del lado del cliente ofrece un mayor control sobre la exposición del texto plano, pero introduce responsabilidades de gestión, recuperación, rotación y revocación de claves. Los commitments conservan la verificabilidad mientras ocultan el valor a los observadores casuales, pero pueden someterse a ataques de fuerza bruta cuando las entradas son predecibles.
Una red con funciones de privacidad o un entorno de ejecución confidencial puede reducir la visibilidad pública, pero sus garantías dependen del protocolo, los componentes de confianza, los supuestos sobre validadores u operadores y el modelo de acceso de lectura. Revisa la documentación de seguridad de la red en lugar de tratar el endpoint de un proveedor como prueba de confidencialidad.
Desde el punto de vista operativo, los controles de privacidad pueden aumentar la latencia, el tamaño de los payloads, la complejidad de la recuperación ante fallos y la carga de soporte. Define el alcance confidencial mínimo necesario. Almacena públicamente el estado, las marcas de tiempo y los commitments cuando corresponda, y conserva los datos empresariales sensibles en un sistema cifrado diseñado para ese fin cuando no sea necesario almacenarlos on-chain.
Al elegir la infraestructura, compara el acceso documentado a la red, la autenticación, los límites y la observabilidad en lugar de asumir que un proveedor cambia la privacidad del protocolo. La descripción general del servicio RPC y la información de precios de RPC pueden ayudarte a planificar la infraestructura; no sustituyen el cifrado a nivel de aplicación ni el control de acceso.
Lista de comprobación de implementación y próximos pasos
Empieza por redactar la política de confidencialidad en lenguaje claro: qué se protege, de quién, durante cuánto tiempo y qué evidencias deben permanecer públicas. Después, mapea cada copia de los datos en el cliente, la solicitud RPC, la transacción, los logs, las colas, las bases de datos, los indexadores, las copias de seguridad y la interfaz de usuario.
A continuación, define un esquema versionado y un comportamiento fail-closed para los modos no compatibles. Cifra los valores sensibles antes de transmitirlos cuando el operador RPC no deba verlos, publica únicamente el commitment o el estado mínimo necesario para la verificación y prueba el acceso no autorizado con una identidad que no tenga permiso de descifrado.
Por último, ejecuta el procedimiento de la tabla de resultados en un entorno de desarrollo y conserva las evidencias necesarias para reproducirlo. Para decisiones de infraestructura más amplias, consulta la guía de endpoints RPC multicadena, revisa las opciones de nodos dedicados y usa RPC Assistant para obtener una recomendación breve y específica de la red cuando la elección del endpoint —no el diseño de confidencialidad— sea la decisión pendiente.
- Documenta si el flag es metadatos de la aplicación, estado del contrato o funcionalidad del protocolo.
- Mantén los secretos y las claves privadas en un almacenamiento de secretos gestionado mediante el entorno.
- Verifica de forma independiente los recibos, eventos, estados, logs y la exposición en los indexadores.
- Mide solo después de definir el entorno de prueba y los criterios de aceptación.
- Trata un flag confidencial como una señal de política, a menos que la privacidad criptográfica esté documentada explícitamente.