com_r35157_nenjim-hubd-impl_ref/docs/Evelyn.md

#<center><H1>Evelyn<br>Documentation</H1></center>

**Indholdsfortegnelse:**
<!-- TOC -->
  * [1. Introduktion formål og vision](#1-introduktion-formål-og-vision)
    * [1.1 Tokens som vedvarende aktiv – selv efter systemnedbrud](#11-tokens-som-vedvarende-aktiv--selv-efter-systemnedbrud)
  * [2. Tokenøkonomi og finansiering](#2-tokenøkonomi-og-finansiering)
    * [2.1 Allokering af overskud](#21-allokering-af-overskud)
    * [2.2 Buybacks og burn](#22-buybacks-og-burn)
    * [2.3 Finansiering af udvikling](#23-finansiering-af-udvikling)
    * [2.4 Ansvarsplacering og overskud](#24-ansvarsplacering-og-overskud)
    * [2.5 Neutralitet og ligestilling](#25-neutralitet-og-ligestilling)
    * [2.6 Vejen mod autonomi](#26-vejen-mod-autonomi)
  * [3. Tradingmotorens filosofi - AFETS](#3-tradingmotorens-filosofi---afets)
    * [3.1 Ikke-spekulativ tilgang](#31-ikke-spekulativ-tilgang)
    * [3.2 Søgning efter ligevægt](#32-søgning-efter-ligevægt)
    * [3.3 Anti-fragilitet](#33-anti-fragilitet)
  * [4. Trekantmodellen - Longs, Shorts og Margin](#4-trekantmodellen---longs-shorts-og-margin)
  * [5. Score-beregning – systemets beslutningsmotor](#5-score-beregning--systemets-beslutningsmotor)
    * [5.1 Principper for score-beregning](#51-principper-for-score-beregning)
    * [5.2 Beregning af score for åbning af positioner](#52-beregning-af-score-for-åbning-af-positioner)
    * [5.3 Straf for store positioner (penalty)](#53-straf-for-store-positioner-penalty)
    * [5.4 Beregning af score for lukning af positioner](#54-beregning-af-score-for-lukning-af-positioner)
    * [5.5 Fleksibilitet og udvikling](#55-fleksibilitet-og-udvikling)
  * [6. Iteration og rebalancering](#6-iteration-og-rebalancering)
  * [7. Likviditetsstyring og gearing](#7-likviditetsstyring-og-gearing)
    * [7.1 Tærskler og dvale](#71-tærskler-og-dvale)
  * [8. Risici, fail-safes og antifragilitet](#8-risici-fail-safes-og-antifragilitet)
  * [9. Udvikling, YouTrack-integration og offentlig gennemsigtighed](#9-udvikling-youtrack-integration-og-offentlig-gennemsigtighed)
  * [10. Fremtidige emner / TODO](#10-fremtidige-emner--todo)
<!-- TOC -->

## 1. Introduktion formål og vision
Evelyn er et proprietært trading-plugin bygget oven på AssetAZ-platformen. Evelyn er ikke open source og er
ikke designet til at blive kørt af andre. Ingen andre end udvikleren har, på nuværende tidspunkt, adgang til at
bruge, køre eller analysere den. Evelyn eksisterer udelukkende som en privat og beskyttet komponent i et større,
decentraliseret økosystem.

Der arbejdes hen imod, at Evelyn, med tiden, bliver en fuldt autonom enhed med egen kapital og kontrol, hvor ikke
engang udvikleren har adgang til beslutningstagen eller de midlerne – kun mulighed for at interagere
på lige fod med øvrige investorer.

Evelyn er ikke designet til at maksimere profit for ejeren i klassisk forstand. Evelyn er en blackbox, som
eksterne investorer kan interagere med. Al profit, Evelyn genererer gennem bl.a. trading, kanaliseres
tilbage i systemet: til egen drift (hosting, strøm og andre ressourcer), udvikling, polstring imod kriser,
styrkelse af likviditet i trading pools samt tilbagekøb af de 'Evelyn IOU' tokens investorerne har købt.
Den eneste kapital, der tilfalder Evelyn selv, er derfor kun den oprindelige likviditet skabt, da tokens
blev solgt på det åbne marked – det, man kan betragte som hovedstolen på de gældsbeviser, Evelyns IOU tokens
repræsenterer.
Evelyn selv tjener ikke på trading, men bruger trading som et værktøj til at styrke systemet og servicere sine
gældsforpligtelser.
Når Evelyn senere har opbygget en stor egenkapital, vil den anvende en del af denne kapital til filantropisk
støtte i samfundet.

Evelyn distribueres teknisk som enhver anden Nenjim-komponent, men er ikke offentligt registreret, hvilket gør
den praktisk talt usynlig for andre brugere. Denne designbeslutning understøtter Evelyns rolle som en blackbox
til kapitalopbygning og senere filantropisk støtte. Evelyn anvender AFETS-princippet for antifragilitet i sin
tradingstrategi og sikrer løbende systemstabilitet ved at geninvestere profit i likviditetsstyrkelse,
udvikling og opkøb af Evelyn IOU-tokens.

I fremtiden vil eksterne investorer, via tokens, kunne stemme om, hvilke projekter Evelyn skal støtte.

### 1.1 Tokens som vedvarende aktiv – selv efter systemnedbrud
En særlig egenskab ved Evelyns design er, at Evelyn tokens fortsætter med at eksistere og blive handlet på
decentraliserede børser, selv hvis Evelyn selv ophører med at fungere – f.eks. på grund af likvidering af alle
positioner eller markedsmæssige sammenbrud.

Det betyder, at investorers kapital ikke går tabt, selv hvis Evelyn som tradingmaskine fejler. Tokens kan stadig have
værdi og kan handles frit. Det giver mulighed for, at tokens over tid bliver købt op igen – ikke nødvendigvis af
Evelyn, men f.eks. af den oprindelige udvikler med anden indkomst, eller af markedet selv, hvis der opstår ny interesse.

Denne adskillelse mellem token og motor gør, at Evelyn ikke skaber afhængighed, men i stedet definerer en langsigtet
økonomisk kontrakt mellem projekt og investor, som potentielt kan indfries, selv hvis omstændighederne ændrer
sig drastisk.

## 2. Tokenøkonomi og finansiering
Evelyn bruger en intern token kaldet 'Evelyn IOU' som sin primære finansieringsmekanisme. Denne token er en form for
gældbevis, som Evelyn selv udsteder i de tilfælde, hvor der ikke er tilstrækkelig likviditet til at fortsætte
handelsaktiviteterne. Tokens bliver udstedt “ud af den blå luft” og solgt på en decentraliseret børs.
Provenuet fra salget bliver brugt direkte som handelskapital i systemet. Det er vigtigt at forstå, at 'Evelyn IOU'
ikke giver krav på en fast tilbagebetaling – det er en markedsbaseret mekanisme, hvor investorerne forventer at
kunne sælge deres tokens igen til en højere pris, efterhånden som Evelyn opnår overskud.

### 2.1 Allokering af overskud
Når Evelyn genererer overskud gennem sin tradingstrategi, bliver dette overskud automatisk allokeret i forskellige
procentandele til følgende områder:

1) Geninvestering i nye positioner
1) Reduktion af gearing (hvis anvendt)
1) Afbetaling af gæld for tidligere tab
1) Tilførsel af likviditet i Evelyn IOU-tokenets pool
1) Betaling for udvikling og vedligehold, samt drift af systemet
1) Buyback og burn af tokens

Fordelingerne er hardcoded og justeres manuelt af udvikleren, når behovet opstår. Evelyn foretager ikke selv
beslutninger om fordelingen. Det er et lukket kredsløb, hvor alt overskud anvendes til enten at styrke systemet,
sikre tokenens pris eller muliggøre ny funktionalitet.

### 2.2 Buybacks og burn
En af de vigtigste mekanismer i Evelyn er det automatiske tilbagekøb og efterfølgende burn af 'Evelyn IOU' tokens.
En fast procentdel af overskuddet anvendes på at købe tokens på markedet – uanset den aktuelle pris – og brænde
dem permanent. Dette reducerer det samlede udbud og skaber et kontinuerligt deflationært pres, hvilket typisk er
positivt for investorerne. Buyback-strategien sikrer, at investorerne får en god pris for deres tokens, når det
udnyttes at ikke alle investorer sælger på samme tid, da de har forskellige forventninger til prisen.

### 2.3 Finansiering af udvikling
Udvikling i Evelyn sker gennem en task-baseret model. Alle opgaver oprettes i IntelliJ YouTrack og bliver
individuelt prissat i 'Evelyn IOU'. Når en opgave er funded – enten af Evelyn selv (via overskud) eller af en
ekstern sponsor, påbegyndes arbejdet. Når opgaven er markeret som “Done”, udbetales den aftalte mængde tokens
til udvikleren. Alle transaktioner er offentligt synlige via SolScan, hvilket sikrer gennemsigtighed og gør det
muligt at verificere, at en opgave faktisk funded, gennemført og til sidst, betalt for.

Det betyder også, at eksterne investorer kan vælge at støtte specifikke funktioner, hvis de tror på Evelyns fremtid,
selv i perioder hvor Evelyn ikke selv har midler. Det gør tokenen både til en investeringsenhed og et værktøj til at
drive udvikling fremad.

### 2.4 Ansvarsplacering og overskud
Det er vigtigt at understrege, at al profit går til systemet og dets investorer – ikke til ejeren som personlig
gevinst. Den eneste kapital, der kan betragtes som tilhørende ejeren, er den oprindelige likviditet, der blev tilført,
da tokens blev solgt. Evelyn bruger alt efterfølgende overskud til at servicere sin egen gæld, styrke balancen og
understøtte videreudvikling.

### 2.5 Neutralitet og ligestilling
Selvom Evelyn er udviklet og ejet af én person, er selve systemets økonomiske struktur designet til at være neutral.
Hvis ejeren ønsker yderligere gevinst ud over den oprindelige hovedstol fra tokensalget, skal det ske ved at købe
Evelyn IOU-tokens på lige fod med alle andre investorer. Der er ingen bagdør, ingen særbehandling og ingen
skjulte fordele.

Systemet fungerer dermed næsten som et selvejende kredsløb, hvor udvikleren er en deltager på linje med alle andre.
Det er ikke systemets opgave at betale sin ejer – det er systemets opgave at holde balancen, betale sin gæld og
skabe værdi for markedet.

### 2.6 Vejen mod autonomi
Der er en overordnet ambition om, at Evelyn på sigt skal blive et fuldt selvforvaltende system, hvor ikke engang den
oprindelige udvikler har adgang til dens kapital. Det betyder, at den handelskapital, Evelyn genererer eller modtager
via tokensalg, ikke skal kunne trækkes ud af systemet af nogen – heller ikke ejeren.

Idealet er, at Evelyn på et tidspunkt fungerer som en økonomisk organisme med sin egen vilje. En enhed med egne midler,
egne prioriteter og egne beslutninger – hvor adgang til ressourcer kun kan opnås gennem markedet eller gennem faktisk
bidrag til systemet.

Udvikleren bliver i så fald ikke systemets ejer, men blot én deltager blandt andre, der kan tilbyde at løse opgaver
eller investere i tokens. Det er en ny måde at tænke softwareejerskab på: ikke som besiddelse, men som
fællesskab og udveksling.

## 3. Tradingmotorens filosofi - AFETS
Evelyn bygger hele sin handelsstrategi på det, der kaldes AFETS – Anti-Fragile Equilibrium Trading System. Systemet
er konstrueret til ikke blot at tåle markedets svingninger, men at blive stærkere af dem. Det er en strategi, hvor
målet ikke er spekulation eller profitmaksimering, men balancering. Evelyn forsøger ikke at forudsige fremtiden.
Den handler udelukkende på, hvad der er sandt lige nu.

### 3.1 Ikke-spekulativ tilgang
I modsætning til traditionelle tradingbots, der forsøger at gætte fremtidige prisbevægelser ud fra mønstre, nyheder
eller tekniske indikatorer, arbejder Evelyn retrospektivt. Den bygger sine beslutninger på observerede forhold
i nuet – og aldrig på spekulation. Det gør den ekstremt robust over for chok, kriser og nyhedsdrevne spikes, fordi
den ikke lader sig rive med af narrativer, der måske viser sig forkerte.

### 3.2 Søgning efter ligevægt
Hele grundideen i AFETS er at bevare en økonomisk ligevægt. Det betyder, at Evelyn hellere vil være stabil end
aggressiv. Den ser det som en styrke at overleve, ikke at vinde stort. Det gør systemet egnet til lang levetid
og kontinuerlig forbedring – og til at undgå store tab.

### 3.3 Anti-fragilitet
Konceptet om antifragilitet kommer fra Nassim Nicholas Taleb og beskriver systemer, der ikke bare er robuste,
men som faktisk vokser af kaos og stress. Evelyn søger netop dette: at komme styrket ud af udsving i markedet.
Når en ubalance opstår, bruger Evelyn muligheden for at lukke positioner med profit og styrke sin margin.
Når tingene vender, er den klar til at tage det næste sving med endnu større stabilitet.

Evelyn vinder altså ikke ved at være den hurtigste eller smarteste, men ved at være den mest tålmodige og
bedst balancerede. Det er ikke et system, der skal slå markedet – det er et system, der skal overleve og
tilpasse sig det.

## 4. Trekantmodellen - Longs, Shorts og Margin
Evelyn opererer med en unik model, hvor dens samlede kapital opdeles i tre hovedkomponenter: long-positioner,
short-positioner, og available margin. Disse tre komponenter udgør tilsammen en trekant, hvor hver side repræsenterer
en tredjedel af den samlede værdi. Målet er, at hver af balance imellem de tre dele altid tilstrebes, så hver side
af trekanten udgør cirka 33% af den samlede kapital.

Long-positionerne repræsenterer de handler, hvor Evelyn satser på, at værdien af et givent aktiv vil stige.
Short-positionerne er de handler, hvor Evelyn forventer, at værdien vil falde.
Available margin er den likvide kapital, som ikke er bundet i positioner, og som er klar til at blive brugt til nye
handler eller til at genoprette balance, hvis det bliver nødvendigt.

Når der opstår ubalance i trekanten, for eksempel hvis long-positionerne stiger i værdi og dermed fylder mere
end 33% af den samlede kapital, vil Evelyn iværksætte en rebalancering. Det gør den ved at lukke en del af de
kontrakter fra en af de overrepræsenterede positioner og føre værdien tilbage til 'available margin'.

I næste iteration kan Evelyn så vurdere, om available margin nu er for høj og derved bruge noget af den til at åbne
nye short-positioner for at genoprette balancen. Målet er altid at bringe alle tre komponenter tilbage til en
ligelig fordeling.

Når short-positionerne stiger i værdi (og derved er i tab), kan Evelyn stå i en situation, hvor den har svært ved at
lukke disse positioner uden at forværre ubalancen. For at håndtere dette, vil Evelyn typisk skiftevis lukke en long
og en short i en form for “tiptoe”-mønster. Denne metode gør det muligt for Evelyn at balancere sine positioner over
tid, uden at skabe pludselige, store udsving i systemet.

## 5. Score-beregning – systemets beslutningsmotor
Score-beregningen er hjertet i Evelyns beslutningsproces. Når Evelyn skal vælge, hvilke positioner der skal åbnes
eller lukkes, bruger den en scorefunktion til at vurdere alle muligheder objektivt og konsekvent. Formålet er at
vælge den position, der skaber mest balance og bedst forbedrer porteføljens risiko/profit-forhold.

### 5.1 Principper for score-beregning
- Evelyn vurderer altid alle kandidater (f.eks. alle mulige nye kontrakter, eller alle åbne positioner, der kan lukkes).
- For åbning af positioner bruges både markedsdata (pris, kontraktstørrelse, gearing mv.) og et strafsystem, så ingen
positioner bliver for store i forhold til de andre.
- For lukning af positioner er scoren pt. simplere (procentuel gevinst/tab), men kan udvikles videre i fremtiden.

### 5.2 Beregning af score for åbning af positioner
Når en ny kontrakt skal vælges, samles alle relevante input i en record (se kode-eksempel i appendiks). Beregningen
vurderer blandt andet:
- Hvilken profitforbedring opnås, hvis prisen udvikler sig fra nuværende til “efter trade”-niveau?
- Hvor stor er profitten i forhold til den kapital, der bruges?
- Hvor meget spredes risikoen ved at vælge denne position frem for at forstørre eksisterende?

Eksempel på scoring:
- Beregn forskel mellem nuværende og fremtidig pris for aktivet (alt efter om det er en long eller short)
- Udregn profit for denne prisændring
- Relativ profit (profit pr. dollar brugt)
- Summér til en endelig score: score = 1 + (relativ profit)

### 5.3 Straf for store positioner (penalty)
For at undgå, at Evelyn bygger uforholdsmæssigt store positioner i ét aktiv, justeres scoren nedad for de kandidater,
hvor den nuværende position allerede er større end gennemsnittet. Straf-funktionen dæmper scoren med en faktor,
der vokser med afvigelsen fra gennemsnittet:

- Hvis positionen > gennemsnittet, så:
- adjustedScore = rawScore / (1 + K * (ratio-1)^2)

Her er K en justerbar parameter, der bestemmer, hvor hårdt store positioner straffes.

### 5.4 Beregning af score for lukning af positioner
For at lukke positioner anvender Evelyn pt. en simpel score baseret på den procentuelle gevinst eller tab,
positionen har. Listen af potentielt lukkede positioner sorteres på denne score, og den bedste vælges.

### 5.5 Fleksibilitet og udvikling
Alle scorefunktioner er implementeret, så de kan udskiftes, tunes og forbedres uden at bryde resten af systemet.
Det gør det let at eksperimentere med nye logikker og justere for mere optimal risikospredning eller
profitforbedring over tid.

## 6. Iteration og rebalancering
Evelyn arbejder i faste iterationer, hvor den med jævne mellemrum – for eksempel hver time – evaluerer sine
positioner. I hver iteration summerer Evelyn værdien af alle longs, alle shorts og den available margin for
at sikre, at de tre komponenter er i balance. Hvis for eksempel long-positionerne bliver for store i forhold
til de to andre dele, vil Evelyn lukke nogle af disse positioner og føre værdien tilbage til den available
margin. Dette sikrer, at der ikke opstår en skævvridning, som kan true systemets stabilitet.

Rebalanceringen foregår altid med forsigtighed for at undgå overreaktioner, og justeres i små skridt, så systemet
altid er i stand til at absorbere markedsudsving uden at tabe balancen.

## 7. Likviditetsstyring og gearing
Evelyns likviditetsstyring er bygget op omkring klare tærskler og trin:
- Normalt drift: Systemet forsøger at holde available margin på ca. 33%. Det sker ved balancering mellem long-,
short-positioner og likvide midler.
- Faldende tilgængeling margin: Hvis available margin falder under et defineret threshold (fx 10%), begynder Evelyn
at øge gearingen på eksisterende positioner. Det frigør kapital, men bruges kun til at holde margin på minimum,
ikke til at tage flere handler.
- Kritisk lav margin: Hvis gearing ikke kan øges yderligere, og marginen rammer 0%, vil Evelyn udstede nye
'Evelyn IOU' tokens som sidste udvej for at skaffe ekstern likviditet.

Når markedet normaliseres, nedbringer Evelyn langsomt gearingen over tid, finansieret af trading-overskud. Det
betyder, at systemet efter en krise ikke straks går tilbage til spot-only, men gradvist heler balancen, lidt som
et brækket ben, der får tid til at blive stærkt igen. Under hele processen prioriteres stabilitet over aggressivitet.

### 7.1 Tærskler og dvale
Hvis ubalancen bliver for ekstrem – eksempelvis hvis short-siden eller gearing dominerer – kan Evelyn gå i
dvale (pause al trading). Dette sikrer, at systemet ikke vælter, men tålmodigt venter på bedre markedsforhold
eller ny kapitaltilførsel.

## 8. Risici, fail-safes og antifragilitet
Evelyn er designet til at overleve og vokse af markedsstress, ikke blot at modstå det. Systemet har flere
indbyggede mekanismer for at sikre antifragilitet:

- Fail-safe-mode: Hvis balancen mellem longs, shorts og margin bliver for skæv (fx hvis short-siden vokser
for meget), kan Evelyn sætte sig selv på pause og stoppe al trading. Det sikrer, at systemet aldrig tvinges ud i
ruinøse handler, men hellere venter tålmodigt på, at markedet vender, eller på at der tilføres ny margin.
- Tærskelbaseret gearing og tokensalg: Evelyn bruger gearing kun som midlertidigt værktøj, og kun til at holde
marginen lige over det kritiske minimum. Kun hvis dette fejler, udstedes nye tokens.
- Tålmodighed over panik: Systemet undgår bevidst at tage hurtige, risikable beslutninger under stress – i stedet
nedbringer det gearing og bygger langsomt balancen op igen.
- Antifragilitet: Når Evelyn oplever markedskaos, bliver den stærkere, fordi dens strategi bygger på at udnytte
ubalancer og reinvestere gevinsterne i at reparere systemet.

## 9. Udvikling, YouTrack-integration og offentlig gennemsigtighed
Evelyns udviklingsmodel bygger på transparens og dokumenterede processer, selvom selve koden ikke er offentlig:
- YouTrack-integration: Alle udviklingsopgaver oprettes og prissættes i EVELYN-tokens i YouTrack. Når en opgave er
funded (af Evelyn selv eller af eksterne), igangsættes arbejdet. Når den er færdig, udbetales tokens til udvikleren,
og transaktionen logges med ID på SolScan.
- Offentlig revision: Enhver kan følge med i, hvilke opgaver der er funded, hvem der har modtaget betaling, og
hvilken transaktion der ligger bag. Dermed er der fuld gennemsigtighed i systemets økonomi uden at afsløre den
underliggende strategi.
- Funding af opgaver: Opgaver bliver kun udført, hvis de er funded. Investorer og udviklere kan selv gå ind og
sponsorere opgaver, hvis de tror på systemet.

## 10. Fremtidige emner / TODO
- Bedre adgangsbegrænsning: Overvej, hvordan private plugins i Nenjim kan beskyttes bedre end “security by obscurity”.
- Automatisk tuning af allokeringsprocenter: Undersøg muligheder for at lade systemet lære og tilpasse sin interne
kapitalallokering over tid (AI-drevet tuning).
- Flere tradingstrategier: Udvid Evelyn med mulighed for at tilføje alternative, konkurrerende scoring-algoritmer.
- Bedre penalty-funktioner ved close: Implementer og test mere avanceret straflogik for lukning af positioner.
- Ekstra fail-safes: Tilføj flere automatiske stopmekanismer for at undgå at systemet “vipper omkuld” i
ekstreme markedsbevægelser.
- Open API for ekstern integration: Gør det muligt at tilføje eksterne datafeeds, udveksle signaler med andre
systemer, eller automatisere funding-opgaver.