Skip to content

API del Servidor

⏱ 7 min de lectura

El servidor es un microservicio Express que expone una API HTTP sobre los contratos del protocolo. Cada endpoint pasa por un middleware que define cómo se autentica la petición y cómo se ejecuta la operación en la cadena:

  • Lectura: consulta el estado de un contrato sin firmar nada.
  • Operación de usuario: el usuario firma desde su cuenta inteligente.
  • Operación de servidores: la ejecutan los servidores firmadores del tren (TRAIN).
  • Operación de quórum: requiere el consenso de varios servidores y deja un registro de firmas en MongoDB.

Instalación:

  1. Debes clonar el servidor institucional desde el Github oficial de Lineal Qorum:
Terminal window
git clone https://github.com/lineal-qorum/signer-server.git
cd signer-server

Inicia el contenedor con la variable de entorno de name “tecne | ache | agora | ethos”.

  1. Crea un archivo .env y agrega las variables “INSTITUTION_ID”, “INSTITUTION_ADDRESS” y “MONGO_URL” (importante para registro off-chain).
  1. Levanta el contenedor con docker:
Terminal window
docker compose up -d

Debes desplegar 4 contenedores diferentes. Para desarrollo puedes usar todos en una sola máquina. Para producción cada servidor debe estar en nubes y regiones diferentes de disponibilidad.

flowchart LR
    C[Cliente] --> A[authMiddleware]
    A --> M{Middleware de la ruta}
    M -->|Lectura| R[readStateMiddleware]
    M -->|Usuario| U[userOperation]
    M -->|Servidores| S[onlyServers]
    M -->|Quórum| Q[onlyQorum]
    R --> K[(Contrato)]
    U --> K
    S --> K
    Q --> K

Todos los endpoints POST reciben un JSON con la función del contrato a invocar:

{
"contractName": "LinealBank",
"contractAddress": "0x...",
"functionName": "deposit",
"args": [],
"servers": ["demos", "nomos"]
}

Ejemplo de uso de operación de usuario:

app.post('/bank/deposit', userOperation, async (req, res) => {
try {
// Agrega tu lógica acá
return res.status(201).json({ success: true, result: req.results });
} catch (err) {
console.error('error:', err);
return res.status(500).json({ error: err.message });
}
});

Ejemplo de uso de operación Qorum:

app.post('/bank/realease-from-bank', onlyQorum, async (req, res) => {
try {
// Agrega tu lógica acá
return res.status(201).json({ success: true, result: req.doc });
} catch (err) {
console.error('error:', err);
return res.status(500).json({ error: err.message });
}
});
Campo Tipo Descripción
contractName string Nombre del contrato. En las rutas de quórum y servidores también es el nombre de la colección donde se registra la acción.
contractAddress string Dirección del contrato.
functionName string Función a invocar.
args array Argumentos de la función. Debe ser un arreglo.
servers array Servidores a los que se envía la operación (rutas de quórum y servidores).

Éxito (201):

{ "success": true, "result": { } }

Error:

{ "error": "mensaje" }
Código Significado
400 args no es un arreglo, o contractName inválido.
401 Token no proporcionado, inválido o expirado.
402 Wallet o servidor no autorizado (middlewares de autorización).
403 Usuario no autorizado (unauthorizedMiddleware).
500 Error interno.
Cabecera La usan
q-user-token authMiddleware, readStateMiddleware, userOperation, onlyServers
q-institution-token onlyServers (alternativa a q-user-token)
q-server-token unauthorizedMiddleware
authorization onlyQorum, actionsMiddleware, actionMiddleware

Los tokens se validan contra los servidores del tren mediante Signer.getUserWallet(TRAIN, token).

Middleware Cabecera Qué hace Deja en req
authMiddleware q-user-token Valida el token y comprueba que la cuenta esté autorizada (AuthorizedServer). Se aplica a todas las rutas. user
authMachineMiddleware (máquina) Conecta la máquina del servidor y comprueba su autorización. wallet, doc
unauthorizedMiddleware q-server-token Valida el token de un servidor y verifica AuthorizedServer y AuthorizedWallet de la wallet de la ruta. user
readStateMiddleware q-user-token Lee el estado de un contrato con Contract.readState. wallet, doc
userOperation q-user-token Comprueba que la wallet esté autorizada y envía la operación firmada por el usuario a los servidores del tren. wallet, result
onlyServers q-user-token o q-institution-token Registra la acción, envía la operación a los servidores indicados y avanza el tren de firmas. wallet, server, result
onlyQorum authorization Igual que onlyServers, pero para operaciones que exigen quórum de servidores. wallet, server, result
actionsMiddleware authorization Consulta el registro de acciones de un contrato. wallet, doc
actionMiddleware authorization Consulta una acción por su id. wallet, doc

onlyQorum y onlyServers registran cada operación en una colección de MongoDB (una por contractName) y coordinan la firma de los servidores.

Constante Valor Descripción
REQUIRED_SIGNATURES 3 Servidores que deben firmar para completar la acción.
POOL_SIZE 1 Servidores que se procesan por ronda.
HASHES_PER_SERVER 3 Hashes de transacción que debe devolver cada servidor.
REQUIRED_HASHES 9 REQUIRED_SIGNATURES × HASHES_PER_SERVER.
STALE_SIGNING_MS 4 min Tiempo tras el cual un paso en signing se considera vencido.
Campo Tipo Descripción
contractName, contractAddress, functionName string Identifican la operación.
args array Argumentos de la función.
status pending | completed Estado global de la acción.
signCount number Firmas acumuladas.
required number Firmas requeridas (por defecto 3).
steps[] objeto Un paso por servidor del tren.
signatures[] objeto Registro de quién firmó: wallet, receipt, signedAt.

Cada elemento de steps tiene server, status, users, receipt, error, claimedAt y signedAt.

stateDiagram-v2
    [*] --> waiting
    waiting --> signing: reclamo atómico
    failed --> signing: reintento
    signing --> signing: vencido (>4 min), se reclama de nuevo
    signing --> signed: 3 hashes válidos
    signing --> failed: error o hashes incompletos
    signed --> [*]
  1. Reclamo atómico: un servidor pasa a signing solo si estaba en waiting, failed o signing vencido. Evita que dos procesos firmen el mismo paso.
  2. Validación: el servidor debe devolver exactamente HASHES_PER_SERVER hashes. Si no, el paso queda en failed con el error.
  3. Registro: al firmar, el paso pasa a signed, se guarda el recibo, se agrega la wallet a users y signatures, y se incrementa signCount.
  4. Elección de servidor (nextPool): continúa después del último servidor intentado, salta los ya firmados y vuelve al primero al llegar al final del tren. No pide más servidores de los que faltan para llegar a REQUIRED_SIGNATURES.
  5. Ocupado: si hay un paso en signing que no ha vencido, no se inicia otro.
  6. Completado: al alcanzar REQUIRED_SIGNATURES firmas, la acción pasa a completed.

extractHashes(receipt) acepta un arreglo de strings o un objeto con hashes, transactionHashes o receipt, y descarta lo que no sea texto.

Todas las rutas pasan antes por authMiddleware. Salvo que se indique lo contrario, son POST.

Ruta Método Middleware Descripción
/ GET authMachineMiddleware Estado del servicio y de la conexión a la base de datos.
/identity GET authMiddleware Devuelve la dirección del usuario autenticado.
/wallet/unautorize/:wallet GET unauthorizedMiddleware Verifica la autorización de una wallet.
/actions/:contractName/:contractAddress GET actionsMiddleware Registro de acciones de un contrato.
/action/:contractName/:id GET actionMiddleware Una acción por id.

Operaciones de los servidores (onlyServers):

Ruta
/institution/set-token-support
/institution/set-pair-token
/institution/set-citizens-address
/institution/create-subaccount
/institution/move-founds-to-subaccount
/institution/move-founds-to-bank
/institution/realease-from-bank
/institution/mint-tender
/institution/mint-profile
/institution/update-identity-score
/institution/set-description

Lecturas (readStateMiddleware):

Ruta
/institution/get-directiva
/institution/get-subaccounts
/institution/get-institution-bank
/institution/get-institution-tender
/institution/get-identity
/institution/get-rewards-accoun-id
/institution/get-bank-tokens
/institution/get-account-balances
Ruta Middleware
/bank/is-token-supported readStateMiddleware
/bank/get-account-balances readStateMiddleware
/bank/account-of readStateMiddleware
/bank/account-balance readStateMiddleware
/bank/account-balances-all readStateMiddleware
/bank/token-list readStateMiddleware
/bank/total-reserve-balance readStateMiddleware
/bank/deposit userOperation
/bank/release-from-my-account userOperation
/bank/move-from-my-account userOperation
/bank/interbank-transfer-from-my-account userOperation
/bank/move-founds-to-bank onlyQorum
/bank/realease-from-bank onlyQorum
/bank/release-pre-sale onlyQorum

Todas con readStateMiddleware:

Ruta
/citizens/get-profile
/citizens/get-profile-by-token
/citizens/get-token-counter
/citizens/get-reputation
/citizens/sub-account-of
/citizens/token-uri
Ruta Middleware
/liquidity/pause readStateMiddleware
/liquidity/unpause readStateMiddleware
/liquidity/launch-seed onlyServers
/liquidity/launch-pre-seed onlyServers
/liquidity/withdraw-unsold-token onlyServers
Ruta Middleware
/milestones/cancel-milestone onlyQorum
/milestones/vote readStateMiddleware
/milestones/finalice readStateMiddleware
/milestones/idp readStateMiddleware
/milestones/milestone-count readStateMiddleware
Ruta Middleware
/router/set-fee-splitter onlyServers
/router/pause onlyServers
/router/unpause onlyServers
/router/distribute-revenue onlyServers
/router/get-receipts-count onlyServers
/router/get-all-receipts onlyServers
/router/set-distribuiton onlyQorum
/set-distribuiton onlyQorum

Todas con onlyQorum:

Ruta
/seed/buy
/seed/finalize
/seed/claim
/seed/refund
/seed/withdraw-funds
/seed/withdraw-unsold-tokens
/seed/claimable
/seed/total-raised
/seed/total-sold
/seed/total-claimed
/seed/finalized
/seed/succesfull
/seed/contributed
/seed/purshased
/seed/claimed

Todas con onlyQorum:

Ruta
/token/pause
/token/unpause
/token/set-white-list
/token/set-black-list
/token/launch-pre-seed
/token/launch-seed
/token/set-daily-limits
/token/set-reserve-bank
/token/recovery-funds
/token/transfer
/token/transfer-from
/token/approve
/token/balance-of
/token/allowance
/token/total-supply
/token/get-circulating-supply
/token/is-white-listed
/token/is-black-listed
/token/get-daily-transfer-volume
/token/get-daily-mint-burn-volume
/token/get-mint-history-length
/token/get-burn-history-length
Variable Uso
MONGODB_URI Cadena de conexión a MongoDB.
SERVER_NAME Nombre del servidor dentro de la red.
SERVER_DOMAIN Dominio del servidor.