Transfer
+``` + +這是元件的 HTML (更準確地說，是 [JSX](https://react.dev/learn/writing-markup-with-jsx)) 格式。 + +#### `server/noir/src/main.nr` {#server-noir-src-main-nr} + +[此檔案](https://github.com/qbzzt/250911-zk-bank/blob/01-manual-zk/server/noir/src/main.nr) 是實際的零知識程式碼。 + +``` +use std::hash::pedersen_hash; +``` + +[Pedersen 雜湊](https://rya-sge.github.io/access-denied/2024/05/07/pedersen-hash-function/) 由 [Noir 標準庫](https://noir-lang.org/docs/noir/standard_library/cryptographic_primitives/hashes#pedersen_hash) 提供。 零知識證明通常使用此雜湊函數。 與標準雜湊函數相比，在 [算術電路](https://rareskills.io/post/arithmetic-circuit) 內計算要容易得多。 + +``` +use keccak256::keccak256; +use dep::ecrecover; +``` + +這兩個函式是外部庫，定義在 [`Nargo.toml`](https://github.com/qbzzt/250911-zk-bank/blob/01-manual-zk/server/noir/Nargo.toml) 中。 它們的名稱恰如其分，一個是計算 [keccak256 雜湊](https://emn178.github.io/online-tools/keccak_256.html) 的函式，另一個是驗證以太坊簽章並恢復簽署者的以太坊地址的函式。 + +``` +global ACCOUNT_NUMBER : u32 = 5; +``` + +Noir 的靈感來自 [Rust](https://www.rust-lang.org/)。 變數預設是常數。 這是我們定義全域組態常數的方式。 具體來說，`ACCOUNT_NUMBER` 是我們儲存的帳戶數量。 + +名為 `uGreeter
+Greeter
+ { + !readResults.isError && !readResults.isLoading && ++``` + +建立一個 `ShowGreeting` 元件（下面會解釋），但只有在成功從區塊鏈讀取問候語時才建立。 + +```tsx + +``` + +這是使用者可以設定新問候語的輸入文字欄位。 每當使用者按下一個鍵，我們就呼叫 `greetingChange`，它會再呼叫 `setNewGreeting`。 由於 `setNewGreeting` 來自 `useState` hook，它會導致 `Greeter` 元件再次被渲染。 這表示： + +- 我們需要指定 `value` 來保留新問候語的值，否則它會變回預設的空字串。 +- 每當 `newGreeting` 變更時，`usePrepareContractWrite` 就會被呼叫，這表示它在準備好的交易中永遠會擁有最新的 `newGreeting`。 + +```tsx + +``` + +如果沒有 `workingTx.write`，那麼我們仍在等待傳送問候語更新所需的資訊，所以按鈕是停用的。 如果有 `workingTx.write` 值，那麼這就是傳送交易時要呼叫的函式。 + +```tsx +
+
+```
+
+我們不希望用所有資訊來塞滿 UI，所以為了可以檢視或關閉它們，我們使用了 [`details`](https://www.w3schools.com/tags/tag_details.asp) 標籤。
+
+```tsx
+
+
+}
+```
+
+結束各種 HTML 標籤。
+
+##### 最後的 `export` {#the-final-export}
+
+```tsx
+export { Greeter }
+```
+
+我們需要為應用程式匯出的就是 `Greeter` 元件。
+
+#### `src/wagmi.ts` {#wagmi-ts}
+
+最後，與 WAGMI 相關的各種定義都在 `src/wagmi.ts` 中。 我不會在這裡解釋所有內容，因為大部分都是樣板程式碼，你不太可能需要變更。
+
+這裡的程式碼與 [github 上的](https://github.com/qbzzt/20230801-modern-ui/blob/main/src/wagmi.ts) 不完全相同，因為在文章後面我們會新增另一條鏈 ([Redstone Holesky](https://redstone.xyz/docs/network-info))。
+
+```ts
+import { getDefaultWallets } from '@rainbow-me/rainbowkit'
+import { configureChains, createConfig } from 'wagmi'
+import { holesky, sepolia } from 'wagmi/chains'
+```
+
+匯入應用程式支援的區塊鏈。 你可以在 [viem 的 github](https://github.com/wagmi-dev/viem/tree/main/src/chains/definitions) 中看到支援的鏈的清單。
+
+```ts
+import { publicProvider } from 'wagmi/providers/public'
+
+const walletConnectProjectId = 'c96e690bb92b6311e8e9b2a6a22df575'
+```
+
+要能使用 [WalletConnect](https://walletconnect.com/)，你的應用程式需要一個專案 ID。 你可以在 [cloud.walletconnect.com](https://cloud.walletconnect.com/sign-in) 上取得它。
+
+```ts
+const { chains, publicClient, webSocketPublicClient } = configureChains(
+ [ holesky, sepolia ],
+ [
+ publicProvider(),
+ ],
+)
+
+const { connectors } = getDefaultWallets({
+ appName: 'My wagmi + RainbowKit App',
+ chains,
+ projectId: walletConnectProjectId,
+})
+
+export const config = createConfig({
+ autoConnect: true,
+ connectors,
+ publicClient,
+ webSocketPublicClient,
+})
+
+export { chains }
+```
+
+### 新增另一條區塊鏈 {#add-blockchain}
+
+現今有很多 [L2 擴展解決方案](/layer-2/)，你可能想要支援一些 viem 尚未支援的方案。 要做到這點，你需要修改 `src/wagmi.ts`。 這些說明解釋了如何新增 [Redstone Holesky](https://redstone.xyz/docs/network-info)。
+
+1. 從 viem 匯入 `defineChain` 型別。
+
+ ```ts
+ import { defineChain } from 'viem'
+ ```
+
+2. 新增網路定義。
+
+ ```ts
+ const redstoneHolesky = defineChain({
+ id: 17_001,
+ name: 'Redstone Holesky',
+ network: 'redstone-holesky',
+ nativeCurrency: {
+ decimals: 18,
+ name: 'Ether',
+ symbol: 'ETH',
+ },
+ rpcUrls: {
+ default: {
+ http: ['https://rpc.holesky.redstone.xyz'],
+ webSocket: ['wss://rpc.holesky.redstone.xyz/ws'],
+ },
+ public: {
+ http: ['https://rpc.holesky.redstone.xyz'],
+ webSocket: ['wss://rpc.holesky.redstone.xyz/ws'],
+ },
+ },
+ blockExplorers: {
+ default: { name: 'Explorer', url: 'https://explorer.holesky.redstone.xyz' },
+ },
+ })
+ ```
+
+3. 將新鏈新增到 `configureChains` 呼叫中。
+
+ ```ts
+ const { chains, publicClient, webSocketPublicClient } = configureChains(
+ [ holesky, sepolia, redstoneHolesky ],
+ [ publicProvider(), ],
+ )
+ ```
+
+4. 確保應用程式知道你的合約在新網路上的地址。 在這種情況下，我們修改 `src/components/Greeter.tsx`：
+
+ ```ts
+ const contractAddrs : AddressPerBlockchainType = {
+ // Holesky
+ 17000: '0x432d810484AdD7454ddb3b5311f0Ac2E95CeceA8',
+
+ // Redstone Holesky
+ 17001: '0x4919517f82a1B89a32392E1BF72ec827ba9986D3',
+
+ // Sepolia
+ 11155111: '0x7143d5c190F048C8d19fe325b748b081903E3BF0'
+ }
+ ```
+
+## 結論 {#conclusion}
+
+當然，你並不是真的在乎為 `Greeter` 提供使用者介面。 你想要為你自己的合約建立一個使用者介面。 要建立你自己的應用程式，請執行以下步驟：
+
+1. 指定建立一個 wagmi 應用程式。
+
+ ```sh copy
+ pnpm create wagmi
+ ```
+
+2. 為應用程式命名。
+
+3. 選擇 **React** 框架。
+
+4. 選擇 **Vite** 變體。
+
+5. 你可以 [新增 Rainbow kit](https://www.rainbowkit.com/docs/installation#manual-setup)。
+
+現在去讓你的合約為廣大世界所用吧。
+
+[在此查看我的更多作品](https://cryptodocguy.pro/)。
+
diff --git a/public/content/translations/zh-tw/developers/tutorials/deploying-your-first-smart-contract/index.md b/public/content/translations/zh-tw/developers/tutorials/deploying-your-first-smart-contract/index.md
new file mode 100644
index 00000000000..701b370b70e
--- /dev/null
+++ b/public/content/translations/zh-tw/developers/tutorials/deploying-your-first-smart-contract/index.md
@@ -0,0 +1,95 @@
+---
+title: "部署你的第一個智能合約"
+description: "在以太坊測試網上部署你的第一個智能合約的簡介"
+author: "jdourlens"
+tags: [ "智能合約", "remix", "穩固", "部署" ]
+skill: beginner
+lang: zh-tw
+published: 2020-04-03
+source: EthereumDev
+sourceUrl: https://ethereumdev.io/deploying-your-first-smart-contract/
+address: "0x19dE91Af973F404EDF5B4c093983a7c6E3EC8ccE"
+---
+
+我想你和我們一樣興奮，都想在以太坊區塊鏈上[部署](/developers/docs/smart-contracts/deploying/)並與你的第一個[智能合約](/developers/docs/smart-contracts/)互動。
+
+別擔心，因為這是我們的第一個智能合約，我們會在[本地測試網](/developers/docs/networks/)上部署它，所以你部署和盡情操作它都不需要任何費用。
+
+## 撰寫我們的合約 {#writing-our-contract}
+
+第一步是[訪問 Remix](https://remix.ethereum.org/) 並建立一個新檔案。 在 Remix 介面的左上角新增一個新檔案，並輸入你想要的檔案名稱。
+
+
+
+在新檔案中，我們將貼上以下程式碼：
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.5.17;
+
+contract Counter {
+
+ // 公開的無正負號整數，用來記錄次數
+ uint256 public count = 0;
+
+ // 遞增計數器的函式
+ function increment() public {
+ count += 1;
+ }
+
+ // 取得計數值的 getter，非必要
+ function getCount() public view returns (uint256) {
+ return count;
+ }
+
+}
+```
+
+如果你習慣寫程式，你應該可以輕易猜出這個程式的功能。 以下是逐行說明：
+
+- 第 4 行：我們定義了一個名為 `Counter` 的合約。
+- 第 7 行：我們的合約儲存一個名為 `count` 的無正負號整數，初始值為 0。
+- 第 10 行：第一個函式會修改合約的狀態，並透過 `increment()` 遞增我們的 `count` 變數。
+- 第 15 行：第二個函式只是一個 getter，用來從智能合約外部讀取 `count` 變數的值。 請注意，因為我們將 `count` 變數定義為 public (公開)，所以這不是必要的，只是作為範例展示。
+
+這就是我們第一個簡單的智能合約。 你可能知道，它看起來像 Java 或 C++ 等物件導向程式設計 (OOP) 語言中的類別 (class)。 現在可以來操作我們的合約了。
+
+## 部署我們的合約 {#deploying-our-contract}
+
+既然我們寫好了第一個智能合約，現在就要將它部署到區塊鏈上，以便進行操作。
+
+[在區塊鏈上部署智能合約](/developers/docs/smart-contracts/deploying/)，實際上只是傳送一筆交易，其中包含已編譯智能合約的程式碼，而無須指定任何接收者。
+
+首先，我們要點擊左側的編譯圖示來[編譯合約](/developers/docs/smart-contracts/compiling/)：
+
+
+
+然後點擊編譯按鈕：
+
+
+
+你可以選擇「自動編譯」(Auto compile) 選項，這樣每當你在文字編輯器中儲存內容時，合約就會自動編譯。
+
+然後前往「部署及執行交易」(deploy and run transactions) 畫面：
+
+
+
+進入「部署及執行交易」畫面後，再次確認你的合約名稱是否出現，然後點擊「部署」(Deploy)。 如你在頁面頂端所見，目前環境是「JavaScript VM」(JavaScript 虛擬機)，這代表我們將在一個本地測試鏈上部署我們的智能合約並與之互動，以便能更快地測試，且無須支付任何費用。
+
+
+
+點擊「部署」(Deploy) 按鈕後，你會在底部看到你的合約。 點擊左邊的箭頭將它展開，我們便能看到合約的內容。 這就是我們的 `count` 變數、`increment()` 函式和 `getCounter()` getter。
+
+如果你點擊 `count` 或 `getCount` 按鈕，它會實際擷取合約的 `count` 變數內容並顯示出來。 因為我們還沒呼叫 `increment` 函式，所以它應該會顯示 0。
+
+
+
+現在讓我們點擊按鈕來呼叫 `increment` 函式。 你會在視窗底部看到所執行交易的紀錄。 你會發現，當你按下擷取資料的按鈕時，紀錄會與按下 `increment` 按鈕時不同。 這是因為在區塊鏈上讀取資料不需要任何交易 (寫入) 或費用。 因為只有修改區塊鏈的狀態才需要進行交易：
+
+
+
+按下 increment 按鈕會產生一筆交易來呼叫我們的 `increment()` 函式，之後如果我們回頭點擊 count 或 getCount 按鈕，我們就會讀取到智能合約已更新的狀態，其中 count 變數的值會大於 0。
+
+
+
+在下一篇教學中，我們將介紹[如何在你的智能合約中新增事件](/developers/tutorials/logging-events-smart-contracts/)。 記錄事件是個便利的方法，可以對你的智能合約進行除錯，並了解呼叫函式時發生了什麼事。
diff --git a/public/content/translations/zh-tw/developers/tutorials/develop-and-test-dapps-with-a-multi-client-local-eth-testnet/index.md b/public/content/translations/zh-tw/developers/tutorials/develop-and-test-dapps-with-a-multi-client-local-eth-testnet/index.md
new file mode 100644
index 00000000000..c248ccf6d0d
--- /dev/null
+++ b/public/content/translations/zh-tw/developers/tutorials/develop-and-test-dapps-with-a-multi-client-local-eth-testnet/index.md
@@ -0,0 +1,363 @@
+---
+title: "如何在本地多用戶端測試網上開發和測試 dApp"
+description: "本指南將首先引導您完成如何實例化和設定多用戶端的本地以太坊測試網，然後再使用該測試網來部署與測試 dApp。"
+author: "Tedi Mitiku"
+tags: [ "用戶端", "節點", "智能合約", "可組合性", "共識層", "執行層", "測試" ]
+skill: intermediate
+lang: zh-tw
+published: 2023-04-11
+---
+
+## 介紹 {#introduction}
+
+本指南將引導您完成實例化可設定的本地以太坊測試網、將智能合約部署到其中，並使用該測試網對您的 dApp 執行測試的過程。 本指南專為希望在部署到即時測試網或主網之前，針對不同的網路設定在本地開發和測試其 dApp 的 dApp 開發者而設計。
+
+在本指南中，您將會：
+
+- 使用 [Kurtosis](https://www.kurtosis.com/) 和 [`eth-network-package`](https://github.com/kurtosis-tech/eth-network-package) 實例化一個本地以太坊測試網，
+- 將您的 Hardhat dApp 開發環境連接到本地測試網以編譯、部署和測試 dApp，以及
+- 設定本地測試網，包括節點數量和特定的 EL/CL 用戶端配對等參數，以實現針對各種網路設定的開發和測試工作流程。
+
+### 什麼是 Kurtosis？ {#what-is-kurtosis}
+
+[Kurtosis](https://www.kurtosis.com/) 是一個可組合的建構系統，專為設定多容器測試環境而設計。 它特別允許開發者創建需要動態設定邏輯的可重現環境，例如區塊鏈測試網。
+
+在本指南中，Kurtosis eth-network-package 會啟動一個本地以太坊測試網，支援 [`geth`](https://geth.ethereum.org/) 執行層 (EL) 用戶端，以及 [`teku`](https://consensys.io/teku)、[`lighthouse`](https://lighthouse.sigmaprime.io/) 和 [`lodestar`](https://lodestar.chainsafe.io/) 共識層 (CL) 用戶端。 此套件可作為 Hardhat Network、Ganache 和 Anvil 等框架中網路的可設定和可組合替代方案。 Kurtosis 為開發者提供了對其使用的測試網更大的控制權和靈活性，這也是[以太坊基金會使用 Kurtosis 測試合併](https://www.kurtosis.com/blog/testing-the-ethereum-merge)並繼續使用它來測試網路升級的主要原因。
+
+## 設定 Kurtosis {#setting-up-kurtosis}
+
+在繼續之前，請確定您已經：
+
+- 在您的本地機器上[安裝並啟動 Docker 引擎](https://docs.kurtosis.com/install/#i-install--start-docker)
+- [安裝 Kurtosis CLI](https://docs.kurtosis.com/install#ii-install-the-cli)（如果您已安裝 CLI，則將其升級到最新版本）
+- 安裝 [Node.js](https://nodejs.org/en)、[yarn](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable) 和 [npx](https://www.npmjs.com/package/npx)（為您的 dApp 環境）
+
+## 實例化本地以太坊測試網 {#instantiate-testnet}
+
+要啟動本地以太坊測試網，請執行：
+
+```python
+kurtosis --enclave local-eth-testnet run github.com/kurtosis-tech/eth-network-package
+```
+
+注意：此命令使用 `--enclave` 標誌將您的網路命名為「local-eth-testnet」。
+
+Kurtosis 在解譯、驗證和執行指令時，會印出其在幕後執行的步驟。 最後，您應該會看到類似以下的輸出：
+
+```python
+INFO[2023-04-04T18:09:44-04:00] ======================================================
+INFO[2023-04-04T18:09:44-04:00] || Created enclave: local-eth-testnet ||
+INFO[2023-04-04T18:09:44-04:00] ======================================================
+Name: local-eth-testnet
+UUID: 39372d756ae8
+Status: RUNNING
+Creation Time: Tue, 04 Apr 2023 18:09:03 EDT
+
+========================================= Files Artifacts =========================================
+UUID Name
+d4085a064230 cl-genesis-data
+1c62cb792e4c el-genesis-data
+bd60489b73a7 genesis-generation-config-cl
+b2e593fe5228 genesis-generation-config-el
+d552a54acf78 geth-prefunded-keys
+5f7e661eb838 prysm-password
+054e7338bb59 validator-keystore-0
+
+========================================== User Services ==========================================
+UUID Name Ports Status
+e20f129ee0c5 cl-client-0-beacon http: 4000/tcp -> {attrs.name}
+
+ {JSON.stringify(attrs.object, null, 2)}
+```
+
+大部分的欄位都是使用 [`JSON.stringify`](https://www.w3schools.com/js/js_json_stringify.asp) 來顯示的。
+
+```tsx
+
+ { funs.length > 0 &&
+ <>
+ 函式：
+ -
+```
+
+例外是函式，它們不是 [JSON 標準](https://www.json.org/json-en.html) 的一部分，所以必須分開顯示。
+
+```tsx
+ {funs.map((f, i) =>
+```
+
+在 JSX 中，`{` 大括號 `}` 內的程式碼會被解讀為 JavaScript。 然後，`(` 普通括號 `)` 內的程式碼會再次被解讀為 JSX。
+
+```tsx
+ (
- {f} ) + )} +``` + +React 要求 [DOM 樹](https://www.w3schools.com/js/js_htmldom.asp) 中的標籤必須有不同的識別碼。 這表示同一個標籤的子標籤（在此例中為 [無序清單](https://www.w3schools.com/tags/tag_ul.asp)）需要有不同的 `key` 屬性。 + +```tsx +
Hello ${loginResponse.extract.nameID}
+ + + `) + res.send(); +``` + +傳送 HTML 回應，僅是為了向使用者顯示我們已收到登入請求。 + +```typescript + } catch (err) { + console.error('Error processing SAML response:', err); + res.status(400).send('SAML authentication failed'); + } + } +) +``` + +如果失敗，請通知使用者。 + +```typescript +spRouter.get('/login', +``` + +當瀏覽器嘗試取得此頁面時，建立一個登入請求。 這是上方序列圖中步驟 1 的處理常式。 + +```typescript + async (req, res) => { + const loginRequest = await sp.createLoginRequest(idp, "post") +``` + +取得發布登入請求的資訊。 + +```typescript + res.send(` + + + +``` + +此頁面會自動提交表單 (見下文)。 如此一來，使用者就不需要執行任何操作即可被重新導向。 這是上方序列圖中的步驟 2。 + +```typescript + + + + `) + } +) + +app.use(express.urlencoded({extended: true})) +``` + +[此中介軟體](https://expressjs.com/en/5x/api.html#express.urlencoded) 會讀取 [HTTP 請求](https://www.tutorialspoint.com/http/http_requests.htm)的主體。 預設情況下，express 會忽略它，因為大多數請求並不需要它。 我們需要它，因為 POST 會使用主體。 + +```typescript +app.use(`/${config.spDir}`, spRouter) +``` + +在服務提供者目錄 (`/sp`) 中掛載路由器。 + +```typescript +app.get("/", (req, res) => { + res.send(` + + + + + + `) +}) +``` + +如果瀏覽器嘗試取得根目錄，請為其提供登入頁面的連結。 + +```typescript +app.listen(config.spPort, () => { + console.log(`service provider is running on http://${config.spHostname}:${config.spPort}`) +}) +``` + +使用此 express 應用程式監聽 `spPort`。 + +#### src/idp.mts + +這是身分提供者。 它與服務提供者非常相似，以下說明是針對不同的部分。 + +```typescript +const xmlParser = new (await import("fast-xml-parser")).XMLParser( + { + ignoreAttributes: false, // Preserve attributes + attributeNamePrefix: "@_", // Prefix for attributes + } +) +``` + +我們需要讀取並理解從服務提供者收到的 XML 請求。 + +```typescript +const getLoginPage = requestId => ` +``` + +此函數會建立一個帶有自動提交表單的頁面，該頁面會在上方序列圖的步驟 4 中傳回。 + +```typescript + + +Login page
+ + + + +const idpRouter = express.Router() + +idpRouter.post("/loginSubmitted", async (req, res) => { + const loginResponse = await idp.createLoginResponse( +``` + +這是上方序列圖中步驟 5 的處理常式。 [`idp.createLoginResponse`](https://github.com/tngan/samlify/blob/master/src/entity-idp.ts#L73-L125) 會建立登入回應。 + +```typescript + sp, + { + authnContextClassRef: 'urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport', + audience: sp.entityID, +``` + +對象為服務提供者。 + +```typescript + extract: { + request: { + id: req.body.requestId + } + }, +``` + +從請求中提取的資訊。 我們在請求中關心的一個參數是 requestId，它讓服務提供者能夠匹配請求及其回應。 + +```typescript + signingKey: { privateKey: idpPrivateKey, publicKey: config.idpCert } // Ensure signing +``` + +我們需要 `signingKey` 擁有簽署回應的資料。 服務提供者不信任未經簽署的請求。 + +```typescript + }, + "post", + { + email: req.body.email +``` + +這是我們傳送回服務提供者的使用者資訊欄位。 + +```typescript + } + ); + + res.send(` + + + + + + + + `) +}) +``` + +同樣，使用自動提交的表單。 這是上方序列圖中的步驟 6。 + +```typescript + +// IdP endpoint for login requests +idpRouter.post(`/login`, +``` + +這是從服務提供者接收登入請求的端點。 這是上方序列圖中步驟 3 的處理常式。 + +```typescript + async (req, res) => { + try { + // Workaround because I couldn't get parseLoginRequest to work. + // const loginRequest = await idp.parseLoginRequest(sp, 'post', req) + const samlRequest = xmlParser.parse(Buffer.from(req.body.SAMLRequest, 'base64').toString('utf-8')) + res.send(getLoginPage(samlRequest["samlp:AuthnRequest"]["@_ID"])) +``` + +我們應該能夠使用 [`idp.parseLoginRequest`](https://github.com/tngan/samlify/blob/master/src/entity-idp.ts#L127-L144) 來讀取驗證請求的 ID。 然而，我無法讓它正常運作，而且不值得花太多時間，所以我只使用[通用的 XML 解析器](https://www.npmjs.com/package/fast-xml-parser)。 我們需要的資訊是 `Please sign
+ ++ + + +` +} +``` + +其餘的只是標準的 HTML。 + +```typescript +idpRouter.get("/signature/:nonce/:account/:signature", async (req, res) => { +``` + +這是序列圖中步驟 5 的處理常式。 + +```typescript + const requestId = nonces[req.params.nonce] + if (requestId === undefined) { + res.send("Bad nonce") + return ; + } + + nonces[req.params.nonce] = undefined +``` + +取得請求 ID，並從 `nonces` 中刪除該 nonce，以確保無法重複使用。 + +```typescript + try { +``` + +由於簽章可能無效的方式有很多種，我們將此包裝在 `try ...` `catch` 區塊中，以捕捉任何擲出的錯誤。 + +```typescript + const validSignature = await verifyMessage({ + address: req.params.account, + message: `${loginPrompt}${req.params.nonce}`, + signature: req.params.signature + }) +``` + +使用 [`verifyMessage`](https://viem.sh/docs/actions/public/verifyMessage#verifymessage) 來實作序列圖中的步驟 5.5。 + +```typescript + if (!validSignature) + throw("Bad signature") + } catch (err) { + res.send("Error:" + err) + return ; + } +``` + +此處理程式的其餘部分與我們之前在 `/loginSubmitted` 處理程式中所做的相同，除了一個小小的變更。 + +```typescript + const loginResponse = await idp.createLoginResponse( + . + . + . + { + email: req.params.account + "@bad.email.address" + } + ); +``` + +我們沒有實際的電子郵件地址 (我們將在下一節中取得)，所以現在我們先傳回以太坊地址，並清楚地標示它不是一個電子郵件地址。 + +```typescript +// IdP endpoint for login requests +idpRouter.post(`/login`, + async (req, res) => { + try { + // Workaround because I couldn't get parseLoginRequest to work. + // const loginRequest = await idp.parseLoginRequest(sp, 'post', req) + const samlRequest = xmlParser.parse(Buffer.from(req.body.SAMLRequest, 'base64').toString('utf-8')) + res.send(getSignaturePage(samlRequest["samlp:AuthnRequest"]["@_ID"])) + } catch (err) { + console.error('Error processing SAML response:', err); + res.status(400).send('SAML authentication failed'); + } + } +) +``` + +現在在步驟 3 的處理常式中使用 `getSignaturePage` 取代 `getLoginPage`。 + +## 取得電子郵件地址 + +下一步是取得電子郵件地址，也就是服務提供者請求的識別碼。 為此，我們使用[以太坊證明服務 (EAS)](https://attest.org/)。 + +取得證明最簡單的方法是使用 [GraphQL API](https://docs.attest.org/docs/developer-tools/api)。 我們使用此查詢： + +``` +query GetAttestationsByRecipient { + attestations( + where: { + recipient: { equals: "${getAddress(ethAddr)}" } + schemaId: { equals: "0xfa2eff59a916e3cc3246f9aec5e0ca00874ae9d09e4678e5016006f07622f977" } + } + take: 1 + ) { + data + id + attester + } +} +``` + +這個 [`schemaId`](https://optimism.easscan.org/schema/view/0xfa2eff59a916e3cc3246f9aec5e0ca00874ae9d09e4678e5016006f07622f977) 只包含一個電子郵件地址。 此查詢要求此結構的證明。 證明的主體稱為「`recipient`」(接收者)。 它永遠是以太坊地址。 + +警告：我們在此處取得證明的方式有兩個安全問題。 + +- 我們前往的 API 端點是 `https://optimism.easscan.org/graphql`，這是一個中心化元件。 我們可以取得 `id` 屬性，然後在鏈上進行查詢以驗證證明是否真實，但 API 端點仍然可以透過不告知我們來審查證明。 + + 這個問題並非無法解決，我們可以執行自己的 GraphQL 端點並從鏈記錄中取得證明，但這對我們的目的來說太過繁瑣。 + +- 我們不看證明人的身分。 任何人都可以提供我們錯誤的資訊。 在實際的實作中，我們會有一組受信任的證明人，並且只查看他們的證明。 + +要查看此操作，請停止現有的 IdP 和 SP，並執行以下命令： + +```sh +git checkout email-address +pnpm install +pnpm start +``` + +然後提供您的電子郵件地址。 您有兩種方式可以做到： + +- 使用私密金鑰匯入錢包，並使用測試私密金鑰 `0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80`。 + +- 為您自己的電子郵件地址新增一則證明： + + 1. 在證明瀏覽器中瀏覽至[該結構](https://optimism.easscan.org/schema/view/0xfa2eff59a916e3cc3246f9aec5e0ca00874ae9d09e4678e5016006f07622f977)。 + + 2. 按一下「**使用結構證明**」。 + + 3. 輸入您的以太坊地址作為接收者，您的電子郵件地址作為 email address，並選取**鏈上**。 然後按一下「**進行證明**」。 + + 4. 在您的錢包中核准交易。 您將需要在 [Optimism 區塊鏈](https://app.optimism.io/bridge/deposit) 上擁有一些 ETH 以支付 Gas。 + +無論哪種方式，完成後請瀏覽至 [http://localhost:3000](http://localhost:3000) 並依照指示操作。 如果您匯入了測試私密金鑰，您收到的電子郵件是 `test_addr_0@example.com`。 如果您使用自己的地址，它應該是您所證明的任何內容。 + +### 詳細說明 + + + +新的步驟是 GraphQL 通訊，即步驟 5.6 和 5.7。 + +同樣，以下是 `idp.mts` 的已變更部分。 + +```typescript +import { GraphQLClient } from 'graphql-request' +import { SchemaEncoder } from '@ethereum-attestation-service/eas-sdk' +``` + +匯入我們需要的庫。 + +```typescript +const graphqlEndpointUrl = "https://optimism.easscan.org/graphql" +``` + +[每個區塊鏈都有一個獨立的端點](https://docs.attest.org/docs/developer-tools/api)。 + +```typescript +const graphqlClient = new GraphQLClient(graphqlEndpointUrl, { fetch }) +``` + +建立一個新的 `GraphQLClient` 用戶端，可用於查詢端點。 + +```typescript +const graphqlSchema = 'string emailAddress' +const graphqlEncoder = new SchemaEncoder(graphqlSchema) +``` + +GraphQL 只提供我們一個不透明的位元組資料物件。 若要理解它，我們需要結構。 + +```typescript +const ethereumAddressToEmail = async ethAddr => { +``` + +一個從以太坊地址取得電子郵件地址的函數。 + +```typescript + const query = ` + query GetAttestationsByRecipient { +``` + +這是一個 GraphQL 查詢。 + +```typescript + attestations( +``` + +我們正在尋找證明。 + +```typescript + where: { + recipient: { equals: "${getAddress(ethAddr)}" } + schemaId: { equals: "0xfa2eff59a916e3cc3246f9aec5e0ca00874ae9d09e4678e5016006f07622f977" } + } +``` + +我們想要的證明是我們結構中的證明，其中接收者是 `getAddress(ethAddr)`。 [`getAddress`](https://viem.sh/docs/utilities/getAddress#getaddress) 函數可確保我們的地址具有正確的[校驗和](https://github.com/ethereum/ercs/blob/master/ERCS/erc-55.md)。 這對於 GraphQL 而言是必要的，因為 GraphQL 區分大小寫。 「0xBAD060A7」、「0xBad060A7」和「0xbad060a7」是不同的值。 + +```typescript + take: 1 +``` + +無論我們找到多少則證明，我們只需要第一則。 + +```typescript + ) { + data + id + attester + } + }` +``` + +我們想要接收的欄位。 + +- `attester`：提交證明的地址。 通常這用於決定是否信任該證明。 +- `id`：證明 ID。 您可以使用此值[在鏈上讀取證明](https://optimism.blockscout.com/address/0x4200000000000000000000000000000000000021?tab=read_proxy&source_address=0x4E0275Ea5a89e7a3c1B58411379D1a0eDdc5b088#0xa3112a64)以驗證 GraphQL 查詢的資訊是否正確。 +- `data`：結構資料 (在此情況下為電子郵件地址)。 + +```typescript + const queryResult = await graphqlClient.request(query) + + if (queryResult.attestations.length == 0) + return "no_address@available.is" +``` + +如果沒有證明，則傳回一個明顯不正確的值，但服務提供者會認為它有效。 + +```typescript + const attestationDataFields = graphqlEncoder.decodeData(queryResult.attestations[0].data) + return attestationDataFields[0].value.value +} +``` + +如果有值，請使用 `decodeData` 解碼資料。 我們不需要它提供的中繼資料，只需要值本身。 + +```typescript + const loginResponse = await idp.createLoginResponse( + sp, + { + . + . + . + }, + "post", + { + email: await ethereumAddressToEmail(req.params.account) + } + ); +``` + +使用新函數取得電子郵件地址。 + +## 關於去中心化呢？ + +在此組態中，只要我們依賴可信的證明人進行以太坊到電子郵件地址的對應，使用者就無法冒充他人。 然而，我們的身分提供者仍然是一個中心化元件。 任何擁有身分提供者私密金鑰的人都可以向服務提供者傳送虛假資訊。 + +使用[多方運算 (MPC)](https://en.wikipedia.org/wiki/Secure_multi-party_computation) 可能是一個解決方案。 我希望在未來的教學中寫到它。 + +## 結論 + +採用登入標準 (例如以太坊簽章) 會面臨雞生蛋、蛋生雞的問題。 服務提供者希望吸引盡可能廣泛的市場。 使用者希望能夠存取服務，而不用擔心支援其登入標準。 +建立適配器 (例如以太坊 IdP) 可以幫助我們克服這個障礙。 + +[在此查看我的更多作品](https://cryptodocguy.pro/)。 diff --git a/public/content/translations/zh-tw/developers/tutorials/getting-started-with-ethereum-development-using-alchemy/index.md b/public/content/translations/zh-tw/developers/tutorials/getting-started-with-ethereum-development-using-alchemy/index.md new file mode 100644 index 00000000000..c14801cb3f5 --- /dev/null +++ b/public/content/translations/zh-tw/developers/tutorials/getting-started-with-ethereum-development-using-alchemy/index.md @@ -0,0 +1,149 @@ +--- +title: "開始以太坊開發之旅" +description: "這是一份以太坊開發的入門指南。 我們將引導您完成建立 API 端點、發出命令列請求，到撰寫您的第一個 Web3 腳本！ 無需區塊鏈開發經驗！" +author: "Elan Halpern" +tags: [ "javascript", "ethers.js", "節點", "諮詢", "alchemy" ] +skill: beginner +lang: zh-tw +published: 2020-10-30 +source: Medium +sourceUrl: https://medium.com/alchemy-api/getting-started-with-ethereum-development-using-alchemy-c3d6a45c567f +--- + + + +這是一份以太坊開發的入門指南。 在本教學中，我們將使用 [Alchemy](https://alchemyapi.io/)，這是一個領先的區塊鏈開發者平台，為 70% 的頂級區塊鏈應用程式 (包括 Maker、0x、MyEtherWallet、Dharma 和 Kyber) 的數百萬名使用者提供支援。 Alchemy 將讓我們能夠存取以太坊鏈上的 API 端點，以便我們讀取和寫入交易。 + +我們將引導您從註冊 Alchemy 到撰寫您的第一個 Web3 腳本！ 無需區塊鏈開發經驗！ + +## 1. 註冊免費的 Alchemy 帳戶 {#sign-up-for-a-free-alchemy-account} + +建立 Alchemy 帳戶很簡單，[在此免費註冊](https://auth.alchemy.com/)。 + +## 2. 建立 Alchemy 應用程式 {#create-an-alchemy-app} + +若要與以太坊鏈通訊並使用 Alchemy 的產品，您需要一個 API 金鑰來驗證您的請求。 + +您可以[從儀表板建立 API 金鑰](https://dashboard.alchemy.com/)。 若要建立新的金鑰，請如下所示導覽至「Create App」： + +特別感謝 [_ShapeShift_](https://shapeshift.com/) _讓我們展示他們的儀表板！_ + + + +在「Create App」下填寫詳細資料，即可取得新的金鑰。 您也可以在此處看到您先前建立的應用程式，以及您團隊建立的應用程式。 按一下任何應用程式的「View Key」來擷取現有的金鑰。 + + + +您也可以將游標懸停在「Apps」上並選取一個應用程式，來擷取現有的 API 金鑰。 您可以在此處「View Key」(檢視金鑰) 以及「Edit App」(編輯應用程式)，將特定網域加入白名單、查看多個開發者工具，以及檢視分析資料。 + + + +## 3 從命令列發出請求 {#make-a-request-from-the-command-line} + +透過 Alchemy 使用 JSON-RPC 和 curl 與以太坊區塊鏈互動。 + +對於手動請求，我們建議透過 `POST` 請求與 `JSON-RPC` 互動。 只需傳入 `Content-Type: application/json` 標頭，並將您的查詢作為 `POST` 主體，並包含以下欄位： + +- `jsonrpc`：JSON-RPC 版本—目前僅支援 `2.0`。 +- `method`：ETH API 方法。 [請參閱 API 參考資料。](https://docs.alchemyapi.io/documentation/alchemy-api-reference/json-rpc) +- `params`：要傳遞給方法的參數清單。 +- `id`：您請求的 ID。 回應中將會傳回此 ID，以便您追蹤哪個回應屬於哪個請求。 + +以下是您可以從命令列執行的範例，用以擷取目前的 gas 價格： + +```bash +curl https://eth-mainnet.alchemyapi.io/v2/demo \ +-X POST \ +-H "Content-Type: application/json" \ +-d '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":73}' +``` + +_\*\*注意：\*\*將 [https://eth-mainnet.alchemyapi.io/v2/demo](https://eth-mainnet.alchemyapi.io/jsonrpc/demo) 替換為您自己的 API 金鑰 `https://eth-mainnet.alchemyapi.io/v2/**your-api-key`。_ + +**結果：** + +```json +{ "id": 73,"jsonrpc": "2.0","result": "0x09184e72a000" // 10000000000000 } +``` + +## 4 設定您的 Web3 用戶端 {#set-up-your-web3-client} + +\*\*如果您有現有的用戶端，\*\*請將您目前的節點提供者 URL 變更為帶有您 API 金鑰的 Alchemy URL：`“https://eth-mainnet.alchemyapi.io/v2/your-api-key\"` + +**_注意：_** 下方的腳本需要在 **節點環境** 中執行，或 **儲存在檔案中** 執行，而非從命令列執行。 如果您尚未安裝 Node 或 npm，請查看這份快速的 [mac 版設定指南](https://app.gitbook.com/@alchemyapi/s/alchemy/guides/alchemy-for-macs)。 + +有許多 [Web3 程式庫](https://docs.alchemyapi.io/guides/getting-started#other-web3-libraries)可以與 Alchemy 整合，但我們建議使用 [Alchemy Web3](https://docs.alchemy.com/reference/api-overview)，它是 web3.js 的直接替代品，其建構與設定可和 Alchemy 無縫協作。 這提供了多種優點，例如自動重試和強大的 WebSocket 支援。 + +若要安裝 AlchemyWeb3.js，請 **導覽至您的專案目錄** 並執行： + +**使用 Yarn：** + +``` +yarn add @alch/alchemy-web3 +``` + +**使用 NPM：** + +``` +npm install @alch/alchemy-web3 +``` + +若要與 Alchemy 的節點基礎架構互動，請在 NodeJS 中執行或將此新增至 JavaScript 檔案： + +```js +const { createAlchemyWeb3 } = require("@alch/alchemy-web3") +const web3 = createAlchemyWeb3( + "https://eth-mainnet.alchemyapi.io/v2/your-api-key" +) +``` + +## 5 撰寫您的第一個 Web3 腳本！ {#write-your-first-web3-script} + +現在，讓我們來實際動手做一點 Web3 程式設計，我們將撰寫一個簡單的腳本，從以太坊主網印出最新的區塊編號。 + +**1. 如果您尚未這麼做，請在您的終端機中建立一個新的專案目錄，並用 cd 進入該目錄：** + +``` +mkdir web3-example +cd web3-example +``` + +**2. 如果您尚未這麼做，請將 Alchemy Web3 (或任何 Web3) 相依性安裝到您的專案中：** + +``` +npm install @alch/alchemy-web3 +``` + +**3. 建立一個名為 `index.js` 的檔案，並新增以下內容：** + +> 最終您應該將 `demo` 替換為您的 Alchemy HTTP API 金鑰。 + +```js +async function main() { + const { createAlchemyWeb3 } = require("@alch/alchemy-web3") + const web3 = createAlchemyWeb3("https://eth-mainnet.alchemyapi.io/v2/demo") + const blockNumber = await web3.eth.getBlockNumber() + console.log("The latest block number is " + blockNumber) +} +main() +``` + +不熟悉非同步 (async) 相關內容？ 請參閱這篇 [Medium 文章](https://medium.com/better-programming/understanding-async-await-in-javascript-1d81bb079b2c)。 + +**4. 使用 node 在您的終端機中執行它** + +``` +node index.js +``` + +**5. 您現在應該會在主控台中看到最新的區塊編號輸出！** + +``` +The latest block number is 11043912 +``` + +**讚！** 恭喜！ 您剛使用 Alchemy 撰寫了您的第一個 Web3 腳本 🎉\*\* + +不確定下一步要做什麼？ 試著部署您的第一個智能合約，並在我們的 [Hello World 智能合約指南](https://www.alchemy.com/docs/hello-world-smart-contract) 中實際動手進行一些 Solidity 程式設計，或使用 [儀表板示範應用程式](https://docs.alchemyapi.io/tutorials/demo-app) 來測試您的儀表板知識！ + +_[免費註冊 Alchemy](https://auth.alchemy.com/)、查看我們的[文件](https://www.alchemy.com/docs/)，以及如需最新消息，請在 [Twitter](https://twitter.com/AlchemyPlatform) 上追蹤我們_。 diff --git a/public/content/translations/zh-tw/developers/tutorials/guide-to-smart-contract-security-tools/index.md b/public/content/translations/zh-tw/developers/tutorials/guide-to-smart-contract-security-tools/index.md new file mode 100644 index 00000000000..4dfd52b75ec --- /dev/null +++ b/public/content/translations/zh-tw/developers/tutorials/guide-to-smart-contract-security-tools/index.md @@ -0,0 +1,102 @@ +--- +title: "智能合約安全工具指南" +description: "三種不同測試與程式分析技術的概觀" +author: "Trailofbits" +lang: zh-tw +tags: [ "穩固", "智能合約", "安全性" ] +skill: intermediate +published: 2020-09-07 +source: Building secure contracts +sourceUrl: https://github.com/crytic/building-secure-contracts/tree/master/program-analysis +--- + +我們將使用三種獨特的測試與程式分析技術： + +- \*\*透過 [Slither](/developers/tutorials/how-to-use-slither-to-find-smart-contract-bugs/) 進行靜態分析。\*\*程式的所有路徑會透過不同的程式呈現方式（例如控制流程圖）同時進行近似與分析 +- \*\*透過 [Echidna](/developers/tutorials/how-to-use-echidna-to-test-smart-contracts/) 進行模糊測試。\*\*程式碼會透過偽隨機產生的交易來執行。 模糊測試器會嘗試找到違反給定屬性的交易序列。 +- \*\*透過 [Manticore](/developers/tutorials/how-to-use-manticore-to-find-smart-contract-bugs/) 進行符號執行。\*\*一種正規的驗證技術，將每個執行路徑轉換成數學公式，並在其上檢查約束條件。 + +每種技術都有其優點和缺點，在[特定情況](#determining-security-properties)下會很有用： + +| 技術 | 工具 | 用法 | 速度 | 遺漏的錯誤 | 誤報 | +| ---- | --------- | --------------- | -- | ----- | -- | +| 靜態分析 | Slither | 命令列介面與指令碼 | 秒 | 中等 | 低 | +| 模糊測試 | Echidna | Solidity 屬性 | 分 | 低 | 無 | +| 符號執行 | Manticore | Solidity 屬性與指令碼 | 小時 | 無\* | 無 | + +\* 如果所有路徑都在沒有逾時的情況下完成探索 + +**Slither** 可在幾秒鐘內分析合約，但靜態分析可能會導致誤報，且較不適合用於複雜的檢查（例如算術檢查）。 透過應用程式介面執行 Slither，以按鈕方式存取內建的偵測器，或透過應用程式介面進行使用者定義的檢查。 + +**Echidna** 需要運行數分鐘，且只會產生真陽性結果。 Echidna 會檢查使用者提供的、以 Solidity 編寫的安全屬性。 由於它基於隨機探索，可能會遺漏錯誤。 + +**Manticore** 會執行「最重量級」的分析。 與 Echidna 類似，Manticore 也會驗證使用者提供的屬性。 它需要更長的運行時間，但可以證明屬性的有效性，且不會報告誤報。 + +## 建議工作流程 {#suggested-workflow} + +從 Slither 的內建偵測器開始，確保目前沒有簡單的錯誤，未來也不會引入。 使用 Slither 檢查與繼承、變數相依性和結構性問題相關的屬性。 隨著程式碼庫的增長，使用 Echidna 測試狀態機更複雜的屬性。 再次使用 Slither 開發自訂檢查，以提供 Solidity 中沒有的保護措施，例如防止函式被覆寫。 最後，使用 Manticore 對關鍵安全屬性（例如算術運算）執行有針對性的驗證。 + +- 使用 Slither 的命令列介面來捕捉常見問題 +- 使用 Echidna 測試合約的高階安全屬性 +- 使用 Slither 編寫自訂的靜態檢查 +- 當您想要對關鍵安全屬性進行深度保證時，請使用 Manticore + +**關於單元測試的說明**。 單元測試是建立高品質軟體的必要條件。 然而，這些技術並非最適合用來發現安全漏洞。 它們通常用於測試程式碼的正面行為（即程式碼在正常情況下如預期般運作），而安全漏洞則傾向於存在於開發者未曾考慮到的邊際情況。 在我們對數十個智能合約安全審查的研究中，我們在客戶的程式碼中發現，[單元測試覆蓋率對安全漏洞的數量或嚴重性沒有影響](https://blog.trailofbits.com/2019/08/08/246-findings-from-our-smart-contract-audits-an-executive-summary/)。 + +## 確定安全屬性 {#determining-security-properties} + +為了有效地測試和驗證您的程式碼，您必須找出需要注意的區域。 由於您在安全性上投入的資源有限，確定您程式碼庫中較弱或高價值的部分，對於優化您的投入非常重要。 威脅模型可以提供幫助。 請考慮審查： + +- [快速風險評估](https://infosec.mozilla.org/guidelines/risk/rapid_risk_assessment.html)（時間緊迫時我們的首選方法） +- [以資料為中心的系統威脅模型指南](https://csrc.nist.gov/pubs/sp/800/154/ipd) (又名 NIST 800-154) +- [Shostack 威脅模型](https://www.amazon.com/Threat-Modeling-Designing-Adam-Shostack/dp/1118809998) +- [STRIDE](https://wikipedia.org/wiki/STRIDE_\(security\)) / [DREAD](https://wikipedia.org/wiki/DREAD_\(risk_assessment_model\)) +- [PASTA](https://wikipedia.org/wiki/Threat_model#P.A.S.T.A.) +- [斷言的使用](https://blog.regehr.org/archives/1091) + +### 元件 {#components} + +了解您想檢查的內容，也有助於您選擇正確的工具。 + +與智能合約經常相關的廣泛領域包括： + +- \*\*狀態機。\*\*大多數合約都可以表示為狀態機。 考慮檢查 (1) 無法達到任何無效狀態，(2) 如果一個狀態是有效的，那麼它可以被達到，以及 (3) 沒有任何狀態會讓合約陷入陷阱。 + + - Echidna 和 Manticore 是測試狀態機規格的首選工具。 + +- \*\*存取控制。\*\*如果您的系統有特權使用者（例如擁有者、控制者等） 您必須確保 (1) 每個使用者只能執行授權的動作，以及 (2) 沒有使用者可以阻止更具特權的使用者執行動作。 + + - Slither、Echidna 和 Manticore 可以檢查存取控制的正確性。 例如，Slither 可以檢查是否只有列入白名單的函式缺少 `onlyOwner` 修飾符。 Echidna 和 Manticore 對於更複雜的存取控制很有用，例如只有在合約達到給定狀態時才授予權限。 + +- \*\*算術運算。\*\*檢查算術運算的健全性至關重要。 在各處使用 `SafeMath` 是防止溢出/下溢的好方法，但您仍需考慮其他算術缺陷，包括捨入問題和會讓合約陷入陷阱的缺陷。 + + - Manticore 是這裡的最佳選擇。 如果算術超出 SMT 求解器的範圍，可以使用 Echidna。 + +- \*\*繼承正確性。\*\*Solidity 合約高度依賴多重繼承。 很容易會出現錯誤，例如遮蔽函式缺少 `super` 呼叫，以及對 C3 線性化順序的誤解。 + + - Slither 是確保偵測到這些問題的工具。 + +- \*\*外部互動。\*\*合約會彼此互動，而某些外部合約不應被信任。 例如，如果您的合約依賴外部預言機，當一半可用的預言機遭到入侵時，它還能保持安全嗎？ + + - Manticore 和 Echidna 是測試您的合約與外部互動的最佳選擇。 Manticore 有內建機制來模擬外部合約。 + +- \*\*標準符合性。\*\*以太坊標準（例如 ERC20）的設計歷史上曾出現過瑕疵。 請注意您所依據的標準的限制。 + - Slither、Echidna 和 Manticore 將幫助您偵測與給定標準的偏差。 + +### 工具選擇快捷手冊 {#tool-selection-cheatsheet} + +| 元件 | 工具 | 範例 | +| ----- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 狀態機 | Echidna、Manticore | | +| 存取控制 | Slither、Echidna、Manticore | [Slither 練習 2](https://github.com/crytic/slither/blob/7f54c8b948c34fb35e1d61adaa1bd568ca733253/docs/src/tutorials/exercise2.md)、[Echidna 練習 2](https://github.com/crytic/building-secure-contracts/blob/master/program-analysis/echidna/exercises/Exercise-2.md) | +| 算術運算 | Manticore、Echidna | [Echidna 練習 1](https://github.com/crytic/building-secure-contracts/blob/master/program-analysis/echidna/exercises/Exercise-1.md)、[Manticore 練習 1 - 3](https://github.com/crytic/building-secure-contracts/tree/master/program-analysis/manticore/exercises) | +| 繼承正確性 | Slither | [Slither 練習 1](https://github.com/crytic/slither/blob/7f54c8b948c34fb35e1d61adaa1bd568ca733253/docs/src/tutorials/exercise1.md) | +| 外部互動 | Manticore、Echidna | | +| 標準符合性 | Slither、Echidna、Manticore | [`slither-erc`](https://github.com/crytic/slither/wiki/ERC-Conformance) | + +根據您的目標，可能還需要檢查其他領域，但這些粗略的重點領域對於任何智能合約系統來說都是一個好的開始。 + +我們的公開審計報告中包含了經過驗證或測試的屬性範例。 請考慮閱讀以下報告的「自動化測試與驗證」部分，以審查真實世界的安全屬性： + +- [0x](https://github.com/trailofbits/publications/blob/master/reviews/0x-protocol.pdf) +- [Balancer](https://github.com/trailofbits/publications/blob/master/reviews/BalancerCore.pdf) diff --git a/public/content/translations/zh-tw/developers/tutorials/hello-world-smart-contract-fullstack/index.md b/public/content/translations/zh-tw/developers/tutorials/hello-world-smart-contract-fullstack/index.md new file mode 100644 index 00000000000..5024603cfbc --- /dev/null +++ b/public/content/translations/zh-tw/developers/tutorials/hello-world-smart-contract-fullstack/index.md @@ -0,0 +1,1540 @@ +--- +title: "給初學者的 Hello World 智慧型合約 - 全端" +description: "在以太坊上撰寫和部署簡單智能合約的入門教學。" +author: "nstrike2" +tags: + [ + "穩固", + "hardhat", + "alchemy", + "智能合約", + "部署", + "區塊瀏覽器", + "前端", + "交易" + ] +skill: beginner +lang: zh-tw +published: 2021-10-25 +--- + +如果您是區塊鏈開發新手，不知道從何開始，或不知道如何部署智慧型合約並與之互動，本指南就是為您準備的。 我們將逐步說明如何使用 [MetaMask](https://metamask.io)、[Solidity](https://docs.soliditylang.org/en/v0.8.0/)、[Hardhat](https://hardhat.org) 和 [Alchemy](https://alchemy.com/eth)，在 Goerli 測試網上建立並部署一個簡單的智慧型合約。 + +您需要一個 Alchemy 帳戶才能完成本教學。 [註冊免費帳戶](https://www.alchemy.com/) + +如果您在任何時候有任何疑問，歡迎隨時到 [Alchemy Discord](https://discord.gg/gWuC7zB) 提問！ + +## 第一部分 - 使用 Hardhat 建立與部署您的智慧型合約 {#part-1} + +### 連線至以太坊網路 {#connect-to-the-ethereum-network} + +向以太坊鏈發出請求有很多種方式。 為求簡單，我們將使用 Alchemy 上的免費帳戶。Alchemy 是一個區塊鏈開發者平台及 API，讓我們無須自行執行節點就能與以太坊鏈通訊。 Alchemy 也有用於監控和分析的開發者工具；我們將在本教學中利用這些工具來了解我們智慧型合約部署的底層運作情況。 + +### 建立您的應用程式和 API 金鑰 {#create-your-app-and-api-key} + +建立 Alchemy 帳戶後，您可以透過建立應用程式來產生 API 金鑰。 這將允許您向 Goerli 測試網發出請求。 如果您不熟悉測試網，可以閱讀 [Alchemy 選擇網路的指南](https://www.alchemy.com/docs/choosing-a-web3-network)。 + +在 Alchemy 儀表板上，於導覽列中找到 **Apps** 下拉式選單，然後點擊 **Create App**。 + + + +將您的應用程式命名為「_Hello World_」，並寫下簡短描述。 選擇 **Staging** 作為您的環境，**Goerli** 作為您的網路。 + + + +_注意：請務必選擇 **Goerli**，否則本教學將無法運作。_ + +點擊 **Create app**。 您的應用程式將出現在下方的表格中。 + +### 建立一個以太坊帳戶 {#create-an-ethereum-account} + +您需要一個以太坊帳戶來傳送和接收交易。 我們將使用 MetaMask，這是一款瀏覽器內的虛擬錢包，可讓使用者管理其以太坊帳戶地址。 + +您可以在[這裡](https://metamask.io/download)免費下載並建立 MetaMask 帳戶。 在建立帳戶時，或如果您已有帳戶，請確保切換到右上角的「Goerli 測試網」(這樣我們就不會處理真實貨幣)。 + +### 第 4 步：從水龍頭取得以太幣 {#step-4-add-ether-from-a-faucet} + +要將您的智慧型合約部署到測試網，您會需要一些假的 ETH。 要在 Goerli 網路上取得 ETH，請前往 Goerli 水龍頭，並輸入您的 Goerli 帳戶地址。 請注意，Goerli 水龍頭最近可能有點不穩定 - 請參閱[測試網頁面](/developers/docs/networks/#goerli)，查看可嘗試的選項清單： + +_注意：由於網路壅塞，這可能需要一些時間。_ +`` + +### 步驟 5：檢查您的餘額 {#step-5-check-your-balance} + +為了再次確認 ETH 已在您的錢包中，讓我們使用 [Alchemy 的編寫工具](https://composer.alchemyapi.io/?composer_state=%7B%22network%22%3A0%2C%22methodName%22%3A%22eth_getBalance%22%2C%22paramValues%22%3A%5B%22%22%2C%22latest%22%5D%7D) 發出 [eth_getBalance](https://docs.alchemyapi.io/alchemy/documentation/alchemy-api-reference/json-rpc#eth_getbalance) 請求。 這將會回傳你的錢包裡的餘額。 要了解更多資訊，請查看 [Alchemy 關於如何使用編寫工具的簡短教學](https://youtu.be/r6sjRxBZJuU)。 + +輸入您的 MetaMask 帳戶地址，然後點擊 **Send Request**。 您將會看到類似下方程式碼片段的回應。 + +```json +{ "jsonrpc": "2.0", "id": 0, "result": "0x2B5E3AF16B1880000" } +``` + +> _注意：此結果以 wei 為單位，而非 ETH。_ Wei 是以太幣的最小單位。_ + +哈! 我們的假錢都在這。 + +### 步驟 6：初始化我們的專案 {#step-6-initialize-our-project} + +首先，我們需要為我們的專案建立一個資料夾。 導覽至您的命令列並輸入以下內容。 + +``` +mkdir hello-world +cd hello-world +``` + +現在我們在專案資料夾中了，我們將使用 `npm init` 來初始化專案。 + +> 如果您尚未安裝 npm，請遵循[這些說明來安裝 Node.js 和 npm](https://docs.alchemyapi.io/alchemy/guides/alchemy-for-macs#1-install-nodejs-and-npm)。 + +就本教學而言，您如何回答初始化問題並不重要。 以下是我們的做法，僅供參考： + +``` +套件名稱：(hello-world) +版本：(1.0.0) +描述：hello world 智慧型合約 +進入點：(index.js) +測試指令： +git 儲存庫： +關鍵字： +作者： +授權：(ISC) + +即將寫入 /Users/.../.../.../hello-world/package.json： + +{ + "name": "hello-world", + "version": "1.0.0", + "description": "hello world 智慧型合約", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC" +} +``` + +核准 package.json，我們就可以開始了！ + +### 步驟 7：下載 Hardhat {#step-7-download-hardhat} + +Hardhat 是一個開發環境，提供你去編譯、部屬、測試、以及除錯你的以太坊軟體。 它能協助開發人員在部署至即時鏈之前，於本機建立智慧合約和去中心化應用程式。 + +在我們的 `hello-world` 專案中執行： + +``` +npm install --save-dev hardhat +``` + +如需更多[安裝指示](https://hardhat.org/getting-started/#overview)的詳細資訊，請查看此頁面。 + +### 步驟 8：建立 Hardhat 專案 {#step-8-create-hardhat-project} + +在我們的 `hello-world` 專案資料夾中，執行： + +``` +npx hardhat +``` + +你接下來會看到歡迎訊息以及關於你想做什麼的選項。 選擇"create an empty hardhat.config.js": + +``` +888 888 888 888 888 +888 888 888 888 888 +888 888 888 888 888 +8888888888 8888b. 888d888 .d88888 88888b. 8888b. 888888 +888 888 "88b 888P" d88" 888 888 "88b "88b 888 +888 888 .d888888 888 888 888 888 888 .d888888 888 +888 888 888 888 888 Y88b 888 888 888 888 888 Y88b. +888 888 "Y888888 888 "Y88888 888 888 "Y888888 "Y888 + +👷 歡迎使用 Hardhat v2.0.11 👷 + +您想做什麼？… +建立範例專案 +❯ 建立一個空的 hardhat.config.js +退出 +``` + +這將在專案中產生一個 `hardhat.config.js` 檔案。 我們稍後將在本教學中使用此檔案來指定專案的設定。 + +### 步驟 9：新增專案資料夾 {#step-9-add-project-folders} + +為了讓專案保持井然有序，我們來建立兩個新資料夾。 在命令列中，導覽至 `hello-world` 專案的根目錄並輸入： + +``` +mkdir contracts +mkdir scripts +``` + +- `contracts/` 是我們存放 hello world 智能合約程式碼檔案的地方 +- `scripts/` 是我們存放部署和與合約互動的腳本的地方 + +### 步驟 10：編寫我們的合約 {#step-10-write-our-contract} + +您可能會問自己，我們什麼時候才要開始寫程式碼？ 就是現在！ + +在您喜歡的編輯器中開啟 hello-world 專案。 智慧型合約最常用 Solidity 編寫，我們將使用它來編寫我們的智慧型合約。 + +1. 導覽至 `contracts` 資料夾並建立一個名為 `HelloWorld.sol` 的新檔案 +2. 以下是我們將在本教學中使用的範例 Hello World 智慧型合約。 將以下內容複製到 `HelloWorld.sol` 檔案中。 + +_注意：請務必閱讀註解以了解此合約的功能。_ + +``` +// 指定 Solidity 的版本，使用語意化版本控制。 +// 了解更多：https://solidity.readthedocs.io/en/v0.5.10/layout-of-source-files.html#pragma +pragma solidity >=0.7.3; + +// 定義一個名為「HelloWorld」的合約。 +// 合約是函式和資料 (其狀態) 的集合。部署後，合約會存放在以太坊區塊鏈的特定地址上。了解更多：https://solidity.readthedocs.io/en/v0.5.10/structure-of-a-contract.html +contract HelloWorld { + + // 呼叫更新函式時發出 + // 智慧型合約事件是您合約的一種方式，可將區塊鏈上發生的事情傳達給您的應用程式前端，前端可以「監聽」某些事件並在事件發生時採取行動。 + event UpdatedMessages(string oldStr, string newStr); + + // 宣告一個「string」類型的狀態變數「message」。 + // 狀態變數是其值永久儲存在合約儲存空間中的變數。關鍵字「public」可讓變數從合約外部存取，並建立一個其他合約或用戶端可呼叫以存取該值的函式。 + string public message; + + // 與許多以類別為基礎的物件導向語言相似，建構函式是一個特殊函式，只在合約建立時執行。 + // 建構函式用於初始化合約的資料。了解更多：https://solidity.readthedocs.io/en/v0.5.10/contracts.html#constructors + constructor(string memory initMessage) { + + // 接受一個字串引數「initMessage」，並將該值設定到合約的「message」儲存變數中)。 + message = initMessage; + } + + // 一個公共函式，接受一個字串引數並更新「message」儲存變數。 + function update(string memory newMessage) public { + string memory oldMsg = message; + message = newMessage; + emit UpdatedMessages(oldMsg, newMessage); + } +} +``` + +這是一個基本的智慧型合約，在建立時儲存一則訊息。 可以透過呼叫 `update` 函式來更新。 + +### 步驟 11：將 MetaMask 和 Alchemy 連線至您的專案 {#step-11-connect-metamask-alchemy-to-your-project} + +我們已經建立了 MetaMask 錢包、Alchemy 帳戶，並編寫了我們的智能合約，現在是時候將這三者連接起來了。 + +從您的錢包傳送的每筆交易都需要使用您唯一的私密金鑰簽署。 為了向我們的程式提供此權限，我們可以安全地將我們的私密金鑰儲存在環境檔案中。 我們也將在此處儲存 Alchemy 的 API 金鑰。 + +> 若要深入了解如何傳送交易，請查看這篇關於使用 web3 傳送交易的[教學](https://www.alchemy.com/docs/hello-world-smart-contract#step-11-connect-metamask--alchemy-to-your-project)。 + +首先，安裝 dotenv 套件。 + +``` +npm install dotenv --save +``` + +然後，在專案的根目錄中建立一個 `.env` 檔案。 將您的 MetaMask 私密金鑰和 HTTP Alchemy API URL 新增至其中。 + +您的環境檔案必須命名為 `.env`，否則它將不會被辨識為環境檔案。 + +請勿將其命名為 `process.env`、`.env-custom` 或任何其他名稱。 + +- 請遵循[這些說明](https://metamask.zendesk.com/hc/en-us/articles/360015289632-How-to-Export-an-Account-Private-Key)來匯出您的私密金鑰 +- 請參閱下文以取得 HTTP Alchemy API URL + + + +你的 `.env` 應該看起來像這樣： + +``` +API_URL = "https://eth-goerli.alchemyapi.io/v2/your-api-key" +PRIVATE_KEY = "your-metamask-private-key" +``` + +為了實際將這些連接到我們的程式碼，我們將在第 13 步的 `hardhat.config.js` 檔案中引用這些變數。 + +### 第 12 步：安裝 Ethers.js {#step-12-install-ethersjs} + +Ethers.js 是一個函式庫，它透過將[標準 JSON-RPC 方法](https://docs.alchemyapi.io/alchemy/documentation/alchemy-api-reference/json-rpc)包裝成更方便使用者使用的方法，讓與以太坊的互動和請求變得更容易。 + +Hardhat 可讓您整合[外掛程式](https://hardhat.org/plugins/)以取得額外的工具和擴充功能。 我們將利用 [Ethers 外掛程式](https://hardhat.org/docs/plugins/official-plugins#hardhat-ethers)來部署合約。 + +在你的專案目錄輸入： + +```bash +npm install --save-dev @nomiclabs/hardhat-ethers "ethers@^5.0.0" +``` + +### 步驟 13：更新 hardhat.config.js {#step-13-update-hardhat-configjs} + +我們目前已經新增了幾個相依套件和外掛程式，現在我們需要更新 `hardhat.config.js`，讓我們的專案知道它們全部。 + +將你的 `hardhat.config.js` 更新成如下所示： + +```javascript +/** + * @type import('hardhat/config').HardhatUserConfig + */ + +require("dotenv").config() +require("@nomiclabs/hardhat-ethers") + +const { API_URL, PRIVATE_KEY } = process.env + +module.exports = { + solidity: "0.7.3", + defaultNetwork: "goerli", + networks: { + hardhat: {}, + goerli: { + url: API_URL, + accounts: [`0x${PRIVATE_KEY}`], + }, + }, +} +``` + +### 步驟 14：編譯我們的合約 {#step-14-compile-our-contract} + +為了確認一切運作正常，我們來編譯合約。 `compile` 任務是內建的 hardhat 任務之一。 + +在命令列工具輸入： + +```bash +npx hardhat compile +``` + +您可能會收到關於「原始程式檔中未提供 SPDX 授權識別碼」的警告，但無須擔心，希望其他一切都沒問題！ 如果沒有，您隨時可以在 [Alchemy discord](https://discord.gg/u72VCg3) 中傳送訊息。 + +### 步驟 15：編寫我們的部署指令碼 {#step-15-write-our-deploy-script} + +現在我們已經寫好了合約，並且也搞定配置檔案。現在我們該來撰寫部署合約的腳本。 + +導覽至 `scripts/` 資料夾並建立一個名為 `deploy.js` 的新檔案，將以下內容加入其中： + +```javascript +async function main() { + const HelloWorld = await ethers.getContractFactory("HelloWorld") + + // 開始部署，回傳一個解析為合約物件的 promise + const hello_world = await HelloWorld.deploy("Hello World!") + console.log("合約已部署至地址：", hello_world.address) +} + +main() + .then(() => process.exit(0)) + .catch((error) => { + console.error(error) + process.exit(1) + }) +``` + +Hardhat 在其[合約教學文章](https://hardhat.org/tutorial/testing-contracts.html#writing-tests)中詳細地解釋了每一行程式碼的作用，我們在此採用了他們的解釋。 + +```javascript +const HelloWorld = await ethers.getContractFactory("HelloWorld") +``` + +ethers.js 中的 `ContractFactory` 是用於部署新智慧型合約的抽象概念，因此這裡的 `HelloWorld` 是我們 hello world 合約執行個體的[工廠](https://en.wikipedia.org/wiki/Factory_\(object-oriented_programming\))。 使用 `hardhat-ethers` 外掛程式時，`ContractFactory` 和 `Contract` 執行個體預設會連線至第一個簽署者 (擁有者)。 + +```javascript +const hello_world = await HelloWorld.deploy() +``` + +在 `ContractFactory` 上呼叫 `deploy()` 將會開始部署，並回傳一個解析為 `Contract` 物件的 `Promise`。 這就是和我們的智慧型合約函數有一對一的方法的物件。 + +### 第 16 步：部署我們的合約 {#step-16-deploy-our-contract} + +我們終於準備好要部署合約了！ 導覽至命令列並執行： + +```bash +npx hardhat run scripts/deploy.js --network goerli +``` + +你會看到像這樣的輸出： + +```bash +合約已部署至地址：0x6cd7d44516a20882cEa2DE9f205bF401c0d23570 +``` + +**請儲存此地址**。 我們稍後將在本教學中使用它。 + +如果我們前往 [Goerli etherscan](https://goerli.etherscan.io) 並搜尋我們的合約地址，我們應該能夠看到它已成功部署。 這個交易執行看起來會像這樣： + + + +`From` 地址應與您的 MetaMask 帳戶地址相符，而 `To` 地址將顯示 **Contract Creation**。 如果我們點擊進入交易，我們將在 `To` 欄位中看到我們的合約地址。 + + + +恭喜！ 您剛剛將智慧型合約部署到以太坊測試網。 + +若要了解底層的運作情況，讓我們導覽至 [Alchemy 儀表板](https://dashboard.alchemy.com/explorer)中的 Explorer 標籤。 如果您有多個 Alchemy 應用程式，請務必依應用程式篩選並選取 **Hello World**。 + + + +在這裡您會看到當我們呼叫 `.deploy()` 函式時，Hardhat/Ethers 在幕後為我們進行的一些 JSON-RPC 方法。 這裡有兩個重要的方法：[`eth_sendRawTransaction`](https://docs.alchemyapi.io/alchemy/documentation/alchemy-api-reference/json-rpc#eth_sendrawtransaction) (這是將我們的合約寫入 Goerli 鏈的請求)，以及 [`eth_getTransactionByHash`](https://docs.alchemyapi.io/alchemy/documentation/alchemy-api-reference/json-rpc#eth_gettransactionbyhash) (這是在給定哈希值的情況下，讀取我們交易資訊的請求)。 若要深入了解如何傳送交易，請查看[我們關於使用 Web3 傳送交易的教學](/developers/tutorials/sending-transactions-using-web3-and-alchemy/)。 + +## 第二部分：與您的智慧型合約互動 {#part-2-interact-with-your-smart-contract} + +既然我們已成功將智慧型合約部署至 Goerli 網路，讓我們來學習如何與它互動。 + +### 建立一個 interact.js 檔案 {#create-a-interactjs-file} + +這就是我們將編寫互動腳本的檔案。 我們將使用您先前在第一部分中安裝的 Ethers.js 函式庫。 + +在 `scripts/` 資料夾中，建立一個名為 `interact.js` 的新檔案，並新增以下程式碼： + +```javascript +// interact.js + +const API_KEY = process.env.API_KEY +const PRIVATE_KEY = process.env.PRIVATE_KEY +const CONTRACT_ADDRESS = process.env.CONTRACT_ADDRESS +``` + +### 更新您的 .env 檔案 {#update-your-env-file} + +我們將使用新的環境變數，因此我們需要在[先前建立](#step-11-connect-metamask-&-alchemy-to-your-project) 的 `.env` 檔案中定義它們。 + +我們需要新增我們的 Alchemy `API_KEY` 和部署智慧型合約的 `CONTRACT_ADDRESS` 的定義。 + +您的 `.env` 檔案應如下所示： + +```bash +# .env + +API_URL = "https://eth-goerli.alchemyapi.io/v2/
+ 
+
+
+
+)
+```
+
+如果您仔細掃描此程式碼，您會注意到我們在 UI 中使用了各種狀態變數：
+
+- 在第 6-12 行，如果使用者的錢包已連線 (即 `walletAddress.length > 0`)，我們會在 ID 為「walletButton」的按鈕中顯示使用者 `walletAddress` 的截斷版本；否則它只會顯示「連線錢包」。
+- 在第 17 行，我們顯示儲存在智慧型合約中的目前訊息，該訊息擷取在 `message` 字串中。
+- 在第 23-26 行，我們使用[受控元件](https://legacy.reactjs.org/docs/forms.html#controlled-components)來更新我們的 `newMessage` 狀態變數，當文字欄位中的輸入變更時。
+
+除了我們的狀態變數，您還會看到 `connectWalletPressed` 和 `onUpdatePressed` 函式分別在點擊 ID 為 `publishButton` 和 `walletButton` 的按鈕時被呼叫。
+
+最後，讓我們來處理這個 `HelloWorld.js` 元件被新增到哪裡的問題。
+
+如果您前往 `App.js` 檔案，這是 React 中的主要元件，作為所有其他元件的容器，您會看到我們的 `HelloWorld.js` 元件被注入在第 7 行。
+
+最後但同樣重要的是，讓我們查看為您提供的另一個檔案，即 `interact.js` 檔案。
+
+#### `interact.js` 檔案 {#the-interact-js-file}
+
+因為我們想要遵循 [M-V-C](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) 範式，我們將需要一個單獨的檔案，其中包含我們所有的函式來管理我們去中心化應用程式的邏輯、資料和規則，然後能夠將這些函式匯出到我們的前端 (我們的 `HelloWorld.js` 元件)。
+
+👆🏽這正是我們的 `interact.js` 檔案的目的！
+
+導覽至您 `src` 目錄中的 `util` 資料夾，您會注意到我們包含了一個名為 `interact.js` 的檔案，它將包含我們所有的智慧型合約互動和錢包函式與變數。
+
+```javascript
+// interact.js
+
+//export const helloWorldContract;
+
+export const loadCurrentMessage = async () => {}
+
+export const connectWallet = async () => {}
+
+const getCurrentWalletConnected = async () => {}
+
+export const updateMessage = async (message) => {}
+```
+
+您會注意到檔案頂端，我們已註解掉 `helloWorldContract` 物件。 稍後在本教學中，我們將取消註解此物件，並在此變數中實例化我們的智慧型合約，然後我們將其匯出至我們的 `HelloWorld.js` 元件。
+
+我們 `helloWorldContract` 物件之後的四個未實作函式執行以下操作：
+
+- `loadCurrentMessage` - 此函式處理載入儲存在智慧型合約中目前訊息的邏輯。 它將使用 [Alchemy Web3 API](https://github.com/alchemyplatform/alchemy-web3) 對 Hello World 智慧型合約進行_讀取_呼叫。
+- `connectWallet` - 此函式將把使用者的 MetaMask 連線至我們的去中心化應用程式。
+- `getCurrentWalletConnected` - 此函式將在頁面載入時檢查以太坊帳戶是否已連線至我們的去中心化應用程式，並相應地更新我們的 UI。
+- `updateMessage` - 此函式將更新儲存在智慧型合約中的訊息。 它將對 Hello World 智慧型合約進行_寫入_呼叫，因此使用者的 MetaMask 錢包必須簽署一筆以太坊交易才能更新訊息。
+
+既然我們了解了我們正在處理的內容，讓我們來弄清楚如何從我們的智慧型合約中讀取！
+
+### 步驟 3：從您的智慧型合約讀取 {#step-3-read-from-your-smart-contract}
+
+若要從您的智慧型合約讀取，您需要成功設定：
+
+- 與以太坊鏈的 API 連線
+- 您智慧型合約的載入執行個體
+- 呼叫您智慧型合約函式的函式
+- 一個監聽器，用於在您從智慧型合約讀取的資料變更時監看更新
+
+這聽起來可能有很多步驟，但別擔心！ 我們將一步一步引導您完成它們！ :\)
+
+#### 建立與以太坊鏈的 API 連線 {#establish-an-api-connection-to-the-ethereum-chain}
+
+還記得在本教學的第二部分中，我們如何使用我們的 [Alchemy Web3 金鑰從我們的智慧型合約讀取](https://docs.alchemy.com/alchemy/tutorials/hello-world-smart-contract/interacting-with-a-smart-contract#step-1-install-web3-library)嗎？ 您還需要在您的去中心化應用程式中使用 Alchemy Web3 金鑰才能從鏈上讀取。
+
+如果您還沒有，首先安裝 [Alchemy Web3](https://github.com/alchemyplatform/alchemy-web3)，方法是導覽至您 `starter-files` 的根目錄，並在您的終端機中執行以下指令：
+
+```text
+npm install @alch/alchemy-web3
+```
+
+[Alchemy Web3](https://github.com/alchemyplatform/alchemy-web3) 是 [Web3.js](https://docs.web3js.org/) 的一個包裝器，提供了增強的 API 方法和其他關鍵優勢，讓你的 web3 開發者生活更輕鬆。 它是被設計成最低配置，因此你能夠在你的應用程式內馬上開始使用它！
+
+然後，在您的專案目錄中安裝 [dotenv](https://www.npmjs.com/package/dotenv) 套件，這樣我們在取得 API 金鑰後就有一個安全的地方來儲存它。
+
+```text
+npm install dotenv --save
+```
+
+對於我們的去中心化應用程式，**我們將使用我們的 Websockets API 金鑰** 而非我們的 HTTP API 金鑰，因為它將允許我們設定一個監聽器，偵測儲存在智慧型合約中的訊息何時變更。
+
+取得您的 API 金鑰後，在您的根目錄中建立一個 `.env` 檔案，並將您的 Alchemy Websockets url 新增至其中。 之後，您的 `.env` 檔案應如下所示：
+
+```javascript
+REACT_APP_ALCHEMY_KEY = wss://eth-goerli.ws.alchemyapi.io/v2/目前訊息：
+{message}
+ +新訊息：
+ +
+ setNewMessage(e.target.value)}
+ value={newMessage}
+ />
+
+
+{status}
+ + ++ {" "} + 🦊 + 您必須在瀏覽器中安裝 MetaMask，這是一款虛擬以太坊錢包。 + +
+ + ), + } + } +} +``` + +那麼這段龐大的程式碼究竟做了什麼？ + +首先，它會檢查您的瀏覽器中是否啟用了 `window.ethereum`。 + +`window.ethereum` 是由 MetaMask 和其他錢包提供者注入的全域 API，允許網站請求使用者的以太坊帳戶。 如果獲得批准，它可以從使用者連線的區塊鏈讀取資料，並建議使用者簽署訊息和交易。 查看 [MetaMask 文件](https://docs.metamask.io/guide/ethereum-provider.html#table-of-contents)以獲得更多資訊！ + +如果 `window.ethereum` _不存在_，那表示 MetaMask 沒有安裝。 這會回傳一個 JSON 物件，其中回傳的 `address` 是一個空字串，而 `status` JSX 物件則傳達使用者必須安裝 MetaMask 的訊息。 + +現在如果 `window.ethereum` _存在_，事情就變得有趣了。 + +使用 try/catch 迴圈，我們將透過呼叫 [`window.ethereum.request({ method: "eth_requestAccounts" });`](https://docs.metamask.io/guide/rpc-api.html#eth-requestaccounts) 來嘗試連接 MetaMask。 呼叫這個函式會在瀏覽器中開啟 MetaMask，提示使用者將他們的錢包連接到你的去中心化應用程式。 + +- 如果使用者選擇連線，`method: "eth_requestAccounts"` 將回傳一個陣列，其中包含所有連線至去中心化應用程式的使用者帳戶地址。 總而言之，我們的 `connectWallet` 函式會回傳一個 JSON 物件，其中包含此陣列中的_第一個_ `address` (見第 9 行) 和一則 `status` 訊息，提示使用者向智能合約寫入一則訊息。 +- 如果使用者拒絕連接，那麼 JSON 物件將包含一個空字串作為回傳的 `address`，以及一則反映使用者拒絕連接的 `status` 訊息。 + +既然我們已編寫此 `connectWallet` 函式，下一步就是將它呼叫至我們的 `HelloWorld.js` 元件。 + +#### 將 `connectWallet` 函式新增至您的 `HelloWorld.js` UI 元件 {#add-the-connectWallet-function-to-your-HelloWorld-js-ui-component} + +導覽至 `HelloWorld.js` 中的 `connectWalletPressed` 函式，並將其更新為以下內容： + +```javascript +// HelloWorld.js + +const connectWalletPressed = async () => { + const walletResponse = await connectWallet() + setStatus(walletResponse.status) + setWallet(walletResponse.address) +} +``` + +注意到我們的大部分功能是如何從 `interact.js` 檔案中抽象出來，遠離我們的 `HelloWorld.js` 元件嗎？ 這是我們跟M-V-C規範相容的做法！ + +在 `connectWalletPressed` 中，我們只需對匯入的 `connectWallet` 函式進行一個 await 呼叫，並利用其回應，透過它們的 state hooks 更新我們的 `status` 和 `walletAddress` 變數。 + +現在，讓我們儲存這兩個檔案 (`HelloWorld.js` 和 `interact.js`)，並測試一下我們目前的 UI。 + +在 [http://localhost:3000/](http://localhost:3000/) 頁面上開啟您的瀏覽器，並按下頁面右上角的「連線錢包」按鈕。 + +如果你已安裝 MetaMask，系統應該會提示你將錢包連接到你的去中心化應用程式。 請接受進行連結的邀請。 + +您應該會看到錢包按鈕現在反映您的地址已連線！ 太棒了 🔥 + +接下來，試著重新整理頁面... 這很奇怪。 我們的錢包按鈕會鼓勵我們對MetaMask進行連結，就算它已經被連結好了。。。。。。 + +不過，別擔心！ 我們可以輕鬆地處理這個問題 (懂嗎？) 透過實作 `getCurrentWalletConnected`，它將檢查是否有地址已連線至我們的去中心化應用程式，並相應地更新我們的 UI！ + +#### `getCurrentWalletConnected` 函式 {#the-getcurrentwalletconnected-function} + +將您 `interact.js` 檔案中的 `getCurrentWalletConnected` 函式更新為以下內容： + +```javascript +// interact.js + +export const getCurrentWalletConnected = async () => { + if (window.ethereum) { + try { + const addressArray = await window.ethereum.request({ + method: "eth_accounts", + }) + if (addressArray.length > 0) { + return { + address: addressArray[0], + status: "👆🏽 在上方的文字欄位中寫一則訊息。", + } + } else { + return { + address: "", + status: "🦊 使用右上角按鈕連線至 MetaMask。", + } + } + } catch (err) { + return { + address: "", + status: "😥 " + err.message, + } + } + } else { + return { + address: "", + status: ( + ++ {" "} + 🦊 + 您必須在瀏覽器中安裝 MetaMask，這是一款虛擬以太坊錢包。 + +
+ + ), + } + } +} +``` + +這段程式碼與我們剛在上一步中編寫的 `connectWallet` 函式_非常_相似。 + +主要的區別在於，我們不是呼叫 `eth_requestAccounts` 方法 (這會開啟 MetaMask 讓使用者連接他們的錢包)，而是在這裡呼叫 `eth_accounts` 方法，它只會回傳一個包含當前連接到我們去中心化應用程式的 MetaMask 位址的陣列。 + +若要查看此函式的實際運作情況，讓我們在我們的 `HelloWorld.js` 元件的 `useEffect` 函式中呼叫它： + +```javascript +// HelloWorld.js + +useEffect(async () => { + const message = await loadCurrentMessage() + setMessage(message) + addSmartContractListener() + + const { address, status } = await getCurrentWalletConnected() + setWallet(address) + setStatus(status) +}, []) +``` + +注意，我們使用對 `getCurrentWalletConnected` 呼叫的回應來更新我們的 `walletAddress` 和 `status` 狀態變數。 + +既然您已新增此程式碼，讓我們試著重新整理我們的瀏覽器視窗。 + +太棒了！ 這個按鈕應該會跟你說：「你已經連結好了。」，然後會顯出一個你錢包被連結好的地址的預視 - 就算在你刷新之後也會這樣！ + +#### 實作 `addWalletListener` {#implement-addwalletlistener} + +我們去中心化應用程式錢包設定的最後一個步驟是實作錢包監聽器，這樣當我們錢包的狀態改變時 (例如使用者中斷連線或切換帳戶)，我們的 UI 就會更新。 + +在您的 `HelloWorld.js` 檔案中，將您的 `addWalletListener` 函式修改為以下內容： + +```javascript +// HelloWorld.js + +function addWalletListener() { + if (window.ethereum) { + window.ethereum.on("accountsChanged", (accounts) => { + if (accounts.length > 0) { + setWallet(accounts[0]) + setStatus("👆🏽 在上方的文字欄位中寫一則訊息。") + } else { + setWallet("") + setStatus("🦊 使用右上角按鈕連線至 MetaMask。") + } + }) + } else { + setStatus( ++ {" "} + 🦊 + 您必須在瀏覽器中安裝 MetaMask，這是一款虛擬以太坊錢包。 + +
+ ) + } +} +``` + +我敢打賭，此時您甚至不需要我們的幫助就能了解這裡發生了什麼事，但為了周全起見，讓我們快速分解一下： + +- 首先，我們的函式會檢查 `window.ethereum` 是否已啟用 (即 MetaMask 已安裝)。 + - 如果沒有啟用，我們只需將 `status` 狀態變數設定為一個 JSX 字串，提示使用者安裝 MetaMask。 + - 如果已啟用，我們在第 3 行設定監聽器 `window.ethereum.on("accountsChanged")`，它會監聽 MetaMask 錢包的狀態變化，包括使用者將額外帳戶連接到去中心化應用程式、切換帳戶或中斷帳戶連線時。 如果至少有一個帳戶已連接，`walletAddress` 狀態變數會更新為監聽器回傳的 `accounts` 陣列中的第一個帳戶。 否則，`walletAddress` 會被設定為空字串。 + +最後但同樣重要的是，我們必須在我們的 `useEffect` 函式中呼叫它： + +```javascript +// HelloWorld.js + +useEffect(async () => { + const message = await loadCurrentMessage() + setMessage(message) + addSmartContractListener() + + const { address, status } = await getCurrentWalletConnected() + setWallet(address) + setStatus(status) + + addWalletListener() +}, []) +``` + +就是這樣！ 我們已成功完成所有錢包功能的編寫！ 現在進入我們最後的任務：更新儲存在我們智慧型合約中的訊息！ + +### 步驟 6：實作 `updateMessage` 函式 {#step-6-implement-the-updateMessage-function} + +好了，各位，我們已進入最後階段！ 在您 `interact.js` 檔案的 `updateMessage` 中，我們將執行以下操作： + +1. 確保我們希望在我們的智慧合約中發布的訊息是有效的 +2. 使用 MetaMask 簽署我們的交易 +3. 從我們的 `HelloWorld.js` 前端元件呼叫此函式 + +這不會花很長時間；讓我們完成這個去中心化應用程式！ + +#### 輸入錯誤處理 {#input-error-handling} + +自然地，在函式開始時進行某種輸入錯誤處理是合理的。 + +如果沒有安裝 MetaMask 擴充功能、沒有連線錢包 (即傳入的 `address` 是空字串)，或者 `message` 是空字串，我們希望我們的函式能提早回傳。 讓我們將以下錯誤處理新增至 `updateMessage`： + +```javascript +// interact.js + +export const updateMessage = async (address, message) => { + if (!window.ethereum || address === null) { + return { + status: + "💡 連線您的 MetaMask 錢包以更新區塊鏈上的訊息。", + } + } + + if (message.trim() === "") { + return { + status: "❌ 您的訊息不能是空字串。", + } + } +} +``` + +既然它有了適當的輸入錯誤處理，是時候透過 MetaMask 簽署交易了！ + +#### 簽署我們的交易 {#signing-our-transaction} + +如果您已經熟悉傳統的 web3 以太坊交易，我們接下來編寫的程式碼將會非常熟悉。 在您的輸入錯誤處理程式碼下方，將以下內容新增至 `updateMessage`： + +```javascript +// interact.js + +//設定交易參數 +const transactionParameters = { + to: contractAddress, // 合約發布期間除外為必要 + from: address, // 必須與使用者目前的地址相符 + data: helloWorldContract.methods.update(message).encodeABI(), +} + +//簽署交易 +try { + const txHash = await window.ethereum.request({ + method: "eth_sendTransaction", + params: [transactionParameters], + }) + return { + status: ( + + ✅{" "} + + 在 Etherscan 上查看您交易的狀態！ + ++ ℹ️ 交易一旦經網路驗證，訊息將自動更新。 + + ), + } +} catch (error) { + return { + status: "😥 " + error.message, + } +} +``` + +讓我們來分解一下發生了什麼事。 首先，我們設定我們的交易參數，其中： + +- `to` 指定接收方位址 (我們的智能合約) +- `from` 指定交易的簽署者，即我們傳入函式的 `address` 變數 +- `data` 包含對我們 Hello World 智慧型合約的 `update` 方法的呼叫，並接收我們的 `message` 字串變數作為輸入 + +然後，我們進行一個 await 呼叫，`window.ethereum.request`，我們在此請求 MetaMask 簽署交易。 請注意，在第 11 和 12 行，我們正在指定我們的 eth 方法 `eth_sendTransaction`，並傳入我們的 `transactionParameters`。 + +在這時機，MetaMask將會在瀏覽器中被開啟，然後鼓勵用戶去簽署或拒絕該筆交易。 + +- 如果交易成功，函式將回傳一個 JSON 物件，其中 `status` JSX 字串會提示使用者查看 Etherscan 以取得有關其交易的更多資訊。 +- 如果交易失敗，函式將回傳一個 JSON 物件，其中 `status` 字串會轉達錯誤訊息。 + +總而言之，我們的 `updateMessage` 函式應如下所示： + +```javascript +// interact.js + +export const updateMessage = async (address, message) => { + //輸入錯誤處理 + if (!window.ethereum || address === null) { + return { + status: + "💡 連線您的 MetaMask 錢包以更新區塊鏈上的訊息。", + } + } + + if (message.trim() === "") { + return { + status: "❌ 您的訊息不能是空字串。", + } + } + + //設定交易參數 + const transactionParameters = { + to: contractAddress, // 合約發布期間除外為必要 + from: address, // 必須與使用者目前的地址相符 + data: helloWorldContract.methods.update(message).encodeABI(), + } + + //簽署交易 + try { + const txHash = await window.ethereum.request({ + method: "eth_sendTransaction", + params: [transactionParameters], + }) + return { + status: ( + + ✅{" "} + + 在 Etherscan 上查看您交易的狀態！ + +
+ ℹ️ 交易一旦經網路驗證，訊息將自動更新。 + + ), + } + } catch (error) { + return { + status: "😥 " + error.message, + } + } +} +``` + +最後但同樣重要的是，我們需要將我們的 `updateMessage` 函式連線至我們的 `HelloWorld.js` 元件。 + +#### 將 `updateMessage` 連線至 `HelloWorld.js` 前端 {#connect-updatemessage-to-the-helloworld-js-frontend} + +我們的 `onUpdatePressed` 函式應對匯入的 `updateMessage` 函式進行 await 呼叫，並修改 `status` 狀態變數以反映我們的交易是成功還是失敗： + +```javascript +// HelloWorld.js + +const onUpdatePressed = async () => { + const { status } = await updateMessage(walletAddress, newMessage) + setStatus(status) +} +``` + +它非常乾淨簡單。 您猜怎麼著... 您的去中心化應用程式完成了！！！ + +去測試一下**更新**按鈕吧！ + +### 製作您自己的自訂去中心化應用程式 {#make-your-own-custom-dapp} + +哇，您完成了本教學！ 總結一下，您學會了如何： + +- 將 MetaMask 錢包連線至您的去中心化應用程式專案 +- 使用 [Alchemy Web3](https://docs.alchemy.com/alchemy/documentation/alchemy-web3) API 從您的智慧型合約讀取資料 +- 使用 MetaMask 簽署以太坊交易 + +現在您已完全具備應用本教學的技能，可以打造您自己的自訂去中心化應用程式專案了！ 一如既往，如果您有任何問題，請隨時到 [Alchemy Discord](https://discord.gg/gWuC7zB) 尋求協助。 🧙♂️ + +完成本教學後，請在 Twitter 上標記我們 [@alchemyplatform](https://twitter.com/AlchemyPlatform)，讓我們知道您的體驗如何，或是否有任何回饋！