Referencia del SDK de Go

El SDK de Go (github.com/ULedgerInc/golang-sdk) es la capa de integración principal de ULedger. Se encarga de la gestión de claves de billetera, la construcción y firma de transactions, el envío, el polling y los test harnesses de extremo a extremo.

---

Instalación

go get github.com/ULedgerInc/golang-sdk

O clonar y compilar localmente:

git clone https://github.com/ULedgerInc/golang-sdk
cd golang-sdk
go build ./...

---

Herramientas de Línea de Comandos

Gestión de Billeteras

cmd/generate_wallets

Genera nuevos pares de claves de billetera a partir de entropía BIP39.

go run ./cmd/generate_wallets [flags]

Flags:
  --type    Key algorithm: secp256k1 | ed25519 | mldsa87 | bls12377 (required)
  --auth    Auth group preset: admin | wallet | readonly (optional)
  --count   Number of wallets to generate (default: 1)
  --out     Output directory for .ukey files (default: ./wallets)

Genera archivos .ukey con el nombre <wallet-address>.ukey.

cmd/register_wallets

Envía transactions TX_CREATE_WALLET para todas las billeteras del directorio de billeteras.

go run ./cmd/register_wallets [flags]

Flags:
  --config  Path to network config JSON (default: local-network.json)
  --dir     Wallet directory to register (default: ./wallets)

Lee los archivos de billetera, construye los payloads de TX_CREATE_WALLET, los firma con la clave privada de cada billetera, los envía a la chain y hace polling para la confirmación.

cmd/alter_wallets

Envía transactions ALTER_WALLET a partir de la configuración de billeteras.

go run ./cmd/alter_wallets [flags]

Flags:
  --config  Path to alter config JSON

cmd/alter_entity

Envía transactions ALTER_ENTITY.

cmd/create_entities

Envía transactions CREATE_ENTITY a partir de la configuración de entities.

---

Test Harness de Extremo a Extremo

cmd/e2e_bootstrap: Paso 1

Descubre la configuración de la chain y aprovisiona las billeteras para la suite E2E.

go run ./cmd/e2e_bootstrap [flags]

Flags:
  --config              Path to bootstrap config JSON
  --skip-council-wait   Skip waiting for council formation

Qué hace:

1. Se conecta a los endpoints de los nodes y descubre el ID de la chain y el tipo de clave.
2. Genera y registra 7 billeteras de rol + firmantes de throughput.
3. Espera la formación del council (a menos que se omita).
4. Emite un archivo de configuración E2E validado + el comando exacto de cmd/e2e que debe ejecutarse a continuación.

Se ejecuta una vez al configurar un nuevo clúster de pruebas.

cmd/e2e: Paso 2

Ejecuta la suite E2E completa.

go run ./cmd/e2e [flags]

Flags:
  --config           Path to E2E config JSON (output from e2e_bootstrap)
  --only             Comma-separated list of domains to run (token,contract,walletops,data,council)
  --skip-throughput  Skip the throughput burst phase

Fases:

1. Preflight (verificación de salud del clúster)
2. Las suites de dominio se ejecutan de forma concurrente (token, contract, walletops, data, council)
3. Settle (esperar a que todas las transactions se confirmen)
4. Ráfaga de throughput
5. Settle nuevamente
6. Barrido de commits
7. Verificación de consistencia entre nodes (lectura desde un node distinto al del envío)

Termina con código 0 si todo pasa y 1 si algún dominio falla. Guarda un informe JSON con marca de tiempo en outputDir.

cmd/council: Dominio Único

Ejecuta únicamente la suite E2E del dominio council.

go run ./cmd/council --config council-setup.json

cmd/identity: Ciclo de Vida de Identidad

Ejecuta el ciclo de vida completo de identidad (DIDs, entities, recuperación, credenciales).

go run ./cmd/identity --config identities.json

Pasos: creación de DID, creación de entity, entity hija, modificación de metadatos, configuración de recuperación, lista de acceso, transferencia de propiedad, emisión de credenciales, ejecución de recuperación.

---

Ejecutores de Dominio Individuales (Utilidades Manuales Obsoletas)

Estos ejecutan transactions individuales sin polling. Han sido reemplazados por los ejecutores de dominio de la suite E2E. Se recomienda usarlos únicamente para pruebas rápidas puntuales.

Comando	Descripción
cmd/erc20	Una única operación ERC-20.
cmd/erc721	Una única operación ERC-721.
cmd/erc1155	Una única operación ERC-1155.
cmd/deploy_contracts	Despliega un contract sin polling.
cmd/invoke_contract	Invoca una función de un contract sin polling.
cmd/upgrade_rollback_contract	Actualiza o revierte un contract sin polling.

---

Utilidades

Comando	Descripción
cmd/test_suite	Ráfaga de throughput sin procesar para pruebas de carga en chains preregistradas.
cmd/test_block	Envía una transaction de bloque de prueba.
cmd/test_results	Lee y muestra un archivo JSON de informe de pruebas.
cmd/operator	Gestión de credenciales de operador.
cmd/transactions	Consulta y muestra el historial de transactions.
cmd/generate_token	Genera un token JWT para la autenticación de la API.

---

Esquema de Configuración

Configuración de Red (Base)

{
    "nodeEndpoints": ["http://localhost:8081", "..."],
    "keyType": "secp256k1",
    "blockchainId": "<hex-chain-id>",
    "verbose": false,
    "insecureSkipVerify": false
}

Campo	Tipo	Valor por defecto	Descripción
nodeEndpoints	array	requerido	URLs HTTP de los nodes validadores.
keyType	string	requerido	Algoritmo de clave de la chain.
blockchainId	string	requerido	ID de la chain de destino.
verbose	bool	false	Habilita el registro detallado del SDK.
insecureSkipVerify	bool	false	Omite la verificación TLS (solo para desarrollo).

Configuración E2E (Completa)

{
    "nodeEndpoints": [...],
    "blockchainId": "...",
    "chainKeyType": "mldsa87",
    "passphrase": "",
    "outputDir": "./e2e_runs",
    "endpointStrategy": "roundrobin",
    "poll": {
        "intervalSeconds": 1,
        "timeoutSeconds": 80
    },
    "settle": {
        "intervals": 3,
        "intervalSeconds": 2
    },
    "throughput": {
        "count": 200,
        "intervalMs": 250,
        "concurrent": 100
    },
    "consistency": {
        "nodeIndex": 1
    },
    "domains": {
        "token": {
            "enabled": true,
            "wallets": {
                "owner": "./wallets/<hash>.ukey",
                "counterparty": "./wallets/<hash>.ukey",
                "spender": "./wallets/<hash>.ukey"
            }
        },
        "contract": {
            "enabled": true,
            "wallets": {
                "owner": "./wallets/<hash>.ukey",
                "other": "./wallets/<hash>.ukey"
            }
        },
        "walletops": {
            "enabled": true,
            "wallets": {
                "root": "./wallets/<hash>.ukey"
            }
        },
        "data": {
            "enabled": true,
            "wallets": {
                "sender": "./wallets/<hash>.ukey"
            }
        },
        "council": {
            "enabled": true,
            "sources": {
                "address": "<deployed-contract-address>"
            },
            "wallets": {
                "owner": "./wallets/<hash>.ukey",
                "member:alice": "./wallets/<hash>.ukey",
                "member:bob": "./wallets/<hash>.ukey",
                "agent:alice": "./wallets/<hash>.ukey",
                "agent:bob": "./wallets/<hash>.ukey"
            }
        }
    }
}

Estrategia de Endpoints

Valor	Comportamiento
roundrobin	Distribuye los envíos entre todos los endpoints en orden.
random	Elige un endpoint aleatorio para cada envío.
single	Usa únicamente el primer endpoint.

Roles de Billetera Requeridos por Dominio

Dominio	Roles Requeridos
token	owner, counterparty, spender
contract	owner, other
walletops	root
data	sender
council	owner, member:* (N miembros), agent:* (N agentes)

Aislamiento de billeteras: Ninguna dirección de billetera puede aparecer en más de un dominio. El validador de configuración lo hace cumplir.

---

Formato del Archivo de Billetera (.ukey)

El archivo .ukey contiene el material de clave privada de la billetera, codificado según el algoritmo de clave. Los campos varían según el algoritmo.

{
    "address": "<wallet-address>",
    "keyType": "mldsa87",
    "publicKey": "<hex>",
    "privateKey": "<hex>",
    "mnemonic": "<BIP39 mnemonic phrase>",
    "passphrase": ""
}

Las billeteras protegidas con passphrase cifran los bytes de la clave privada. Una passphrase vacía significa que no están cifradas.

---

Resumen de Paquetes del SDK

Paquete	Propósito
pkg/wallet	Cargar una billetera desde un archivo .ukey, derivar la dirección, firmar.
pkg/transaction	Construir y firmar payloads de transaction para todos los tipos de TX.
pkg/txconfirm	Hacer polling del receipt de una transaction con timeout configurable.
pkg/e2e	Motor del pipeline E2E: carga de configuración, ejecutores de dominio, informes.
pkg/bootstrap	Aprovisionamiento de billeteras para la configuración E2E.
pkg/council	Ejecutor del dominio council: alta de miembros, autorización de agentes, ciclo de vida de propuestas.
pkg/identity	Ciclo de vida de identidad: DIDs, entities, recuperación, credenciales.
pkg/credential	Emisión de VC, codificación JWT, gestión de listas de estado.
pkg/token	Ejecutor del dominio token: operaciones ERC-20/721/1155.
pkg/contract	Ejecutor del dominio contract: despliegue, invocación, actualización, rollback.
pkg/walletops	Dominio de operaciones de billetera: creación de árboles, otorgamiento de auth, deshabilitación en cascada.
pkg/data	Ejecutor del dominio data: round-trip byte a byte, payload grande, deduplicación.
pkg/crypto	Generación de claves, firma y verificación para todos los algoritmos admitidos.
pkg/auth	Autenticación basada en desafíos, emisión de JWT.
pkg/operator	Gestión de credenciales de operador.
pkg/audit	Utilidades de verificación de auditoría.
pkg/utils	Cliente HTTP, lógica de reintentos, utilidades JSON.

---

Lectura de Informes E2E

Los informes se guardan como archivos JSON con marca de tiempo en outputDir:

e2e_runs/
  report_2026-10-16T14:23:45Z.json

Estructura del informe:

{
    "timestamp": "2026-10-16T14:23:45Z",
    "passed": true,
    "domains": {
        "token": { "passed": true, "steps": [...] },
        "contract": { "passed": true, "steps": [...] },
        "walletops": { "passed": true, "steps": [...] },
        "data": { "passed": true, "steps": [...] },
        "council": { "passed": true, "steps": [...] }
    },
    "throughput": {
        "submitted": 200,
        "confirmed": 200,
        "durationMs": 4200,
        "tps": 47.6
    },
    "negativeTests": {
        "passed": true,
        "results": [...]
    }
}

Los pasos marcados con "denied": true en los resultados de las pruebas negativas se reportan como PASS; el comportamiento esperado es el rechazo.

---

Dependencias

Dependencia	Propósito
github.com/cloudflare/circl	Criptografía post-cuántica: ML-DSA-87, BLS12-377.
github.com/consensys/gnark-crypto	Operaciones de curva elíptica: secp256k1, Ed25519.
github.com/tyler-smith/go-bip39	Generación de mnemónicos BIP39 para la entropía de las billeteras.
github.com/google/uuid	Generación de UUID para los IDs de solicitud.
golang.org/x/crypto	AES, SHA3 y otras primitivas criptográficas estándar.
github.com/urfave/cli/v3	Análisis de flags de CLI para todas las herramientas de línea de comandos.