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:
- Debes clonar el servidor institucional desde el Github oficial de Lineal Qorum:
git clone https://github.com/lineal-qorum/signer-server.gitcd signer-serverInicia el contenedor con la variable de entorno de name “tecne | ache | agora | ethos”.
- Crea un archivo .env y agrega las variables “INSTITUTION_ID”, “INSTITUTION_ADDRESS” y “MONGO_URL” (importante para registro off-chain).
- Levanta el contenedor con docker:
docker compose up -dDebes 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
Convenciones
Section titled “Convenciones”Cuerpo de la petición
Section titled “Cuerpo de la petición”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). |
Respuesta
Section titled “Respuesta”É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. |
Cabeceras de autenticación
Section titled “Cabeceras de autenticación”| 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).
Middlewares
Section titled “Middlewares”| 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 |
Flujo de firma por quórum
Section titled “Flujo de firma por quórum”onlyQorum y onlyServers registran cada operación en una colección de MongoDB (una por contractName) y coordinan la firma de los servidores.
Constantes
Section titled “Constantes”| 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. |
Esquema del documento de acción
Section titled “Esquema del documento de acción”| 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. |
Pasos por servidor
Section titled “Pasos por servidor”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 --> [*]
Algoritmo
Section titled “Algoritmo”- Reclamo atómico: un servidor pasa a
signingsolo si estaba enwaiting,failedosigningvencido. Evita que dos procesos firmen el mismo paso. - Validación: el servidor debe devolver exactamente
HASHES_PER_SERVERhashes. Si no, el paso queda enfailedcon el error. - Registro: al firmar, el paso pasa a
signed, se guarda el recibo, se agrega la wallet ausersysignatures, y se incrementasignCount. - 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 aREQUIRED_SIGNATURES. - Ocupado: si hay un paso en
signingque no ha vencido, no se inicia otro. - Completado: al alcanzar
REQUIRED_SIGNATURESfirmas, la acción pasa acompleted.
Extracción de hashes
Section titled “Extracción de hashes”extractHashes(receipt) acepta un arreglo de strings o un objeto con hashes, transactionHashes o receipt, y descarta lo que no sea texto.
Endpoints
Section titled “Endpoints”Todas las rutas pasan antes por authMiddleware. Salvo que se indique lo contrario, son POST.
Sistema
Section titled “Sistema”| 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. |
Lineal Institution
Section titled “Lineal Institution”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 |
Lineal Bank
Section titled “Lineal Bank”| 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 |
Lineal Citizens
Section titled “Lineal Citizens”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 |
Lineal Liquidity
Section titled “Lineal Liquidity”| Ruta | Middleware |
|---|---|
/liquidity/pause |
readStateMiddleware |
/liquidity/unpause |
readStateMiddleware |
/liquidity/launch-seed |
onlyServers |
/liquidity/launch-pre-seed |
onlyServers |
/liquidity/withdraw-unsold-token |
onlyServers |
Lineal Milestones
Section titled “Lineal Milestones”| Ruta | Middleware |
|---|---|
/milestones/cancel-milestone |
onlyQorum |
/milestones/vote |
readStateMiddleware |
/milestones/finalice |
readStateMiddleware |
/milestones/idp |
readStateMiddleware |
/milestones/milestone-count |
readStateMiddleware |
Lineal Router
Section titled “Lineal Router”| 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 |
Lineal Seed
Section titled “Lineal Seed”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 |
Lineal Token
Section titled “Lineal Token”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 |
Variables de entorno
Section titled “Variables de entorno”| Variable | Uso |
|---|---|
MONGODB_URI |
Cadena de conexión a MongoDB. |
SERVER_NAME |
Nombre del servidor dentro de la red. |
SERVER_DOMAIN |
Dominio del servidor. |
