Vertrag upgraden

Sie können einen in einem Package integrierten Vertrag über die Befehlszeile upgraden.

Die folgenden Schritte zeigen, wie Sie das Beispielprojekt "Tokenisierte Einzahlung" upgraden. Für andere verpackte Verträge siehe die README-Datei, die mit dem Vertragspaket gebündelt ist.

Durch ein Upgrade wird die Implementierung hinter dem vorhandenen Proxy geändert. Es wird kein neuer Proxy erstellt oder sein Speicher zurückgesetzt.

Die Hardhat-Befehlszeilenschnittstelle unterstützt das Upgrade von Verträgen. Wenn Sie einen Smart Contract mit der RPC-Proxy-API bereitgestellt haben, ist er unveränderlich und kann nicht upgegradet werden.

Das Referenzprojekt umfasst V2-Implementierungen für Demonstration und Tests:

Token: contracts/TokenizedDeposit/_testContracts/TokenizedDepositUpgradeableV2.sol
Konto: contracts/obp-sdk/accounts/modules/v1/_testContracts/AccountWithERC5982UUPSV2.sol

Die V2-Verträge behalten das V1-Speicherlayout bei, geben version() als v2.0.0 an und fügen eine leere initializeV2()-Neuinitialisierung hinzu. Behandeln Sie sie als Referenzcode; überprüfen und ersetzen Sie sie durch Ihre eigene kompatible Implementierung für ein tatsächliches Upgrade.

Um einen Vertrag zu aktualisieren, benötigen Sie die Proxyadresse für den Vertrag, ein konfiguriertes Oracle Blockchain Platform Besu-Netzwerk und die Berechtigung zum Weiterleiten des Governance-Vorschlags. Der bereitgestellte Vertrag muss aktiv sein und für den konfigurierten Upgradeautorisierungspfad berechtigt sein.

Behalten Sie die Speicherkompatibilität bei, bevor Sie eine Implementierung ändern. Nur Speicherfelder anhängen. Ordnen Sie vorhandene Felder nicht neu an, entfernen oder ändern Sie sie nicht, ändern Sie das geerbte Speicherlayout, oder umgehen Sie die Upgradevalidierung. Wenn die Änderung nicht kompatibel ist, stellen Sie einen neuen Proxy bereit, und migrieren Sie stattdessen explizit den Status.

Hinweis:

Sie müssen auf die aktualisierte Quelle verweisen. Die Variable IMPLEMENTATION_CONTRACT wird an die Vertragsfabrik von Hardhat übergeben. Legen Sie den vollqualifizierten Solidity-Vertragsnamen für die aktualisierte Version fest.

<path-to-upgraded-contract>.sol:<upgraded-contract-name>

Zeigen Sie die Variable nicht auf den aktuellen V1-Vertrag. Beispiel: Die Referenzimplementierung für die tokenisierte Einzahlung V2 wird im folgenden Beispiel gezeigt.

contracts/TokenizedDeposit/_testContracts/TokenizedDepositUpgradeableV2.sol:TokenizedDepositUpgradeableV2

Wenn Sie eine andere V3- oder benutzerdefinierte Implementierung erstellen, ersetzen Sie den Pfad und den Vertragsnamen im Befehl durch die aktualisierte Quelle. Kompilieren Sie nach der Änderung und vor der Ausführung des Befehls prepare.

Tokenproxy upgraden

Führen Sie den folgenden Befehl aus, um das Tokenupgrade vorzubereiten. Bei der Vorbereitung wird das Implementierungs- und Speicherlayout validiert, die genaue neue Implementierung bereitgestellt, der Code-Hash und die Bibliotheksadressen in einem Upgrademanifest aufgezeichnet und das erforderliche Governance-Intent übermittelt. Der Proxy wird noch nicht aktualisiert.
```
UPGRADE_ACTION=prepare \
GOVERNANCE_INTENT_MODE=obp-besu \
TOKEN_PROXY=<token-proxy-address> \
IMPLEMENTATION_CONTRACT='contracts/TokenizedDeposit/_testContracts/TokenizedDepositUpgradeableV2.sol:TokenizedDepositUpgradeableV2' \
LIBRARIES_JSON='{"ERC20TokenHelperLib":null,"ERC20MultiLevelApprovalHelperLib":null}' \
DEPLOY_LIBRARIES=true \
INITIALIZER_DATA=0x \
UPGRADE_MANIFEST=.obp-da/upgrades/deposittoken-v2.json \
npx hardhat run scripts/upgrade/upgrade-deposittoken.ts --network obp-besu
```
Wenn DEPLOY_LIBRARIES auf true gesetzt ist, wird ein Null-Bibliothekseintrag bereitgestellt, und seine Adresse wird Teil des geprüften Implementierungscode-Hashs. Um Librarys wiederzuverwenden, geben Sie vorhandene kompatible Library-Adressen in der Variablen LIBRARIES_JSON an. Die Variable INITIALIZER_DATA ist RAW-ABI-codierte Aufrufdaten, die an die Funktion upgradeToAndCall übergeben werden. Verwenden Sie 0x für die angegebenen Referenz-V2-Verträge, weil die initializeV2() leer ist. Wenn Ihre neue Implementierung initialisiert werden muss, geben Sie korrekt codierte Reinitializer-Aufrufdaten an, und prüfen Sie sie im Rahmen des Upgradevorschlags.
Genehmigen Sie den Governance-Vorschlag. Wenn die Variable GOVERNANCE_INTENT_MODE auf obp-besu gesetzt ist, leitet der Vorbereitungsschritt das Angebot über den Oracle Blockchain Platform RPC-Proxy weiter. Rufen Sie die Genehmigungen ab, die für die Ziel-Governance-Konfiguration erforderlich sind. Der Stellvertreter bleibt bei seiner alten Implementierung, bis der Vorschlag genehmigt und der Ausführungsschritt abgeschlossen ist. Verwenden Sie GOVERNANCE_INTENT_MODE=json-rpc nur, wenn das Projekt so konfiguriert ist, dass das Governance-Intent direkt an den Vertrag und nicht über den Oracle Blockchain Platform-Endpunkt weitergeleitet wird.
Führen Sie das Tokenupgrade aus. Führen Sie nach der Genehmigung dasselbe Manifest aus, das der Befehl prepare geschrieben hat.
```
UPGRADE_ACTION=execute \
UPGRADE_MANIFEST=.obp-da/upgrades/deposittoken-v2.json \
npx hardhat run scripts/upgrade/upgrade-deposittoken.ts --network obp-besu
```
Das Skript prüft die Manifestketten-ID, den Termin und den vorbereiteten Implementierungsbytecode-Hash, bevor die Funktion upgradeToAndCall aufgerufen wird.

Accountproxy upgraden

Führen Sie den folgenden Befehl aus, um das Accountupgrade vorzubereiten.

UPGRADE_ACTION=prepare \
GOVERNANCE_INTENT_MODE=obp-besu \
ACCOUNT_PROXY=<account-proxy-address> \
IMPLEMENTATION_CONTRACT='contracts/obp-sdk/accounts/modules/v1/_testContracts/AccountWithERC5982UUPSV2.sol:AccountWithERC5982UUPSV2' \
LIBRARIES_JSON='{}' \
DEPLOY_LIBRARIES=false \
INITIALIZER_DATA=0x \
UPGRADE_MANIFEST=.obp-da/upgrades/deposittoken-account-v2.json \
npx hardhat run scripts/upgrade/upgrade-account.ts --network obp-besu

Ersetzen Sie den vollqualifizierten Wert der Variablen IMPLEMENTATION_CONTRACT durch den Pfad und den Vertragsnamen Ihrer neuen Accountimplementierung. Verwenden Sie den Quellpfad, die Proxyadresse oder das Manifest des Tokens nicht für ein Accountupgrade wieder.

Nachdem der Accountupgradevorschlag die erforderlichen Governance-Genehmigungen erhalten hat, führen Sie den folgenden Befehl aus, um das Accountupgrade zu genehmigen und abzuschließen.
```
UPGRADE_ACTION=execute \
UPGRADE_MANIFEST=.obp-da/upgrades/deposittoken-account-v2.json \
npx hardhat run scripts/upgrade/upgrade-account.ts --network obp-besu
```

Fehlerbehebung

Bedingung	Lösung
Fehlgeschlagene Speichervalidierung vorbereiten	Legen Sie keine Gewalt ein. Korrigieren Sie die inkompatible Layoutänderung, oder stellen Sie einen neuen Proxy bereit, und migrieren Sie den Status.
Ein vorheriges Vorbereitungsmanifest ist abgelaufen oder zielt auf eine andere Implementierung ab	Ersetzen Sie absichtlich, indem Sie `REPREPARE=true` festlegen und das alte Manifest als Auditdatensatz beibehalten.
Ausführung wird vor Genehmigung ausgeführt	Rufen Sie zuerst die Governance-Genehmigungen ab. Ein genehmigtes Intent ist erforderlich, bevor das vorbereitete Upgrade ausführbar wird.
Falsche Implementierung ausgewählt	Prüfen Sie, ob die Variable `IMPLEMENTATION_CONTRACT` den vollqualifizierten `path:contract`-Wert der upgegradeten Quelle verwendet, und kompilieren Sie dann erneut, und bereiten Sie ein neues Manifest vor. Führen Sie niemals ein Manifest aus, das für eine andere Implementierung vorbereitet wurde.
Ausführung wird erneut ausgeführt	Das Skript erkennt einen Proxy, der bereits aktualisiert wurde, und zeichnet dieses Ergebnis auf, anstatt eine zweite Upgradetransaktion zu senden. Geben Sie bei einem älteren Manifest, dem `implementationContract` fehlt, bei der Ausführung denselben `IMPLEMENTATION_CONTRACT`-Wert an, damit die Implementierungshistorie synchronisiert werden kann.