Arquitectura General
⏱ 6 min de lectura
flowchart TD
subgraph GOV["Governance"]
LQ["LinealQorum\n(abstract)"]
LQA["LinealQantum †\n(abstract, gobernanza)"]
end
subgraph KERN["Kernel"]
LK["LinealKernel"]
end
subgraph ECO["Economy"]
subgraph TOKEN["Token"]
LT["LinealToken\n(ERC20 stablecoin)"]
end
subgraph BANK["Banks"]
LB["LinealBank"]
LTX["LinealTransactions"]
LBQ["LinealQantum\n(banks, abstract)"]
end
subgraph LIQ["Liquidity"]
LL["LinealLiquidity\n(orquestador)"]
LD["LinealDex †\n(AMM x*y=k)"]
LM["LinealMilestones †\n(IDP voting)"]
LS["LinealSeed †\n(ICO/vesting)"]
end
subgraph PM["Paymasters"]
LP["LinealPaymaster †"]
LR["LinealRouter\n(fee splitter)"]
end
subgraph ACC["Accounts (ERC-4337)"]
LA["LinealAccount †"]
LAF["LinealAccountFactory †"]
end
end
subgraph INST["Institution"]
LI["LinealInstitution"]
LC["LinealCitizens\n(ERC721 soulbound)"]
LTend["LinealTender\n(ERC721 licitaciones)"]
end
subgraph SOC["Social"]
LSTG["LinealStorage †\n(PostBoard)"]
end
subgraph CORE["Core (ERC-4337)"]
EP["EntryPoint"]
BA["BaseAccount"]
BP["BasePaymaster"]
LD2["LinealDeployer"]
end
LQ --> LT
LQ --> LI
LQ --> LL
LQ --> LR
LQ --> LM
LQ --> LK
LQ --> LSTG
LBQ --> LTX
LTX -->|"executeTransactionRelease"| LB
LI -->|"despliega"| LB
LI -->|"despliega"| LTend
LI -.->|"setCitizensAddress"| LC
LI -.->|"valida institución y coins"| LK
LL --> LT
LL --> LD
LL --> LM
LL --> LS
LL --> LR
LL --> LI
LL --> LB
EP --> LA
BA --> LA
BP --> LP
LAF --> LA
VI. Mecanismo de Quórum
Section titled “VI. Mecanismo de Quórum”Todos los contratos administrativos heredan de LinealQorum, un multisig de tres capas, salvo LinealTransactions, que hereda la variante LinealQantum del módulo de banks.
| Capa | Tipo | signerType |
|---|---|---|
| 1 — Machines | Nodos/servers automatizados | 1 |
| 2 — Institutions | Firmantes institucionales | 2 |
| 3 — Humans | Firmantes humanos (directiva) | 3 |
Cada contrato define cuántas firmas necesita por capa (requiredMachines, requiredInstitutions, requiredHumans). La capa humana es opcional: si no se definen humanos, requiredHumans queda en cero.
VII. Modos de confirmación
Section titled “VII. Modos de confirmación”| Modo | Función interna | Se ejecuta cuando | Quién puede firmar |
|---|---|---|---|
| Servers | confirmServers |
machines ≥ requiredMachines y institutions ≥ requiredInstitutions |
Capas 1 y 2 (onlyServers) |
| Tripartito | confirm |
Las tres capas alcanzan su mínimo | Cualquier signer (onlyQorum) |
| ZK | confirmWithZK (LinealQantum) |
confirmaciones ≥ requiredSignatures, cada una con prueba válida |
Signers de lista plana |
IIX. Flujo de una acción
Section titled “IIX. Flujo de una acción”No hay funciones separadas de “proponer”, “confirmar” y “ejecutar”. Cada firmante llama a la misma función de negocio con los mismos parámetros. La primera llamada abre la propuesta, y la llamada que completa el quórum ejecuta el cambio en esa misma transacción.
sequenceDiagram
participant S1 as Signer 1 (máquina)
participant S2 as Signer N (institución o humano)
participant C as Contrato (hereda LinealQorum)
S1->>C: setWhitelist(account, true)
Note over C: txHash = _computeActionHash(...)<br/>confirm / confirmServers
C-->>S1: ActionProposed + ActionConfirmed (sin quórum, no ejecuta)
S2->>C: setWhitelist(account, true) con los mismos parámetros
C-->>S2: ActionConfirmed, quórum alcanzado
Note over C: isExecuted = true, nonce++<br/>la función continúa y aplica el cambio
El hash de la acción incluye el tipo, la dirección del contrato, el chainid, el hash de los parámetros y un nonce por tipo de acción:
keccak256(abi.encode( keccak256(bytes(actionType)), address(this), block.chainid, keccak256(params), actionNonce[actionType]))Cambiar un solo parámetro genera otra propuesta, y el nonce impide reutilizar una aprobación ya ejecutada.
IX. Recuperación de firmantes (LinealQorum)
Section titled “IX. Recuperación de firmantes (LinealQorum)”- Cualquier signer llama a
proposeRecoverycon los nuevos conjuntos de máquinas, instituciones y humanos y sus mínimos. - Otros signers llaman a
confirmRecovery. - Pasadas 2 horas (
RECOVERY_DELAY) y conconfirmaciones ≥ recoveryQuorum,executeRecoveryreemplaza los tres conjuntos.
X. LinealQantum (módulo banks): multifirma plana con ZK
Section titled “X. LinealQantum (módulo banks): multifirma plana con ZK”Lista plana de signers con requiredSignatures, y un guardian. Cada signer registra un quantumCommitment con setQuantumCommitment. Para confirmar una acción presenta una ZKProof (Groth16) cuyas señales públicas son:
| Índice | Señal |
|---|---|
[0] |
nullifier (anti-replay, se quema tras verificar) |
[1] |
commitment (debe coincidir con el registrado on-chain) |
[2] |
txHash (la acción concreta) |
[3] |
contractAddress (separación de dominio) |
[4] |
chainId (separación de dominio) |
[5] |
signerAddress (identidad del firmante) |
La rotación de signers (proposeRecovery, confirmRecovery, executeRecovery) la ejecuta el guardian, con confirmaciones hasta recoveryQuorum y la misma espera de 2 horas.
X. Capas del Protocolo
Section titled “X. Capas del Protocolo”Governance
Section titled “Governance”LinealQorum.sol
Section titled “LinealQorum.sol”Contrato abstracto base. Define las tres capas de firmantes, confirm y confirmServers, el hash de acciones con nonce, y la recuperación de firmantes con demora. Modificadores: onlyQorum (cualquier signer), onlyServers (capas 1 y 2) y onlyGuardian.
LinealQantum.sol (governance) †
Section titled “LinealQantum.sol (governance) †”Versión extendida del multisig con soporte nativo de ZK-proofs (Groth16). Usada por contratos que requieren mayor seguridad criptográfica.
Economy
Section titled “Economy”LinealToken.sol
Section titled “LinealToken.sol”Stablecoin regulada 1:1 respaldada por FIAT (CLP). Hereda ERC20, LinealQorum, Pausable.
| Característica | Detalle |
|---|---|
| KYC en entrada | mint solo hacia direcciones isWhitelisted y fuera de blacklist |
| Circulación libre | transfer y transferFrom no exigen whitelist |
| Blacklist reactiva | Bloquea envíos y recepciones. Administrada con setBlacklist (quórum de servers) |
| Burn | Solo desde direcciones whitelisted y fuera de blacklist |
| Mint / Burn | Solo linealLiquidityAddress puede ejecutarlos |
| Límite diario de transferencia | 27.000.000 tokens por dirección emisora |
| Límite diario de mint / burn | 100.000.000 tokens cada uno (globales) |
| Pausa | pause / unpause (Pausable) |
| Lanzamiento | launchPreSeed fija linealLiquidityAddress y acuña; launchSeed acuña la ronda seed (una sola vez cada uno) |
| Banco de reserva | setReserveBank, se fija una sola vez. mint y burn requieren que esté definido |
| Auditoría on-chain | mintHistory, burnHistory, recoveryHistory |
Recuperación de fondos (recoverFunds): exige quórum tripartito (onlyQorum + confirm). El origen debe estar en blacklist y el destino no. La razón es obligatoria. Usa _transfer interno, por lo que no consume el límite diario. Cada recuperación queda en recoveryHistory y se emite FundsRecovered con id, reason, authorizedBy y timestamp.
Vistas de transparencia: getRecoveryHistoryLength, getRecoveries(offset, limit), getMintHistoryLength, getBurnHistoryLength, getDailyTransferVolume, getDailyMintBurnVolume, getCirculatingSupply.
LinealAccount.sol †
Section titled “LinealAccount.sol †”Smart account ERC-4337 (Simple Account). Hereda BaseAccount, UUPSUpgradeable, Initializable. Soporta execute y executeBatch.
LinealAccountFactory.sol †
Section titled “LinealAccountFactory.sol †”Factory para LinealAccount vía CREATE2 + ERC1967Proxy. Retorna la dirección aunque ya esté desplegada.
Social
Section titled “Social”Core (ERC-4337) †
Section titled “Core (ERC-4337) †”| Contrato | Descripción |
|---|---|
EntryPoint.sol |
Punto de entrada ERC-4337 estándar |
BaseAccount.sol |
Base para smart accounts ERC-4337 |
BasePaymaster.sol |
Base para paymasters |
LinealDeployer.sol |
Deployer del protocolo |
GenesisVerifier.sol |
Verificador de génesis |
Groth16Verifier.sol |
Verificador ZK-SNARKs (Groth16) usado por LinealQantum |
NonceManager.sol |
Gestor de nonces para UserOps |
StakeManager.sol |
Gestor de stake para paymasters |
Tabla Resumen de Contratos
Section titled “Tabla Resumen de Contratos”| Contrato | Archivo | Hereda |
|---|---|---|
LinealQorum |
governance/LinealQorum.sol |
— |
LinealQantum (gov) † |
governance/LinealQantum.sol |
Groth16Verifier |
LinealKernel |
kernel/LinealKernel.sol |
LinealQorum |
LinealToken |
economy/token/LinealToken.sol |
ERC20, LinealQorum, Pausable |
LinealBank |
economy/banks/LinealBank.sol |
Ownable, ReentrancyGuard |
LinealTransactions |
economy/banks/LinealTransaction.sol |
LinealQantum (banks) |
LinealQantum (banks) |
economy/banks/LinealQantum.sol |
— (usa Groth16Verifier) |
LinealLiquidity |
economy/Liquidity/LinealLiquidity.sol |
LinealQorum, Pausable |
LinealDex † |
economy/Liquidity/LinealDex.sol |
ReentrancyGuard |
LinealSeed † |
economy/Liquidity/LinealSeed.sol |
Ownable, ReentrancyGuard |
LinealMilestones † |
economy/Liquidity/LinealMilestones.sol |
LinealQorum |
LinealPaymaster † |
economy/paymasters/LinealPaymaster.sol |
BasePaymaster |
LinealRouter |
economy/paymasters/LinealRouter.sol |
LinealQorum, Pausable |
LinealAccount † |
economy/accounts/LinealAccount.sol |
BaseAccount, UUPSUpgradeable |
LinealAccountFactory † |
economy/accounts/LinealAccountFactory.sol |
— |
LinealInstitution |
institution/LinealInstitution.sol |
LinealQorum |
LinealCitizens |
institution/LinealCitizens.sol |
ERC721, Ownable |
LinealTender |
institution/LinealTender.sol |
ERC721, Ownable |
LinealStorage † |
social/LinealStorage.sol |
LinealQorum |
Política LCL — Ley de Conservación de Liquidez
Section titled “Política LCL — Ley de Conservación de Liquidez”flowchart LR
A["unlockAndMint\n(quórum de servers)"] --> B["Alpha = reserva de ingresos del DEX\n/ suministro circulante"]
B -->|"Alpha < 0.93"| C["Buyback & Burn\n5% del saldo de ingresos del contrato"]
C --> D["LinealDex\nswap INCOME → QORUM"]
D --> E["QORUM quemado"]
B --> F{"Alpha ≥ 0.93\ne IDP ≥ 66"}
G["LinealMilestones\nIDP"] --> F
F -->|"sí"| H["Emisión = base × IDP% × LCL%"]
H --> I["LinealToken.mint\nhacia LinealRouter"]
I --> J["distributeRevenue\n(destinatarios por bps)"]
Alpha: índice de salud de liquidez. Si cae bajo 0,93, LinealLiquidity intenta un Buyback & Burn con el 5 % de su saldo de ingresos.
IDP (Índice de Desempeño): suma de pesos de hitos aprobados en LinealMilestones (0–100). Define qué porcentaje de la emisión base puede acuñarse.
Orden de puesta en marcha
Section titled “Orden de puesta en marcha”- Desplegar
LinealKernel. - Desplegar
LinealTokenyLinealInstitution. La institución despliega su banco y su contrato de licitaciones. - Desplegar
LinealCitizenscon la institución comoowner. - En el kernel:
registerInstitutionyregisterCoinpara cada coin. - En la institución:
setEconomicKernel,setCitizensAddressysetPairToken. SisetEconomicKernelse ejecuta antes del paso 4, las operaciones revierten conInstitutionNotEnabledoCoinNotValid. - En el token:
setReserveBank,launchPreSeed(definelinealLiquidityAddress) ysetWhitelistpara las direcciones que recibenmint, para la dirección deLinealLiquidityy para elLinealRouter. - Fondear la cuenta de la institución en el banco con
linealCoinantes de emitir perfiles: los primeros 25.000 reciben 50 unidades. - En cada banco que reciba transferencias, habilitar la coin con
setTokenSupport.
Eventos Clave por Módulo
Section titled “Eventos Clave por Módulo”Governance
Section titled “Governance”| Contrato | Evento |
|---|---|
LinealQorum |
ActionProposed, ActionConfirmed, ActionExecuted, GuardianUpdated, RecoveryProposed, RecoveryConfirmed, RecoveryExecuted |
LinealQantum |
ActionProposed, ActionConfirmed, ActionExecuted, SignersRotated, GuardianUpdated, QuantumCommitmentUpdated, RecoveryProposed, RecoveryConfirmed, RecoveryExecuted |
Kernel
Section titled “Kernel”| Contrato | Evento |
|---|---|
LinealKernel |
IssuerAuthorized, IssuerDeauthorized, BankRegistered, BankDeregistered, InstitutionRegistered, InstitutionProfileUpdated, InstitutionRemoved, CoinRegistered, CoinRemoved, DnsAuthorized, DnsRevoked, AppAuthorized, AppRevoked |
Economy
Section titled “Economy”| Contrato | Evento |
|---|---|
LinealToken |
Transfer, Minted, Burned, AddressWhitelisted, AddressBlacklisted, ReserveBankSet, DailyLimitsUpdated, FundsRecovered(id, from, to, amount, reason, authorizedBy, timestamp) |
LinealBank |
TokenSupportChanged, TokenDeposited, TokenReleased, InternalTransfer, CitizenTransfer, BankTransfer, RewardsFeeCharged, RewardsAccountSet, SubAccountCreated, PersonalAccountCreated, TransactionManagerSet |
LinealTransactions |
TransactionCreated, TransactionCancelled, AdministrativeAuthorized, StaticMultiSigCompleted, TransactionExecuted |
LinealLiquidity |
UnlockExecuted(amount, alpha, idp), BuybackAndBurn(incomeSpent, qorumsBurned) |
LinealRouter |
RevenueDistributed, RecipientPaid, DistributionUpdated |
LinealMilestones † |
MilestoneCreated, Voted, MilestoneClosed |
Institution
Section titled “Institution”| Contrato | Evento |
|---|---|
LinealInstitution |
BankLinked, TendersLinked, IdentityLinked, EconomicKernelLinked, TokenSupportSet, InstitutionAccountCreated, SubAccountCreated, FundsMovedToSubAccount, FundsMovedToBank, FundsReleased, PreFundsReleased, ProfileIssued, CitizenAccountCreated, ProfileImageUpdated, TenderIssued, TenderAccountCreated, DescriptionUpdated |
LinealCitizens |
ProfileIssued(wallet, tokenId, username, subAccountId), ScoreUpdated, ProfileImageUpdated |
LinealTender |
TenderMinted, TenderUpdated, TenderStatusChanged |
Errores Personalizados
Section titled “Errores Personalizados”// LinealBankerror InvalidSubAccount();error Bank_Unauthorized();error Bank_InvalidAccount();error Bank_InvalidAddress();error Bank_InvalidToken();error Bank_InvalidBps();error Bank_ZeroAmount();error Bank_InsufficientBalance();error Bank_TransactionNotExecuted();error Bank_IdentityNotLinked();error Bank_NoAccount(); // la wallet no tiene perfil en LinealCitizenserror Bank_PersonalAccount(); // intento de mover una cuenta personal con funciones del ownererror Bank_TokenNotSupported();
// LinealInstitutionerror BankNotLinked();error TendersNotLinked();error InvalidSubAccount();error InvalidDestBank();error InvalidToken();error InvalidKernel();error InstitutionNotEnabled();error CoinNotValid(address token);
// LinealKernelerror InvalidAddress();error NotAContract();error InvalidName();error DescriptionTooLong();error InvalidImageUrl();error InstitutionAlreadyRegistered();error InstitutionNotFound();error InvalidCoin();error CoinAlreadyRegistered();error CoinNotFound();error InvalidDns();error InvalidAppId();error AlreadyAuthorized();error NotAuthorized();error TooManyEntries();
// LinealTendererror InvalidAddress();error EmptyTitle();error TitleTooLong(); // MAX_TITLE_LENGTH = 100 byteserror EmptyDescription();error EmptyImageURI();error EmptyDocumentURL();error TenderDoesNotExist();error NonTransferable();error InvalidAmount();error InvalidSubAccount();