升級合約

您可以從指令行升級已封裝的合約。

下列步驟顯示如何升級範例變數替代字存款合約專案。如需其他已封裝的合約，請參閱隨附於合約套件的 README 檔案。

升級會變更現有代理主機背後的實作；它不會建立新的代理主機或重設其儲存體。

Hardhat 命令行介面支援升級合約。如果您使用 RPC 代理 API 部署智能合約，則該合約不可變更且無法升級。

參照專案包括用於示範和測試的 V2 導入：

代幣：contracts/TokenizedDeposit/_testContracts/TokenizedDepositUpgradeableV2.sol
帳戶：contracts/obp-sdk/accounts/modules/v1/_testContracts/AccountWithERC5982UUPSV2.sol

V2 合約會保留 V1 儲存配置，將 version() 顯示為 v2.0.0 ，並包含空白的 initializeV2() 重新初始化程式。將它們視為參考代碼；針對實際升級，使用您自己的相容實作複查並取代這些代碼。

若要升級合約，您需要合約的代理主機位址、已設定的 Oracle Blockchain Platform Besu 網路，以及提交治理提案的權限。部署的合約必須有效且適用於其設定的升級授權路徑。

在修改實作之前，請保留儲存相容性。僅附加儲存體欄位。請勿重新排序、移除或變更現有欄位的類型、更改繼承的儲存版面配置，或略過升級驗證。如果變更不相容，請部署新的代理並明確移轉狀態。

備註：

您必須指向已升級的來源。IMPLEMENTATION_CONTRACT 變數會傳遞至 Hardhat 的合約工廠。將它設定為升級版本的完整 Solidity 合約名稱。

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

請勿將變數指向目前的 V1 合約。例如，記號化保證金 V2 參考實作顯示在下列範例中。

contracts/TokenizedDeposit/_testContracts/TokenizedDepositUpgradeableV2.sol:TokenizedDepositUpgradeableV2

如果您建立不同的 V3 或自訂實作，請將指令中的路徑和合約名稱同時取代為該升級的來源。請在變更之後編譯，然後再執行 prepare 命令。

升級權杖代理主機

請執行下列命令來準備權杖升級。準備作業會驗證導入與儲存配置、部署確切的新導入、在升級資訊清單中記錄其程式碼雜湊與程式庫位址，以及提交必要的治理意圖。它尚未升級代理伺服器。
```
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
```
將 DEPLOY_LIBRARIES 設為 true 時，會部署空值程式庫項目，且其位址會成為已複查之實行程式碼雜湊的一部分。若要重複使用程式庫，請在 LIBRARIES_JSON 變數中提供現有的相容程式庫位址。INITIALIZER_DATA 變數是傳送給 upgradeToAndCall 函數的原始 ABI 編碼的呼叫資料。提供的參考 V2 合約使用 0x，因為其 initializeV2() 是空的。如果您的新實作需要初始化，請提供正確編碼的重新初始化程式呼叫資料，並在升級提案中加以複查。
核准治理提案。如果 GOVERNANCE_INTENT_MODE 變數設為 obp-besu，則準備步驟會透過 Oracle Blockchain Platform RPC 代理主機送出提案。取得目標治理組態所需的核准。在提案獲得核准且執行步驟完成之前，代理會保留在其舊的導入上。僅當專案設定為直接將治理意向提交給合約，而不是透過 Oracle Blockchain Platform 端點時，才使用 GOVERNANCE_INTENT_MODE=json-rpc。
執行權杖升級。核准之後，請執行 prepare 命令所撰寫的相同資訊清單。
```
UPGRADE_ACTION=execute \
UPGRADE_MANIFEST=.obp-da/upgrades/deposittoken-v2.json \
npx hardhat run scripts/upgrade/upgrade-deposittoken.ts --network obp-besu
```
此程序檔會先驗證資訊清單鏈 ID、期限，以及準備的實作位元組碼雜湊，然後再呼叫 upgradeToAndCall 函數。

升級帳戶代理主機

執行下列指令以準備帳戶升級。

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

將 IMPLEMENTATION_CONTRACT 變數的完整值取代為您新帳戶實作的路徑與合約名稱。請勿重複使用權杖的來源路徑、代理主機位址或資訊清單進行帳戶升級。

帳戶升級提案收到必要的治理核准之後，請執行下列命令來核准並完成帳戶升級。

UPGRADE_ACTION=execute \
UPGRADE_MANIFEST=.obp-da/upgrades/deposittoken-account-v2.json \
npx hardhat run scripts/upgrade/upgrade-account.ts --network obp-besu

疑難排解

條件	解決方式
準備失敗儲存驗證	請勿強制升級。更正不相容的版面配置變更，或部署新的代理主機並移轉狀態。
先前的準備資訊清單已過期或目標為不同的實行	設定 `REPREPARE=true` 並將舊清單保留為稽核記錄，以蓄意方式建立替代項目。
執行於核准前執行	先取得治理核准。準備好的升級變成可執行之前，必須先核准的意圖。
選取的實行錯誤	確認 `IMPLEMENTATION_CONTRACT` 變數使用已升級來源的完整 `path:contract` 值，然後重新編譯和準備新的清單。絕對不要執行為不同的實行準備的清單。
執行已重新執行	此程序檔會偵測已經升級的代理伺服器，並記錄結果，而非傳送第二次升級交易。對於缺少 `implementationContract` 的舊版清單，請在執行時提供相同的 `IMPLEMENTATION_CONTRACT` 值，以同步化實作歷史記錄。