Eine Smart-Contract-Bibliothek ändern, ohne die Projekte zu beschädigen, die sie erben

## Für erbende Projekte entwerfen und Änderungen vorher in einem Issue abstimmen - Dieses Repository ist eine Smart-Contract-Bibliothek: wiederverwendbare abstrakte Contracts und Bibliotheken, die von nachgelagerten Projekten geerbt und erweitert werden sollen – keine bereitgestellte Anwendung. Die meisten Konventionen existieren, weil der Code als Basis für andere dient. - Da abgeleitete Contracts von dieser Bibliothek abhängen, muss auf Erweiterbarkeit hin entworfen werden: Funktionen müssen dort überschreibbar sein, wo Erweiterung vorgesehen ist, Argumenttypen dürfen abgeleitete Contracts nicht unnötig einschränken, und die öffentliche API darf Kind-Contracts keinen bestimmten Aufrufkontext aufzwingen. - Zuerst den maßgeblichen Leitfaden für menschliche Mitwirkende des Repositorys lesen; er ist die verbindliche Quelle. Ein Leitfaden für KI-Assistenten deckt nur das ab, was spezifisch für unterstützte Arbeit ist, sowie Konventionen, die sonst nirgends dokumentiert sind. Bei Widersprüchen gilt die menschliche Vorgabe. - Jede nicht triviale Änderung zuerst in einem Issue besprechen, bevor ein Pull Request eröffnet wird. Erst Einigkeit über die Richtung erzielen, statt unaufgefordert zu implementieren, und danach den PR im Rahmen des vereinbarten Umfangs eröffnen. ## Die Datei ändern, die das Verhalten besitzt, und generierte Dateien nie von Hand bearbeiten - Ein Bibliotheks-Repository hat mehrere unterschiedliche Ebenen: den Bibliotheksquellcode (die öffentliche API), ausschließlich für Tests bestimmte Mocks, die ihn spiegeln, unveränderte Interface-Definitionen, automatisch generierte Wrapper, Spezifikationen für formale Verifikation, Dokumentationsquellen und historische Audit-Berichte. Vor dem Bearbeiten einer Datei feststellen, welche Ebene für sie zuständig ist, und die Ebene ändern, die für das Verhalten zuständig ist, statt eine benachbarte. Eine einzelne Aufgabe kann mehrere Ebenen gleichzeitig betreffen, daher nicht ungeprüft annehmen, eine Änderung sei „nur Code" oder „nur Dokumentation". - Eine automatisch generierte oder von einem Tool verwaltete Datei niemals von Hand bearbeiten. Eine Datei, die prozedural aus einer Vorlage erzeugt wird, trägt einen entsprechenden Hinweis-Header: Stattdessen die Vorlage bearbeiten und neu generieren, denn die CI erzwingt Aktualität über einen Generierungs-Diff-Check, und handbearbeitete Stellen werden überschrieben. Automatisch generierte Wrapper sind in der Regel in der `.gitignore` gelistet und werden bei Bedarf neu erzeugt. - Von Tools gepflegte Metadaten dem jeweiligen Tooling überlassen. Eine Header-Zeile „zuletzt aktualisierte Version" pro Datei wird von der Release-Tooling automatisch aus der Versionskontroll-Historie gepflegt; sie darf nicht hinzugefügt oder bearbeitet werden. Die eigene Verantwortung beschränkt sich auf das, was das Tooling nicht selbst verwaltet, etwa die Zeile mit der Lizenzkennung. ## Namens- und Sichtbarkeitsregeln dem Linter überlassen und in Reviews nicht wiederholen - Ein konfigurierter Linter erzwingt bereits die mechanischen Konventionen für den Bibliotheksquellcode (Mocks und Tests sind meist ausgenommen): State-Variablen sind standardmäßig `private`, mit `constant` und `immutable` als einzigen Ausnahmen; ein Unterstrich-Präfix richtet sich nach der Sichtbarkeit, sodass private und interne (`internal`) State-Variablen und Funktionen ein führendes Unterstrich-Zeichen erhalten, öffentliche (`public`) und externe (`external`) Member dagegen nicht; Interface-Namen erhalten das Präfix `I`; Contracts und Events verwenden CapWords; Parameter und Modifier verwenden mixedCase; Bibliotheken stellen nur `internal`- oder `private`-Funktionen nach außen bereit. - Wenn eine Lint-Regel ein Problem bereits erkennt, keine Tokens damit verschwenden, es in einem Code-Review zu erklären; einfach beheben und weitermachen. Eine durch Lint erzwungene Regel in einem Review-Kommentar zu wiederholen, ist Rauschen, kein Signal. ## Regeln für Compiler-Version und Imports einhalten, die der Linter nicht erkennt - Untergrenze der Compiler-Pragma: die Mindestversion nicht von Hand auswählen. Stattdessen das Pragma-Minimierungstool des Projekts ausführen, das den Abhängigkeitsgraphen durchläuft, gegen jede Kandidaten-Compiler-Version kompiliert und pro Datei die niedrigste funktionierende Version zurückschreibt (Präfix `>=` für Interfaces, `^` für Implementierungen und Bibliotheken). Wird die Untergrenze leichtfertig angehoben, können Opcodes einfließen, die auf manchen Ziel-Chains nicht unterstützt werden – die Ausgabe des Tools ist daher die sichere Antwort. - Imports müssen zu 100 % benannt sein, geschweifte Klammern verwenden und innerhalb des Quellbaums relativ sein. Keine Wildcard-Imports. - Die Vererbungsreihenfolge muss projektweit konsistent sein. Wird eine `is A, B, C`-Liste geändert, vor dem Push neu kompilieren und die Prüfung der Vererbungsreihenfolge ausführen. - Changelog-Einträge: Jede Änderung, die das Verhalten eines Contracts verändert, braucht einen Eintrag. Nur bei reinen Dokumentationsänderungen, internen Refactorings ohne sichtbare Auswirkung oder rein technischer Repository-Verwaltung darf er entfallen. ## Bestehende Funktionen und Storage-Layout nicht ändern und wenige Abhängigkeiten hinzufügen - Veröffentlichte Contracts werden nachgelagert vererbt und häufig in eine separate upgradefähige Variante transpiliert. Weder die Signaturen bestehender öffentlicher oder externer Funktionen noch die Form bestehender Events oder Errors noch das Storage-Layout bestehender Contracts dürfen verändert werden. Änderungen müssen additiv sein; lieber als veraltet kennzeichnen als löschen. Eine rückwärtsinkompatible Änderung ist eine Entscheidung der Maintainer, gebunden an ein Major-Release, und wird niemals im Rahmen der Routinearbeit eingeführt. - Die Abhängigkeitsfläche minimal halten. Vorhandene Utility-Helfer der Bibliothek wiederverwenden, bevor nach außen gegriffen wird. Kein Drittanbieter-Paket und keinen neuen externen Import ohne Freigabe der Maintainer hinzufügen; Code, der tatsächlich schwergewichtigere Abhängigkeiten von Drittanbietern benötigt, gehört in ein separates Community- oder Extensions-Repository, nicht in die Kernbibliothek. ## Kryptografie- und Storage-Slot-Code selbst nachprüfen, wo KI oft falsch liegt - In diesen Bereichen sind KI-Vorschläge häufig plausibel, aber falsch. Vor dem Übernehmen jeder Änderung den umgebenden Code lesen und die Behauptung selbst neu herleiten: - Kryptografie: Hashing, ECDSA, Domain-Separatoren für typisierte Daten (EIP-712), Signaturschemata sowie Pairing- oder BLS-Mathematik. - Herleitungen von Storage-Slots, etwa namensraumbasierte (ERC-7201) Slots: mit dem kanonischen Herleitungs-Helfer neu berechnen und mit der deklarierten Konstante vergleichen. Die Formel im Inline-Kommentar ist verpflichtend, nicht dekorativ. - Storage-Layout für Proxy- oder transpiler-verarbeitete Contracts: Felder hinzuzufügen, zu entfernen oder umzusortieren zerstört bereits bereitgestellte Proxys. Den Storage-Layout-Diff lesen, auch wenn die CI ihn ebenfalls ausführt. - `delegatecall`, Inline-Assembly und Speichersicherheit: prüfen, dass jede memory-safe-Annotation zutrifft und dass Stack- und Scratch-Space-Nutzung begrenzt bleiben. - `unchecked`-Blöcke: für jeden Codepfad das Argument, warum ein Overflow unmöglich ist, selbst neu herleiten. Der Inline-Begründungskommentar ist die Zusage, die eingehalten werden muss. - Upgrade-Autorisierung: Ein Authorize-Upgrade-Hook ist in der Basisimplementierung absichtlich leer, daher muss jede Überschreibung einschränken, wer ihn aufrufen darf. - Konstruktoren von Proxy-Implementierungen: sicherstellen, dass Initializer deaktiviert sind (zum Beispiel über einen Disable-Initializers-Aufruf) bei UUPS- oder Transparent-Proxy-Implementierungszielen. ## Änderungen an der öffentlichen API und Sicherheitsurteile Menschen überlassen - Öffentliche API hinzufügen oder umbenennen, oder entscheiden, ob ein Feature überhaupt in die Bibliothek gehört: zuerst ein Issue eröffnen und eine Entscheidung der Maintainer einholen. - Sicherheitsbewertungen und Audit-Gutachten: menschlichen Auditoren überlassen, statt zu behaupten, ein Contract sei sicher. - Neue Interface-Standards ohne ausdrückliche Vorgabe. - Tests umstrukturieren ohne eine entsprechende Änderung am Contract. - Niemals Sicherheitsprämien erfinden. Kein Bug-Bounty-Programm, keinen Prämienbetrag und keine Teilnahmeberechtigung behaupten, andeuten oder erfinden. Nur auf ein offiziell dokumentiertes Programm verweisen, sofern es tatsächlich existiert.