軟體工程師/其他身份探詢中

斜槓工程師的問題筆記

很常在 Dashboard 的範例看到的圖表形勢，一個很大的業績數字展現在上面，如果想要展示一些很重要或是很棒的資料內容就可以用的圖表。
## Big Number
展示一個大數字，用以強調目標指標。
![Big Number Chart](/images/big-number-chart.png)
上圖展示下面 SQL 回傳的資料筆數。
```sql
SELECT *
FROM public.users
```
### Query
- Metric：顯示的邏輯，這裡顯示所有資料的比數。
- Filter：篩選器
- Subheader：說明資料內容的標題。

## Big Number with Trendline
與上面的圖表相同，但包含折線圖，可以用以展示趨勢。
![Big Number Train Chart](/images/big-number-train-chart.png)
假設我們的 dataset 存的是每年世界人口的數目，就可以用這張圖來展示人口的趨勢。

### Query
- Temporal x-axis：用以在時間軸顯示的資料欄位，只接受「時間」類型的欄位。
- Time grain：時間粒度，定義每一個顯示間隔的時間單位，如果沒有設定則會以每筆資料的 Temporal x-axis 作為間隔。
- Metric：折線圖的呈現來源，在這裡就是人口總數。

![Big Number Chart Options](/images/big-number-train-chart-options.png)
### Options
用來調整強調數字與過往資料比較的呈現內容。呈現的位置會在大字底下的一行。
- Comparison period lag： 要與多久與前的資料比較。  
如果粒度是日（Daily）：Lag 值設為 7，則會與前一週同一天的數據進行比較。  
如果粒度是月（Monthly）：Lag 值設為 12，則會與去年同一個月的數據進行比較。  
如果粒度是年（Yearly）：Lag 值設為 1，則會與前一年的數據進行比較。  
例如這裡設定 10，就會與 10 年前的資料做比較。此處以 time grain 作為單位。  
- Comparison suffix：說明的文字。
- Show timestamp：打勾的話會在大字上顯示此資料的時間點。
- Show trend Line：勾選後才會呈現趨勢線。
- Start y-axis at 0：是否要以 0 作為 y 軸的起點，若沒有勾選，則最小值的那筆資料會作為圖表呈現的最底。
![Big Number Chart Options](/images/big-number-train-chart-options.gif)

### Advanced Analytics
![Big Number Chart Advanced Analytics](/images/big-number-train-chart-advanced-analytics.png)
#### Rolling Window
計算一個移動窗口內的值。用來平滑數據波動，更方便於觀察長期趨勢。
- Rolling Functions：  
  mean：移動平均  
  sum：移動總和  
  std：標準差  
  cumsum：累加  
- Periods：用來計算的資料量。
- Min Periods：用於計算的最小資料量。

#### Resample
這裡會用來設定 Pandas 的計算規則，可以更近一步地將資料以特定時間區間重新聚合與展示。
- Rule：重新設定時間粒度。
- Full Method：如果資料缺失的填補方式。  
  Zero：將所有缺失值填補為 0。  
  Linear：根據相鄰資料點之間的線性關係進行插值。  
  Forward：用缺失值的前一個有效值進行填充。  
  Backward：用缺失值之後的第一個有效值進行填充。  
  Median：使用整個資料集的中位數進行填充。  
  Sum：將特定時間段（以 Rule 的設定為準）的資料值加總填充。  
  Mean：使用整個資料集合的平均值進行填充。  

## 參考資料
- [Pandas](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.resample.html)
- [Preset](https://docs.preset.io/docs/big-number-chart)

[Superset] Big Number (with Trendline)


## 問題情境
承接[上一篇文章](/../posts/technology/use-docker-to-assist-my-work)，目前已經可以透過單個容器來達成下面的成果。
1. 啟動一個直接運行的專案或服務。
2. 啟動一個擁有合適環境的容器，並且掛載要開法的專案進去，免除在本地安裝環境的麻煩。

那現在遇到新的問題了，如果我同時有多個專案要執行，每個專案需要的環境也不同，那我光是啟動容器的前置作業就得花很多時間。倒不如還一開始痛苦一點將所有環境建置完成。
要解決這個問題，就該 docker-compose 上場了。

### docker-compose 是何方神聖，要怎麼使用？
docker-compose是一套工具，可以讓我們用一個簡單的配置文件來定義和管理多個容器。想像它是一套寫好的使用說明書，docker會按照說明書的內容啟動所有需要的容器，而這一切只需要一行指令就可以完成：
```
docker-compose up
```

## 那我們開始吧！
我們一樣透過專案來實作。在上一篇文章中，我們已經學會使用 Dockerfile 來建置屬於自己的鏡像，並且在該鏡像的基礎上啟動容器。我們的最終目標是能夠透過一行指令，就將專案中的前端畫面與後端伺服器同時啟動，並且會隨著我的專案內容調整而即時更新內容。
我們先將想要見到的成果描述一次。

>「我希望可以啟動兩個容器，一個叫做 backend_dev，一個叫做 frontend_dev。這兩個容器分別是夠過我的 backend 以及 frontend 資料夾下的 Dockerfile-env 建置的鏡像啟動的。由於我想要夠執行開發，因此他需要掛載各自資料夾底下的所有檔案。在容器啟動後，我希望他自動執行專案的啟動指令，並且分別將我電腦上的port號 3001 以及 3002 對應到他們開放的 3000 端口上，好讓我可以透過網路與他們互動。喔對了，幫我將 backend_dev 設定一個環境變數 RAILS_ENV 為 development。」

上面描述資訊量有點多的內容，就是我們要寫給 docker 的說明書，也就是專案底下的 docker-compose.yml 檔案。
```yaml
version: '3.8'
services:
  backend:
    build: 
      context: ./backend
      dockerfile: Dockerfile-env
    container_name: backend_dev
    volumes:
      - ./backend:/backend
    ports:
      - "3001:3000"
    environment:
      - RAILS_ENV=development
    command: >
      bash -c "bundle check || bundle install && 
              rails server -b '0.0.0.0'"
  frontend:
    build: 
      context: ./frontend
      dockerfile: Dockerfile-env
    container_name: frontend_dev
    volumes:
      - ./frontend:/frontend
    ports:
      - "3002:3000"
    command: >
      bash -c "npm install &&
               npm start"  
```
我們一行一行來看裡面的內容，看他們如何分別與上面的指令對應，以及實際使用的方法。
首先要注意的是，docker-compose 是透過縮排來定義階層的，因此如果調整到縮排會讓腳本無法確定你想表達的內容。
- version: '3.8'：指定docker-compose的版本，現階段可先不用調整它。
- services:：定義服務，即我們要啟動的容器有哪些，我們這裡定義的是下面提到的 backend 和 frontend。
- backend 和 frontend:：這是我們定義的兩個服務，每個服務都有自己的一組配置。
- build:：指定鏡像的建置方式，包括context和dockerfile。
- context: ./backend：設置鏡像建置的上下文路徑。
- dockerfile: 指定用於建置鏡像的Dockerfile，這裡我們不使用上一篇文章使用的 Dockerfile，而是新的，被我們命名為 Dockerfile-env 的檔案。
- container_name:：可以指定容器啟動後的名稱。
- volumes:：定義掛載的資料夾，這裡將本地的backend和frontend資料夾掛載到容器中。
- ports:：將主機的端口映射到容器的端口，這樣我們可以在主機上訪問容器內的服務，在 backend 中，我們主機如果呼叫3001 port號就會被轉到容器 backend 的 3000。
- environment:：用來設置環境變數，這裡我們為backend容器設置了RAILS_ENV=development，假設 frontend 有設定一些環境變數的話，也可以設定在這裡，在專案中執行 process.env 就會看到我們設定的變數。
- command:：指定容器啟動後要執行的命令，這樣啟動後就會自動啟動我們的專案。 

在理解之後，我們只要實際上在終端機中在 docker-compose.yml 所在的路徑打下：
```bash
docker-compose up -d
```
其中`-d`跟我們上一篇提到的一樣，是代表後台運行的意思，可以不用加。執行完後，就可以在 docker desktop 看到啟動後的容器。
![](/images/docker-compose-result.png '啟動後的多個容器')
為了體會他實際在執行中，我們可以在本地瀏覽器輸入`localhost:3002`，會看到前端的畫面。
![](/images/frontend-page.png '啟動後的前端畫面')
他實際上呼叫了後端一支寫好的 api，只要在輸入框中輸入任意文字。就可以看到後端回傳的哈囉訊息。
![](/images/frontend-result.png '呼叫後端後的前端畫面')

如果不相信，還可以自己在後端專案下
`backend/app/controllers/hello_controller.rb`中，修改回傳的訊息，再次按下 submit 按鈕就會即時更新囉。
這樣，docker-compose會根據配置文件啟動並管理我們的兩個服務，節省了很多手動操作的時間和精力。

## 好耶，我會了，然後呢？
到這邊，我們只是很粗淺的學習 docker 在真正實務上的用法，沒有深挖底層的原理，但我們已經可以根據自己需求的環境建置客製化的鏡像。也可以透過 docker-compose 一次啟動多個容器。
希望可以用這些最核心的知識，減少大家在開發過程中環境建置的困擾。如果真的對容器很感興趣的話，可以在自己研究容器的內容，我後續也會再慢慢補上相關的筆記。

透過Docker將環境建置時間縮短100倍

如何使用容器來協助進行開發(下)


## 問題情境
去年加入了新的後端團隊中，實際在工作上最常接觸到的專案中，最主要在維運的專案使用的環境是2019年發佈的版本。雖說要跟一些上古專案比，版本不算太舊，但在相對迭代領域較快的軟體領域中，也已經是頗為陳舊的存在。且加上過去設計的架構比較複雜，疊床架屋的情形相對嚴重。雖然團隊持續的在解構，將一些不同的功能單獨拆出來運行，但在此之前，他就是一個很重要所以不太能做太大改動的專案。因此造成幾個問題。

1. 新人上手時間很長：每個人剛入職時，在拿到電腦後首先要面對的就是啟動上面提到的主專案。而這一切要參照前人陸陸續續整理下來的環境建置文件一步一步地進行，雖然沒有實際測試過，但整份文件應該有十張A4只那麼多，再加上不同系統（尤其是m系列的mac）所產生的不同問題，**快則三天，慢的話需要一個星期才能將專案成功啟動**。

2. 工程師不敢更新：由於曾發生電腦開啟自動更新，更新之後專案就跑不動的狀態，造成大家PTSD發作，變得不敢輕易更新自己的電腦，整台電腦的環境為了一個專案被迫停留在過去。

3. 墊高跨專案的開發成本：上面提到的問題其實不只在一個專案上發生，同時期開發的專案或多或少都有類似的問題。造成工程師們在開發時，跨專案開發或支援的時間成本會被墊高。

要解決這些問題，我想到了在轉職後的第一份工作上，遇到過一位堅決不讓任何環境污染自己電腦的OP同事，拜他所賜，我那時也初窺容器的門道。

**現在的新人只需要半天就可以開始進行開發囉！**

容器的使用是一條很深的學問，但在這裡會紀錄的，不是多深的學問，而是如果想要建置一套屬於某個專案的特定環境時，需要的知識以及步驟。指令的操作也基本聚焦在最必要的幾個，能夠使用GUI的盡量使用GUI，避免太多新指令模糊了學習的焦點。

### 那我們開始吧
要開始使用Docker，首先當然是要在自己的電腦上安裝Docker，這件事很簡單，滑鼠點一點就完成了。去Docker desktop[官網](https://www.docker.com/products/docker-desktop/)。根據自己的系統下載相對應的檔案來安裝。

接下來的步驟很簡單
> 搭建特定的環境（鏡像） > 將要執行的檔案放進去（容器） > 開始使用。

#### 搭建特定的環境：幫我燒一片光碟
或許有點透露年紀，但我喜歡將容器的使用比喻成光碟的概念，小時候在玩單機遊戲時，一定都需要插入光碟片，才有辦法將遊戲在電腦中運行。而無論你在遊戲進行什麼樣的操作，存了多少檔案，都不會對那片光碟造成任何改動。因此同樣的光碟片拿去借給朋友的時候，他也可以在他的電腦中，從頭開始體會其中的美好。

而容器當中一個重要的概念 - 鏡像，就是這樣的存在。我現在說的「構建環境」對應的就是 「build一個鏡像」，而用前面的例子來說就是「燒一片光碟」的概念。
而鏡像的構建並不是透過燒錄機，而是透過一條指令
```bash
docker build
```
這條指令下去之後會做的事情，是去找到相對應的**Dockerfile**，按照裡面的步驟去做一條一條執行。Dockerfile中的步驟常見的有幾個：
**FROM / WORKDIR / COPY / RUN / EXPOSE / CMD**

由於主要是為了用於自己的本地開發，一些底層邏輯、權限、安全相關的設定我們就先不考慮。以達成本地順利啟動為目標。
同樣以燒光碟為例子，我現在要將自己電腦中的遊戲燒到光碟中，我需要
> 拿一片新的光碟片(FROM)  
> 將電腦裡的馬力歐資料夾複製(COPY)到光碟片中的指定資料夾(WORKDIR)  
> 複製進去之後，我要在裡面新增一個文件，紀錄這片光碟的序號(RUN)  
> 接著我指定一個啟動指令(CMD)，讓之後拿到光碟的人一放進電腦中就會自動打開遊戲。  

這就是一般build鏡像實在做的事情。
這裡準備了一個簡單的[專案](https://github.com/YINWEIHSU/docker-exercise.git)，可以透過它來練習（也可以不用），所以先透過以下指令將專案複製下來。
```bash
git clone https://github.com/YINWEIHSU/docker-exercise.git
```
現在以實際的案例來說，我現在要將電腦中的一個ruby專案放到鏡像中，需要ruby3.2.2版本的環境，我想要讓其他沒有安裝ruby的人也可以使用這個專案。我需要
> 下載ruby3.2.2的鏡像作為基礎鏡像(FROM)  
> 將電腦裡的專案資料夾複製(COPY)到鏡像中的指定資料夾(WORKDIR)  
> 複製進去之後，我要他安裝各種需要的套件(RUN)   
> 接著我指定一個啟動指令(CMD)，讓之後執行鏡像的人可以直接運行專案。  

實際來看，就是backend資料夾下的Dockerfile（檔案名稱就叫做Dockerfile，沒有任何副檔名）在做的事，裡面的內容長這樣。
```dockerfile
FROM ruby:3.2.2
WORKDIR /src
COPY . .
RUN bundle install
EXPOSE 3000
CMD ["rails", "server", "-b", "0.0.0.0"]
```
每一步實際執行的內容如下。
1. FROM ruby:3.2.2  
從 Docker Hub 下載 Ruby 3.2.2 官方鏡像作為基礎鏡像。用作構建自定義鏡像的起點。等於是拿一片已經安裝好特定版本的Ruby的光碟。
2. WORKDIR /src  
設定容器內的工作目錄為 /src。如果該目錄不存在，Docker 會自動創建它。接下來的指令（如 COPY 和 RUN）都會在這個目錄下執行。
3. COPY . .  
將 Dockerfile 所在目錄的所有文件和子目錄複製到容器內的當前工作目錄（即 /src）。
4. RUN bundle install  
運行 bundle install 命令安裝所有專案中需要的套件。
5. EXPOSE 3000  
告訴 Docker 在運行時打開容器的 3000 端口。這行其實不寫也沒關係，他算是一個提醒的功能讓其他人知道。
6. CMD ["rails", "server", "-b", "0.0.0.0"]  
定義容器啟動時執行的命令。這裡啟動了一個 Rails 服務器，並綁定到所有網絡接口上，使得容器可以接受來自 Docker 主機的任何 IP 地址的請求。

<Note type='memo'>由於容器本身是個隔離的環境，可以將它想像是一台獨立的主機，所以如果沒有寫 0.0.0.0，則容器只會限定接收容器內部發起的請求。</Note>

創建完這個Dockerfile之後，在專案底下執行這行指令。
```bash
docker build -t project:1.0.0 .
```
他會在專案路徑底下(最後的點.)尋找Dockerfile檔案，並且執行裡面的步驟，建立一個名叫project，標籤為1.0.0的鏡像。  
如果有不同的Dockerfile存在，可以透過-f來指定執行的檔案。例如，如果我不想要執行Dockerfile檔案，而是想要執行Dockerfile.dev這個檔案，我可以這樣寫。（目前的專案底下沒有這個檔案，所以執行會出現錯誤）
```bash
docker build -f Dockerfile.dev -t project:1.0.0 .
```
我們執行docker build可以看到build的進程。
![](/images/docker-build.png 'Build過程')
執行完後，打開Docker desktop可以看到一個名為project的鏡像已經被成功創建。
![](/images/image.png 'Build出來的鏡像')

由於在Dockerfile已經設定了CMD，因此容器啟動時就會自動執行這行指令，所以我們來將容器啟動。
```bash
docker run -p 3001:3000 project:1.0.0
```
![](/images/docker-run.png '容器執行')
接著在自己的瀏覽器輸入 `localhost:3001` 就可以看到rails 的啟動畫面。
![](/images/rails-running.png '啟動畫面')

這裡解釋一下這行指令代表的意思：
我要從`project:1.0.0`啟動（`docker run`）一個執行的容器，對外開啟的PORT（`-p`）號為3001，對應到我在容器內的PORT為3000。

<Note type='info'>當然可以寫3000:3000去映射同樣的PORT，但這裡為了方便理解兩者的關聯，所以寫不同的PORT</Note>

到此為止可以成功的透過容器建置環境並運行專案，但如果我是開發需要使用的。我不可能專案啟動了之後就放著不管。

### 同步開發我的專案

接著需要解決的問題就是，如何讓我的程式碼更新也可以即時反映在容器中。在我們上面執行的鏡像構建時，已經將現有程式碼作為固定的部分放入，所以即使我現在做了任何更改，都不會反映到我在執行的容器中。

為了解決這個問題，我們可以使用 Docker 的一個功能 —— Volume。Volume允許我們將本地目錄或檔案掛載到容器中，這樣容器內的應用就可以直接讀取或寫入到本地檔案系統中，從而實現資料的即時同步。不用想得太複雜，就當他是一個設定容器內容跟電腦資料夾的連結功能。

在我們的 backend 路徑下，有一個 Dockerfile-env 檔案
```dockerfile
FROM ruby:3.2.2
WORKDIR /backend
COPY Gemfile Gemfile.lock ./
RUN bundle install
EXPOSE 3000
```
會發現他跟上面的Dockerfile有些不同，我複製的東西不同了，原本是整個專案資料夾複製進去，現在只複製了紀錄套件的檔案。
我們一樣執行 docker build，這次我們透過`-f`指定要使用的Dockerfile。
```bash
docker build -f Dockerfile-env -t project-dev:1.0.0 .
```
執行完後會在 Docker Desktop 中看到 build 完成後的鏡像 project-dev。如果我們用他執行上面的 docker run 指令時，由於我們僅僅複製了套件設定（COPY Gemfile Gemfile.lock ./），他其實是沒有任何可執行的程式碼的，創建的只有一個可執行該程式碼的環境（安裝好套件的 ruby 環境）。因此我們在執行 docker run 時要加上一個 -v 設定。告訴 docker 要將哪個資料夾透過 Volume 掛載進去容器中的環境。
<Note type='info'>
下面的 route-to-project 記得改為自己專案的絕對路徑，由於無法使用相對路徑，所以不確定的話可以透過在專案終端機打上`pwd`來確認專案的絕對路徑。
</Note>

```bash
docker run -it -d -v /${route-to-project}/docker-exercise/backend:/backend -p 3001:3000 project-dev:1.0.0 bash
```
<Note type='memo'>
有沒有發現不只多了 -v，還有很多地方做了調整。在實際執行時都可以試試看如果沒有加上這些指令會發生什麼事。
1. `-it`：只是容器在啟動後為我啟動一個可以用來交互的終端機。如果沒有加上這個指令，容器會在啟動後直接停止，因為我們並沒有給容器一個持續運行的 process 或交互式的接口，Docker 認為容器已經完成了其任務並退出。
2. `-d`：這一個可以不加，用來指示將容器設置為後台運行（detached mode），讓它在背景中運行，不會阻塞當前終端機的操作，這在需要長期運行的服務或應用中很有用。，讓他不會佔用一個終端機頁面。
3. `.`換成`bash`：改變容器的預設啟動 process。將 `.` 替換為 `bash` 允許在容器啟動後立即進入一個交互式的 bash shell，讓我們可以在裡面像在外面終端機一樣執行各種命令和操作。
</Note>

先看結果，在Docker Desktop 中的 container 頁籤，會看到新增了一個容器。是透過我們剛剛build出來的 project-dev 鏡像來創建的。
![](/images/container.png '新容器')

只是如果我們按照之前的步驟，在瀏覽器輸入`localhost:3001`，卻會發現網頁不會正常顯示。因此我們在 Docker Desktop 中選取剛剛間裡起來正在執行中的容器，並且選擇 CLI。會看到一個很熟悉的終端機畫面。在裡面輸入
```bash
rails s -b '0.0.0.0'
```
之後，就會看到rails專案啟動的內容。
![](/images/in-container.png '容器中')
此時再重新到瀏覽器輸入`localhost:3001`就會看到熟悉的畫面。

<Note type='memo'>
如果剛剛沒有使用 `-d` 的話，就不用再特別進去 Docker Desktop 中執行 CLI，因為容器會在前台運行（也就是會直接在你下 docker run 指令的終端），並且佔用 CLI 的輸出，只有當容器停止運行時，CLI 才會恢復正常操作。
</Note>

**為什麼這次需要我自己手動進去啟動應用程式呢？**

主要差別在於兩者的 Dockerfile 設定的不同，在第一個 Dockerfile 中，我們設定了
```bash
CMD ["rails", "server", "-b", "0.0.0.0"]
```
他等於指定了 docker run 之後要執行的指令，因此不用再自己手動啟動伺服器。
這次特別也以兩者的不同來展現 CMD 的作用。

到現在，應該已經可以使用容器來啟動任何專案需要的環境，與本機的環境完全隔離開來。並且還可以透過掛載進行同步的開發作業。但如果我現在有複數的專案要進行開發，同樣的步驟要做很多遍也是非常麻煩。因此在下一篇文章中，會再持續朝這個痛點邁進，透過 docker-compose，讓我們實現一件啟動多個專案的目標。


如何使用容器來協助進行開發(上)


換工作開始接觸到 Ruby 後，深深感受到他「對開發者友善」的一面，在工作中，`transform_values`這個方法是幾個最常使用到也很愛用的方法之一。具體用法就如同字面上所述，是用來更改 Hash（類似 JS 的物件）中的值並返回一個新 Hash，因此他是 Hash 上的方法，且不會影響原本的資料。

```ruby
h = { a: 1, b: 2, c: 3 }
h.transform_values {|v| v * 2 }  #=> { a: 2, b: 4, c: 6 }
h.transform_values(&:to_s)       #=> { a: "1", b: "2", c: "3" }
```
同樣的效果在原生 JS 中，即使是最簡潔的做法都看起來有點囉唆且沒有那麼易懂，寫習慣後有時候切換回 JS 都會有點當機。
```javascript
const h = { a: 1, b: 2, c: 3 }

const result1 = Object.fromEntries(
  Object.entries(h).map(([key, value]) => [key, value * 2])
) // { a: 2, b: 4, c: 6 }

const result2 = Object.fromEntries(
  Object.entries(h).map(([key, value]) => [key, value.toString()])
) // { a: "1", b: "2", c: "3" }
```

目前最常使用的情況有幾種
1. 是在將資料從資料庫取出後，進行處理的過程。
2. 串接外部 api 後的資料整理。

但不限於此，只要需要單獨針對值進行調整的情境都可以使用它，非常的實用。

### 參考資料
- [MDN web docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries)
- [Ruby doc](https://ruby-doc.org/core-2.4.6/Hash.html)

[Ruby] 輕鬆處理 hash 中的值：transform_values 的使用

本系列文章是以 [Blockchain with Hyperledger Fabric, Second Edition](https://www.amazon.com/Blockchain-Hyperledger-Fabric-decentralized-applications/dp/1839218754) 書中的內容為基礎，配合一些實務上遇到的問題所做的筆記。

## 網路運作與分散式應用程式建置（Network Operation and Distributed Application Building
根據先前的基礎知識，我們終於來到了實際的建置階段。對於一個區塊鏈網路來說，可能會涉及多個不同的組織或個人，每個組織或個人可能有著不同的業務邏輯需求。因此，為了滿足這些需求，開發人員需要為每個組織或個人開發不同的應用程式。這導致了單一區塊鏈網路能夠向不同的利益相關者提供不同的賬本視圖和合約功能。此外，這些應用程式可能運行在由不同組織獨立維護的企業安全域中。儘管如此，整個智能合約和更高層次的應用程式集合依然可以被視為在一個共同資料存儲層上操作的分散式應用程式。

### 應用程式模型與架構（Fabric application model and architecture）
在 Hyperledger Fabric 的架構中，我們可以將應用程式開發分為三層結構：
1. 底層網路層（Network Layer）：由節點、排序節點和證書授權中心（CA）組成，是應用程式的基礎設施。
2. 服務層（Service Layer）：中間層由一組服務組成，通常構建為提供 REST API 的 Web 服務器。每個服務都管理 Fabric 網絡的身份並使用 Fabric SDK 觸發智能合約上的交易和查詢。
3. 表現層（Presentation Layer）：通過終端機或瀏覽器作為用戶的接口，來調用中間層的 API 。

![Fabric application model and architecture](/images/fabric-application-model-and-architecture.png)
如上圖，可以看到最底層是合約，中間層由一組服務組成，通常構建為可提供 REST API 的 Web 服務器，每個服務都管理 Fabric 網絡的身份並使用 Fabric SDK 觸發智能合約上的交易和查詢。最上層是表現層，透過終端機或瀏覽器作為用戶的接口，以調用中間層的 API 。

### 應用程式開發概覽
與傳統應用程式不同，每筆交易都是非同步的。交易結果不會在同一個溝通階段中回傳。根據前面的討論，可以知道他會經過三個不同的獨立階段。
1. 用戶提交交易提案給節點背書
2. 已經過背書的交易提案會提交給背書節點。並由背書節點分裝在區塊中。
3. 網路中的節點驗證交易的有效性後將交易存入帳本資料庫中。

簡單來說，這是一種共識協議，網絡節點通過該協議共同批准一項交易，並且每個實例都可能花費無限的時間。因此，提交交易請求到智能合約就像提交工作請求，並且請求者會透過發布-訂閱機制使用事件獲得回應。
但上面的步驟可以隱藏（包裝）在 Fabric 提供的 SDK 中，分別有 Node.js、Java以及Go。
SDK 讓應用程式可以透過 gateway 以及 connection profile 提交交易並透過 gateway API 同步取得結果。SDK 也可以提供身份管理和在錢包中存儲憑據的功能，並且提供 API 功能來動態註冊具有所需角色和屬性的客戶端（通過連接到會員服務提供商 (MSP) 並自動將憑證存儲到錢包中）。Gateway的運作需要讀取錢包中的有效憑證。

### 網路設置
![network setup and bootstrap](/images/network-setup-and-bootstrap.png)
在啟動完節點之後，接下來要設定通道以及合約。

**通道**

一旦確定好通道的數量，並且為每一條通道設定了一個不重複的名稱後，就可以向排序服務提交創建通道的請求。此創建請求會被打包為塊放進由排序節點維護的系統通道中。

當通道成功創建後，每個該通道包含的組織的節點便可加入該通道，且這個過程會初始化該節點上屬於此通道的帳本（區塊鏈以及世界狀態）。在此階段，印為尚未安裝合約。每個加入通道的節點都只是提交節點。節點加入的行為是一個向排序節點提交的請求，並且會在通道帳本上生成一個新的區塊。

**合約**

接著會將合約安裝到通道中。首先，合約程式碼會被以一定的格式打包。一部分通道中的節點會被指定為具有合約背書資格的節點，且打包後的合約會安裝在這些背書節點上。接著，每個組織中負責維護通道的管理員必須各自允許（approve）該合約的定義，這個允許的行為也是向排序節點提交請求，並且會在通道帳本上生成區塊。最後，任何來自通道組織的管理員必須提交（commit）合約的定義到通道中，同樣的，這個動作也是提交至排序節點並生成通道中的區塊。
最後，每個合約都可以透過提交設置合約狀態的交易來完成初始化，這個步驟並非必須的。（在 Fabric 中是必須的）

### 指令順序
因為 Hyperledger Fabric 2中移除了透過 SDK 操作網路建置的方式，僅保留使用CLI，這裡就單純紀錄一下所需步驟。
註：現在依然可以使用 fabric-client 來操作這些功能，但比較複雜且該插件已棄用。

1. 創建通道（Creating channels）:創建通道並產生初始塊。
2. 將節點加到通道中（Joining organization peers to channels）：
3. 在通道上設定組織的錨節點（Setting organization anchor peers on channels）：錨節點是組織中負責與其他組織節點溝通的節點。
4. 打包合約（Packaging a contract）
5. 在節點上安裝合約（Installing a contract on peers）
6. 允許通道上的合約定義（Approving a chaincode definition on the channel）：合約定義包含一些屬性如下
* Name：必須為通道中唯一的名字
* Version：新版本，必須為對於該合約不重複的值
* Sequence：紀錄合約被定義的次數
* Endorsement policy：設定該合約上的交易必須經由哪個組織的簽章，透過AND以及OR。例如：AND('ExporterOrgMSP.member', 'ImporterOrgMSP.member', 'RegulatorOrgMSP.member').
* Initialization：此為非必要選項，設定是否需要執行初始函式，在初始函式執行前，其他函式都無法被調用。嚴格來說，如果是使用 Fabric contract API 開發的合約是非必需的。（如果使用Fabric chaincode shim API 開發的則為必要）
7. 提交合約定義到通道中（Committing a chaincode definition to the channel）
8. 初始化合約（Initializing the contracts）

### 應用程式執行生命週期（Application runtime life cycle）
![Application runtime life cycle](/images/runtime-life-cycle.png)

Hyperledger Fabric 筆記（七）

本系列文章是以 [Blockchain with Hyperledger Fabric, Second Edition](https://www.amazon.com/Blockchain-Hyperledger-Fabric-decentralized-applications/dp/1839218754) 書中的內容為基礎，配合一些實務上遇到的問題所做的筆記。

## 智能合約打包（Smart contract packaging）
我們現在知道如何使用私有數據，驗證型交易，插入型交易，或是傳輸型交易等。但還有一些需要注意的陷阱。
總結來說，智能合約打包的目標在於達成以下效果：
* 使用不同的背書政策對應同一份合約。
* 確保組織只能見到他該看到的合約內容。
* 將不必要的程式碼最小化。

在 Hyperledger Fabric 2 中，智能合約與背書政策通常為一對一關係，但通過合約定義（definition），我們可以實現更多元的包裝方式。以下將介紹兩種主要的包裝策略：多重定義包裝和功能型包裝。

### 多重定義包裝（Multi-definition packages）
![Multi-definition packages](/images/multi-definition-packages.png)
在上表中，可以看到合約被兩個不同的定義（vehicleContracts1 與 vehicleContracts2）指向。即使兩個定義使用相同的合約，但產生的交易是完全不同的。即使交易內容以及使用的合約都相同，他們也會存在不同的命名空間，且擁有不同的背書政策。多重定義包裝可以允許我們使用同一份合約但不用重新命名。

### 功能型包裝（Functional packaging）
同樣的，不同的合約包裝也可以使用同一份定義。如下圖。
![Functional packaging](/images/functional-packaging-1.png)
我們可以看到 package1 擁有一個在 car 合約、boat 合約以及 truck 合約的特定的交易集合 subsetA。package2也有一個 subsetB。我們稱此為功能型包裝，因為不同的package可以從交易池中選擇並生成完全不同的交易。讓package 包含完全不同的業務函式。
![Functional packaging](/images/functional-packaging-2.png)
上圖是之前出現過的銀行內部安全網路架構合約範例。我們可以看到合約不是一個單純的class，而是有層級關係。
![Functional packaging](/images/verify-style-transaction.png)
我們將 verifyTrade 以及 insertTrade 放進 TradeConsumer 這個 Fabric 提供的 Contract Class 的 subClass 中，而將其他的交易createTrade 以及 readTrade 放進其衍生的 TradeProvider class中。

網路中的參與者彼此之間的關係被反映在這樣的層次結構中，TradeProviders 可以執行 TradeConsumers 可以執行的所有功能，然後將不同的交易分別放入TradeConsumer 和 TradeProvider 包中進行分發。
我們也可以使用不同的方式去規劃。
![Functional packaging](/images/functional-packaging-3.png)
在上圖中，左邊是有層級關係的合約包結構，右邊的TradeProvider 以及 TradeConsumer 則沒有任何重疊。一切都可以根據組織彼此之間的關係去配合。

但在我們目前的銀行網路中，這樣的包裝形式並不是很理想：
* 合約可能包含商業機密信息。例如，當insertTrade僅僅是請求進行交易時，createTrade將有權訪問是否進行交易的規則。我們可能希望限制後者交易邏輯的分發。
* 如果我們將智能合約邏輯分發給許多不同的參與者，則我們就會給他們訪問可能被惡意利用的代碼的機會。當然，即使在不法份子可以訪問代碼的情況下我們的系統也應該是安全的，但是從一開始就限制其分發可以減少攻擊面。
* 在設計智能合約時，可以將不同的角色分配到不同的智能合約中，這樣會讓整個系統更容易理解和診斷，因為可以將不同角色的責任區分開來。這也有助於減少攻擊面。

圖7-3中的繼承和包裝設計是用來將功能鎖定到某些類型的參與者，根據他們的關係。比如說，TradeConsumer 的交易更一般且權限較少，而 TradeProvider 的交易更具體且權限較多。這樣的設計意圖是讓 TradeConsumer 的交易能夠廣泛地使用在網絡中，同時將 TradeProvider 的交易保留給提供服務的組織使用。

最終，使用 TradeConsumer 的組織應用程式必須要能夠與另一個使用 TradeProvider 的組織起作用。我們不能在沒有考慮使用情境的情況下任意將功能放入package中。

接下來，我們將所有的東西一起結合在車輛網路中。
![Functional packaging](/images/functional-packaging-4.png)
在上圖中，我們可以看到不同的組織如何根據他們可用的智能合約提供和使用不同的服務。例如，只有警察可以生成警察信息交易或車輛登記可以生成車主交易。這五個組織中的每一個都是交易信息的服務提供商，他們對這些信息擁有主權。

相反的，需注意誰能消費交易信息。在我們的網路中，警察和保險公司都能驗證車輛信息、警察信息和製造信息。但製造商沒有這些交易的訪問權。他們沒有形成哈希或其他交易的智能合約交易，因此無法與這些組織進行交易。

我們可以看到謹慎的智能合約封裝如何使車輛網絡更加智能、私密和安全。我們還看到了智能合約包（鏈碼）及其定義如何允許網絡就生成哪些交易及其各自的背書政策達成一致。智能合約繼承的精心設計允許組織網絡根據不同的網絡參與者的需要向他們提供精確的功能。

從上面的幾個例子可以明白，如果一個網路使用多重定義包裝的合約，那他就是同一份程式碼生成不同的交易，這對於程式碼的重複使用是很有幫助的。而如果使用功能型包裝的，則是同一份定義下生成不同的交易，這有助於限制不必要的和有時不需要的程式碼分發，有效地限制特定組織可以生成的交易。

Hyperledger Fabric 筆記（六）

本系列文章是以 [Blockchain with Hyperledger Fabric, Second Edition](https://www.amazon.com/Blockchain-Hyperledger-Fabric-decentralized-applications/dp/1839218754) 書中的內容為基礎，配合一些實務上遇到的問題所做的筆記。

# 集合與狀態的背書政策（Collection and state endorsements policy）

背書政策會在三個層級上進行。分別是合約層、集合層、狀態層。一筆交易會依序通過狀態層，集合層以及合約層之後才會被認定為有效。以下是每個層級背書政策的介紹及其應用：

![Collection and state endorsements policy](/images/collection-and-state-endorsements-policy.png)
在合約層，背書政策定義了智能合約的交易處理邏輯以及誰可以簽署這些交易。而在集合層，每個組織擁有的私有數據集合可能會有不同的背書政策。這代表，即使使用相同的智能合約，不同的組織可以依據自身需求客製化背書政策來確保交易的有效性。狀態層的背書政策則是基於交易中的特定狀態進行控制，並優先於集合層及合約層。

上圖範例中可以看到每個組織都有一個私有數據集合，儲存 VIN 等資訊。
* 當car101被生產出來時，因為集合層的背書政策優先於合約層，因此由 policy T 指示必須簽署的組織，而不是 policy I 。
* 每個組織的集合有自己的背書策略，這意味著可以在使用同一個合約的同時，但可以客製背書政策來定義必須如何簽署有效交易。

再來我們看 car102，他被交給經銷商 Tesla Dealer 1(TD1)，任何針對該車輛的變更交易都需要 TD1 的簽章。這裡我們可以得知
* 基於狀態的背書政策在當車子移轉制經銷商時被添加，該交易變更由Info合約建立並根據集合層的背書政策 T 經由 Tesla 簽署。當此交易完成後，car201 將會包含狀態層的背書政策。
* 由於狀態層的優先層級高於集合層。以 car201 為例，政策 AND(TD1) 現在新增了交易需要 TD1 簽章的規定。
* 即使在同一集合，不同車子也可以有不同的背書政策。舉例來說，car201 的擁有者為 TD1，而 car204 則為 HD4。

INFO的狀態是由info合約控制，但決定由誰簽署變更交易是由狀態層來控制，並不是合約層或集合層的背書政策。這樣的設計允許我們變更供應鏈中特定資產的所有權。透過適當的背書政策，我們也能實現多方組織同時擁有資產的情況。

## 集合政策（Collection Policy）
除了用於驗證交易的背書，集合政策還包含了一些其他內容，它們控制在返回智能合約的應用程式前必須有多少節點收到私有狀態更新。雖然這些設定主要是管理員的工作（與程式設計師無關），但它們可能會影響系統性能。

例如，集合政策定義了 maxPeerCount 和 requiredPeerCount，它們控制在返回給呼叫智能合約的應用程式前，必須有多少節點收到私有狀態更新。但這是管理員配置的，並且與應用程式如何工作無關。它可能會影響性能，但這不是應用程式或智能合約開發人員應該關心的單獨問題。

## 轉移式交易（The transfer-style transaction）
在設計合約處理私有數據集合時，可以透過「驗證式」(verify-style) 和「插入式」(insert-style) 設計模式，來設計基於狀態以及集合背書政策的轉移式交易。以下是三種轉移式交易的詳細說明：
![The transfer-style transaction](/images/the-transfer-style-transaction.png)
上圖可以看到轉移式交易中最主要的交易（簡化）。下面根據函式分別說明。
### CreateInfo
* createInfo 開啟了 info 的生命週期。負責創建VIN資訊。
* createInfo 可以在每個組織的 Info 集合確認要建立的資產是否已經存在。與插入型交易的最大差別在於，插入型交易無法讀取私有數據庫因此在創建資產前不會確認是否已存在。
* putPrivateData 將新的物件寫入帳本，但同樣的，在達成共識前，不會真的被寫進帳本。
* 由 createInfo 創建的交易需要根據集合層背書政策進行簽署。例如，一台新的 Tesla 寫進去之前，要根據政策 T 進行簽署。由於新物件是要加進集合中，因此在合約層的背書政策 I 並沒有參與其中。
在設計智能合約時，必須考慮背書政策的要求，同時仍然具有彈性，以滿足每個組織的要求。具體來說，Tesla、Honda、Peugeot 和 Ford 都有相同的智能合約，確保它們的每個「INFO」集合的行為方式相同。但是，它們每個都有不同的背書政策，以便為每個組織的交易驗證提供定制功能。
* 我們無法通過檢查 createInfo 的內容來確定對於給定的對象適用的具體背書政策。因此，必須了解智能合約及其背書政策定義的完整交易生命周期，以及相關集合及其背書政策，才能確定哪個背書政策適用。這不是理想的做法，因為如果智能合約有某種元數據，可以用於幫助解決這個問題，那就會更好。正如我們稍後將看到的，這確實會對應用程式產生影響。
 
 ### TransferInfo
 * 此交易用來轉移 carInfo 中的物件的所有權。此方法用於簽署要轉移的汽車，原使用者和新使用者。從背書的角度來看，原使用者的簽名並非必要，但是智能合約通常封裝了管理商業對象轉移的業務規則。例如，將 car201 從 Tesla 轉移到 TD1 時，將檢查該汽車當前是否由 Tesla 擁有。
 * 我們經過集合層的背書政策創造了資產，而 transferInfo 可以透過 setPrivateDataValidationParameter() API 設定物件狀態的新背書政策。在範例中，car201 會新增一個 AND(TD1) 的背書政策。
 * 儘管由 transferInfo 生成的交易將 TD1 設為擁有者，但該交易依然要滿足背書政策，經由 Tesla 的簽署過後才會滿足，這是很合理的設定。
 * 當此交易被認定為有效後，該車輛將會擁有一個狀態層的背書策略，並且在接下來的狀態更改中發揮作用。
 * 與 createInfo 不同，transferInfo 的程式碼中可以看到哪個背書政策新增至指定物件。透過 setPrivateDataValidationParameter() 可以看到狀態層的背書政策啟用，並會在接下來的交易中發生作用。

 ### updateInfo
 * updateInfo 用來修改特定汽車的詳細資訊。很間單的確認車子的存在，並且透過 get 以及 put 帳本 API 去執行。
 * 因為 transferInfo 新增了狀態層的背書政策，updateInfo 生成的交易都必須經由個別的經銷商（例如 TD1）簽署。
 * 因為擁有者並沒有改變 updateInfo 並沒有使用 setPrivateDataValidationParameters()
API 。但是，任何對該物件所做的改變都必須通過 transferInfo 時透過 setPrivateDataValidationParameters()
API 設定的背書政策。
* 與 createInfo 相同，我們無法在 updateInfo 中知道關於背書政策的設定。

## 應用程式提交轉移式交易
下面來看一段應用程式。
### createInfo
```js
const createDetails = {
 owningOrg: Buffer.from('TESLA'),
 carId: Buffer.from('Car101'),
 carVin: Buffer.from('VIN101'),
 carYear: Buffer.from('2020')
};
createInfo = await infoContract.createTransaction('createInfo');
await createInfo.setTransient(createDetails);
endorsingOrgs = ['TESLA'];
await createInfo.setEndorsingOrganizations(...endorsingOrgs);
await createInfo.submit();
```
上面的程式碼中可以看奧應用程式將細部資料放入暫時性資料中。但根據集合層的背書政策，createInfo必須由Tesla進行背書，因此透過 setEndorsingOrganizations 來標示背書組織。這個步驟是必須的，因為發現服務沒辦法幫我們完成這個步驟，要將 SDK 與 Tesla info 集合連接，必須由應用程式來實現這樣的細節。

### transferInfo
```js
const transferDetails = {
 owningOrg: Buffer.from('TESLA'),
 newOwner: Buffer.from('TD1'),
 carId: Buffer.from('Car201'),
};
transferInfo = await infoContract.createTransaction('transferInfo');
await transferInfo.setTransient(transferDetails);

endorsingOrgs = ['TESLA'];
await transferInfo.setEndorsingOrganizations(...endorsingOrgs);
await transferInfo.submit();
```
雖然 transferInfo 交易會根據 newOwner 設定新的背書政策 TD1 ，但我們依然需要 Tesla 的簽章才能成功寫進帳本，這邊一樣可以看到我們透過 setEndorsingOrganizations 來實現。

### updateInfo
```js
const updateDetails = {
 owningOrg: Buffer.from('TD1'),
 carId: Buffer.from('Car201'),
 carModification: Buffer.from('FILTER4'),
};
updateInfo = await infoContract.createTransaction('updateInfo');
await updateInfo.setTransient(updateDetails);
endorsingOrgs = ['TD1'];
await updateInfo.setEndorsingOrganizations(...endorsingOrgs);
await updateInfo.submit();
```
這裡最主要的差別是被書組織改為設定 TD1。

我們並沒有花太多時間專注在智能合約上的商業邏輯。先單純看上面三個交易。
* createInfo 可以確保 VIN 符合格式且之前尚未發布過。
* transferInfo 可以確保交易是由車子的擁有者發起，且提交者擁有該組織賦予的足夠權限。
* updateInfo 可以確保交易是由車輛的擁有者提交並且更改是有效的。

## 小結
目前為止，紀錄了 Hyperledger Fabric 中背書政策的三個層級，以及如何在設計智能合約時應用這些政策來處理私有數據集合。確保了交易的安全性和有效性，也提供了足夠的彈性來定制應用程式。

Hyperledger Fabric 筆記（五）

本系列文章是以 [Blockchain with Hyperledger Fabric, Second Edition](https://www.amazon.com/Blockchain-Hyperledger-Fabric-decentralized-applications/dp/1839218754) 書中的內容為基礎，配合一些實務上遇到的問題所做的筆記。

## 客製化SDK功能
因為關注點分離（separation of concerns）的原則，應用程式專注在業務邏輯，而與區塊鏈互動的細節都交給 SDK。但這樣非常多的邏輯都照著預設值在走，有時候不是那麼適合目前的業務。現在來看看有什麼是可以調整的。
### Connection Options
我們知道 Gateway 是連接的入口，只要透過 connectionProfile 以及 connectionOptions 即可。
現在來看看 connectionOptions 的內容，下面是範例
```js
const userName = 'pedroIdentityA@orgAexample.com';
const TlsName = 'pedroIdentityC@orgAexample.com';
const wallet = new FileSystemWallet('../identity/user/pedro/wallet');
connectionProfilePath = path.resolve(__dirname, 'registration-network.json');
connectionProfile1 = JSON.parse(fs.readFileSync(connectionProfilePath,
'utf8'));
connectionOptions1 = {
  identity: userName,
  wallet: wallet,
  clientTlsIdentity: TlsName,
  eventHandlerOptions: {
    commitTimeout: 100,
    strategy: EventStrategies.MSPID_SCOPE_ANYFORTX
  }
 };
await gateway1.connect(connectionProfile1, connectionOptions1);
regNetwork = await gateway1.getNetwork('vehicle-registration');
```
identity 以及 wallet 是兩個必要的欄位，除了他們以外，還有其他可設定的欄位。
* commitTimeout：等待每個「必要的」節點成功寫入帳本的時間，預設值為300秒，這裡設定為100秒。
* strategy設定 MSPID_SCOPE_ANYFORTX 代表任何一個組織中的節點回傳結果即完成，是很樂觀的策略。與之相反的，NETWORK_SCOPE_ALLFORTX 代表網路中的所有節點都需要回傳才會視為完成共識。
* 在一般情況下，當 Gateway 成功連上網路時，會使用 identity 去進行任何交易，但如果對等元件（例如節點）被設定為需要使用安全溝通，則可以設定 clientTlsIdentity。

### 事件處理器（Event handler function）
如果是比較大型的網路，我們或許會想要有比 MSPID_SCOPE_ANYFORTX, MSPID_SCOPE_ALLFORTX,NETYWORK_SCOPE_ANYFORTX,NETWORK_SCOPE_ALLFORTX 這四個策略更多的設置，這時候可以客製事件處理器。原則上，使用原本預設的設定即可。
```js
{
 ...
 const connectOptions: GatewayOptions = {
 transaction: {
 strategy: MyEventhandler
 }
 }
 const gateway = new Gateway();
 await gateway.connect(connectionProfile, connectOptions);
 ...
}
import { TxEventHandler } from 'fabric-network';
class MyEventHandler implements TxEventHandler {
 ...
}
```

## 暫時性資料（Transient data）
在我們呼叫智能合約的函式時，或許有些敏感數據是合約必要，但不們不想被公開在所有的區塊鏈網路上。（例如，給特定商家的折扣成數）
```js
sellTransaction = await carContract.createTransaction('sellCar');
await sellTransaction.setTransient(transientData);
await sellTransaction.submit('CAR0001', 'Bob Buyer','10000');
```
在使用setTransient時，先透過createTransaction再submit是必須的，且效率較高（與submitTransaction相比）。

## 私有數據（Private data）
看起來感覺與 Transient data 很像，但實際上 Private data 的機制完全不同。Transient data 讓交易內容再輸入時不會公開在帳本上，而 Private data 讓交易輸出不會出現在帳本上。它在私有數據集合（private data collection）中存儲，但是只有特定的組織成員（透過collection policy定義）才能訪問它。在私有數據集合中的狀態只對應於該集合，即使他與世界狀態有同樣的key值，依然是兩個不同狀態。
對於 SDK 來說，他依然只是呼叫交易，使用私有數據的是智能合約。但這樣要怎麼確保大家帳本紀錄的資料是相同的，且資料是在區塊上的。實際上，私有數據在區塊上是以 hash 值的形式存在。
下圖可以很清楚看到，當呼叫 createCarOwner 時，存在私有數據集合裡的狀態是 `car1:{REG1, VIN1, YOGENDRA}`，而存在區塊裡的是 0A01C1:04395C，分別對應 car1 以及`{REG1, VIN1, YOGENDRA}`的 hash（SHA256）值。
![private date in blockchain](/images/private-data-in-blockchain.png)
這與其他區塊鏈技術中被稱為 off-chain 的機制是很像的。

## 驗證型交易（The verify-style transaction）
可以操作私有數據集合的合約擁有與之相關的驗證型方法。
舉例來說，下面就是一段合約的程式碼就是做了 verifyCarOwner 的功能。
```ts
import { Context, Contract, Info, Returns, Transaction } from 'fabriccontract-api';
import { CarOwner } from './car-owner';
const collectionName: string = 'OwnerInfo';
@Info({title: 'CarOwner', description: 'Smart Contract for Vehicle owner data' })
export class CarOwnerContract extends Contract {
public async verifyCarOwner(ctx: Context,
 carOwnerId: string,
 verifyProperties: CarOwner):
Promise<boolean> {
 const hash: Buffer = await ctx.stub.getPrivateDataHash(collectionNa
me, carOwnerId);
 if (hash.length === 0) {
 throw new Error('No private data hash with the Key: ${carOwnerId}');
 }
 const actualHash: string = pdHashBytes.toString('hex');
 // Convert user provided object into a hash
 const propertiesHash: string = crypto.createHash('sha256')
 .update(JSON.stringify(verifyProperties))
 .digest('hex');
 // Compare the hash of object provided with the hash stored on
 // public ledger
 if (propertiesHash === actualHash) {
 return true;
 } else {
 return false;
 }
}
}
```
這讓我們可以實現下面的情境。
![verify-style transaction](/images/verify-style-transaction.png)
在上圖中，汽車註冊機構以及警察都擁有同一份智能合約。假設今天警察攔停了一輛車，雖然他沒有辦法訪問PRIVATE1的資料，但他同樣可以詢問汽車的資訊，並透過verify方法去驗證資料的正確性。

## 私有數據的共識流程（Private data consensus）
![Private data consensus](/images/private-data-consensus.png)
透過上圖的情境來了解私有數據的共識流程。
整個流程完成一件事，讓car1的所有權移轉給Rebecca。

第一步，registration 應用程式提交了 updateOwner 交易。輸入的值為將 car1 的所有權從 Yogendra 轉為 Rebecca。應用程式使用暫時性資料形式來確保輸入內容不會被寫在帳本上。

第二步，SDK根據背書政策選擇Peer1來為交易背書。Peer1 將運行 updateOwner 方法並代表車輛註冊組織簽署回應。

第三步，智能合約執行並訪問 PRIVATE1 集合以創建反映車主為 Rebecca 的狀態 ` car1: {REG1, VIN1, REBECCA}.` 智能合約透過 putPrivateData API 達成上述的行為。與世界狀態交易的情況一樣，此時 PRIVATE1 中的 car1 沒有發生變化。當提交整個事務時，對 PRIVATE1 的更新將在稍後的步驟 8a 和 8b 發生。由於交易涉及私有數據，因此有來自 Peer1 的額外通信。它將提議的 car1 狀態更新分發給 Peer2，Peer2 也持有 PRIVATE1 的副本。在我們的範例中，PRIVATE1 由車輛登記機構獨家持有，因此分配非常簡單。如果多個組織皆持有的情況，將分發給多個組織。

第四步，Peer2接到了 car1 的更新。但同樣的，在交易被commit之前， PRIVATE1不會有任何更新。到目前為止，車輛登記機構中的兩個 peer 都具有 car1 的新值，但尚未將它們放進他們的 PRIVATE1 副本。

第五步，updateOwner 合約方法已將包含私有數據哈希的交易返回給 SDK。 SDK 隨後創建交易 1234 並將其提交給排序服務。最重要的是要注意交易 1234 不包含 PRIVATE1 或新 car1 狀態的任何顯式或可計算記錄，除了哈希： 
Key 0A01C1：PRIVATE1 car1 的 SHA256 Hash
Value `355BFE： {REG1, VIN1, REBECCA}` 的 SHA256 Hash
而因為我們輸入的方式是使用暫時性資料，因此交易回傳並不會包含任何對世界狀態集合的更新。智能合約只更新私有數據集合。編寫生成包含公共世界狀態和私有數據更新的交易的智能合約是完全合理的，只是目前的範例不需要。

第六步，交易1234被排序。並和其他交易一起被包在區塊中，由排序節點發送給每個組織的節點（節點1,2,3,4）驗證。在第 7a、7b 步，車輛登記機構節點驗證交易1234。在一般交易，使用背書政策來驗證。對於私有數據，此策略可以存在於個別私有數據狀態、集合策略或智能合約定義中。在第 7c、7d 步，可以看到驗證由保險公司與警察驗證。

在第 8a、8b 步，PRIVATE1已經更新了 car1 的狀態，透過加上星號來代表。

## 插入型交易（The insert-style transaction）
智能合約還有一另外一種設計模式，插入型交易方法。這種交易風格與我們到目前為止看到的標准或創建風格的方法最相似，但仍然有很大的不同。
![The insert-style transaction](/images/the-insert-style-transaction.png)
在上圖中，可以看到 Top bank 以及 Big Bank 使用 Interbank securities network 來記錄他們與網路中銀行的股票交易紀錄。我們先將事情簡化，只看各銀行如何使用各自的私有數據集合。該集合專門用於記錄該組織與其他銀行的所有交易（證券買賣）。而集合的內容只有自己銀行的節點有權限存取，跟我們之前提到的驗證型交易一樣，如果其他銀行可以拿到交易細節，他可以用來驗證該筆交易是否存在。
如果我們反過來看 Big Bank 的交易集合，可以看到雨 Top Bank 的類似交易紀錄。同樣的，這些資料都只有他自己的節點可以存取，但他與 Top Bank 的交易集合都有一半的 Y2 交易，因此他可以透過這筆交易驗證交易是否正確的寫入對方的集合。

上圖中最重要的一筆交易是 W2 ，因為他並不是由 Top Bank 發起的交易。這與我們過往認知的交易流程都不太一樣。這筆交易是由 Big Bank 提出想要購買股票的掛單交易，而 Top Bank想要販售股票，因此 W2 交易由 Top Bank 提出販售的掛單交易。就像實際上由 Big Bank 向 Top Bank 提出「我想請你賣股票給我，細節如下，你同意嗎？」，Top Bank 會決定是否同意這筆交易，但該提案已由 Big bank 提交，並記錄在帳本中。
同樣值得注意的是，作為同一過程的一部分，Big bank 還使用 Peer9 上的交易合約的創建方法在 BIG TRADES 中創建了 W2 購買掛單。這意味著 Top bank 現在可以使用 Peer6 上的驗證方法驗證 Big bank 是否創建了交易，並可以將此作為驗證 W2 交易的一部分。
這個範例可以知道幾個重要的點：
* 此行為是由智能合約寫定，Big Bank 無法隨意寫入任何資料進入集合中。
* Big Bank **寫入**資料進入 Top Trade 集合，而不是**讀取**。對於私有數據來說，讀取是一個比較有價值的行為，因為其需要確保隱私被保障。
這是創建交易與插入交易概念上很大的分別，創建交易需要先讀取集合並確認目標物件存在，而插入交易則單純寫入交易而沒有讀取的行為。因為插入交易是在驗證階段執行的，因此可以由非擁有該私有數據集合的組織發起，但同時符合背書政策。
如果要比喻的話，可以將私有數據集合想像為信箱，其他組織可以發信（透過 putPrivateData() API）給信箱（寫入交易），但無法讀取該信箱。因此，插入型交易的生命週期是由發起掛單（Pending）交易的時候開始。也由於有背書政策，我們可以確保只要符合背書政策，不一定只能由私有數據集合的組織才能寫入資料。

接下來看一段插入型交易的智能合約：
```ts
import { Context, Contract, Info, Returns, Transaction } from 'fabriccontract-api';
import { Trade } from './trade';
@Info({title: 'Trade', description: 'Smart Contract for trades'})
export class TradeContract extends Contract {
  public async insertTrade (ctx: Context): Promise<void> {
  // Get trade details from transient data
  tradeId = transientData.get('tradeId').toString('utf8');
  buyer = transientData.get('buyerCode').toString('utf8');
  newTrade.seller = transientData.get('sellerCode').toString('utf8');
  newTrade.price = transientData.get('price').toString('utf8');
  ...
  // Check trade details
  ...
  // Insert the transaction
  const tradeBuffer = Buffer.from(newTrade);
  collectionName = newTrade.sellerCode;
  await ctx.stub.putPrivateData(collectionName, tradeId, tradeBuffer);
  }
}
```
* insertTrade()沒有包含任何輸入值，這是為了確保揭露出來的資料最小化，避免區塊鏈紀錄了任何不可洩漏的資訊。當然，我們也可以選擇包含輸入值，但要記得這些值都會被通道中的其他組織看到。
* 集合名稱是計算得出，而非寫死的。且在此方法中幾乎沒有宣告任何常量，這在真實世界的智能合約中是很典型的，因為智能合約被設計可以靈活的處理各種輸入與條件，而不是固定值。在我們的範例中，網路中的每個銀行都有一個單獨的集合，用於儲存它們與網路中其他銀行的所有交易。這意味著當一家新的銀行加入網路時，它只需要加入一個單獨的集合即可參與。只要每個集合都包含與其他銀行的所有交易，就不管是否有用於不同類型交易（如購買、銷售和待處理交易）的單獨集合都沒有關係。這種方法避免了每個對手方都有資料的情況，在這種情況下，銀行會使用不同的集合來存儲與不同對手方的交易。相反，這種方法允許每家銀行都有一個單獨的集合來存儲它們與其他銀行的所有交易，這是一種更有效且具有擴展性的模式。在網路中有幾個策略性的多邊集合是可以接受的（被多個參與者共享的集合），但是不要以系統化或有組織的方式使用這些集合。
* 智能合約中使用 putPrivateData() API 去Top Trade生成掛單交易。除非該組織有設定 memberOnlyWrite: false 不然預設是可以讓非組織成寫入。需再次重申，智能合約並沒有去讀取集合，而僅僅是寫入。

下面是應用程式呼叫，insertTrade()的範例：
```js
const tradeDetails = {
 tradeId: Buffer.from('TRADE-W2'),
 counterparty: Buffer.from('BIG'),
 units: Buffer.from('900'),
 symbol: Buffer.from('AAPL'),
 price: Buffer.from('1200')
};
insertTrade = await tradeContract.createTransaction('insertTrade');
await insertTrade.setTransient(transientData);
await insertTrade.submit();
```
在應用程式端，我們不會知道合約實際是透過插入型交易執行，應用程式單純地將交易細節放入暫時性資料中並提交至 insertTrade()。這種資料隔離方式很重要，他允許應用程式以最小的負擔參與維護訊息的安全性，所有隱私問題都由智能合約來處理。

我們可以看到插入型交易的讀取與寫入是非對稱的，透過讀取獲取資料是及時的，但寫入資料會一直到交易被commit之後才完成。因此，一般來說同常會認為智能合約無法在同一個交易中讀取自己寫入的值。因為讀取是透過底層資料庫（LevelDB、CouchDB等），而寫入須等到驗證後才被寫入。但是，Fabric可以結合資料庫中的資料結合還未被驗證的寫入值去計算新的寫入值，以此方式來實現讀取自己的寫入。

Hyperledger Fabric 應用程式的進階開發

Hyperledger Fabric 筆記（四）

本系列文章是以 [Blockchain with Hyperledger Fabric, Second Edition](https://www.amazon.com/Blockchain-Hyperledger-Fabric-decentralized-applications/dp/1839218754) 書中的內容為基礎，配合一些實務上遇到的問題所做的筆記。

Hyperledger fabric 開發的應用程式可以完成以下任務：
- 查詢帳本
- 提交新交易
- 接收帳本通知訊息

而任何交易都離不開身份驗證的機制，這裡主要著重於交易流程與身份驗證的實作。

## 應用程式開發
目前最容易的就是直接使用官方開發好的套件來開發應用程式，其中[fabric-network](https://www.npmjs.com/package/fabric-network) 這個 package 提供了許多強大的功能，相較於舊版的 [fabric-client](https://www.npmjs.com/package/fabric-client) 更加方便使用。因此，在開發應用程式時，建議選擇使用 fabric-network 套件。此外，應用程式不需要關注智能合約的背書政策，因為 SDK 的 Discovery Service 會自動處理這些事項。

這裡得說，hyperledger fabric 的官方文件並沒有寫得很清楚，在開發時很常看到一些範例其實是 fabric-client 的舊功能，如果不仔細看很容易遇到開發成品不如預期的挫折。

### 查詢帳本
由於分散式帳本的特性，應用程式可以在網路中的任何帳本上查詢相對應的結果。然而，應用程式會優先查詢自己組織節點的帳本，從而提高查詢效率。

### 提交交易
![submit transaction process](/images/submit-transaction-process.png '提交交易')
整個交易提交流程就是產生共識的過程。也可以直接將整個流程稱呼為「共識」。透過SDK可以很簡單的完成整個流程，流程可以分為三個階段：**交易簽章（Transaction Signing）、分配（Distribution）以及驗證（Validation）**。

### 交易簽章
在這個階段，應用程式會生成交易提案，並將其發送到網路中的相關節點進行簽章。Discovery服務會幫助SDK識別出合約安裝在哪些節點上，以及背書政策的內容。這使得SDK能夠自動避開未運行或錯誤的節點，並收集所有必要的簽章。

在上圖的範例中，app1想要紀錄一筆車輛銷售的交易（id:1234）。整個交易起始於包含交易定義以及簽章的交易提案。該提案會被發送到網路中，並用於構建多方交易。
SDK可以判斷合約A須符合背書政策A，因此會將交易提案發送給組織A與組織B的節點（2a, 3a），而兩個組織都安裝了合約A，因此可以產生經過簽章的交易回覆。
雖然節點4沒有安裝相對應的合約，因此無法產生交易回覆，但他知道背書政策A，因此可以驗證交易的有效性。
而在這個階段，Discovery扮演重要的角色，Discovery幫助SDK認知到合約安裝在哪些節點上，且知道背書政策A的內容。
在步驟2b，3b，SDK可以將兩個已簽章的交易回傳值打包進原本的交易提案中（帳本狀態尚未被修改）。SDK提交以及收集回傳值都是並行的，並且會自動避開未運行或錯誤的節點。

### 分配
交易完成簽章後，SDK會將其傳送給排序節點，排序節點則會將交易打包成區塊，並分發給所有節點。

延續上面的流程，接著必須要將交易發送給所有的節點，而這件事是由排序節點來處理。SDK會將已經過簽章的多方交易傳送給排序節點（5a）。在交易送到排序節點後，就是共識流程開始之時，而SDK要一直等到交易寫入帳本後才會回傳給App。排序節點會將交易打包成區塊，並發送給各個節點（6），且發送是併發的。
### 驗證
每個節點收到區塊後，會將其加到自己的區塊鏈上，並開始驗證交易的有效性。經過驗證的交易會寫入狀態資料庫，並通知相關應用程式。

在目前的範例中，交易1234必須經過兩步驟驗證，第一步需要驗證被書政策，確認交易是經過組織A與B簽章的。第二步要驗證交易的before-image與狀態資料庫的物件狀態符合，在符合的情況下，after-image的內容才會改寫狀態資料庫。

當節點完成整個上鏈的程序後，他會通知所有要求通知的應用程式。在8a中，事件通知是由peer2產生，8b是SDK收到通知。應用程式不必設定特定節點接收通知，因為SDK會預設向所有組織中的節點註冊通知。當然，通知策略也是可以客製化的。當SDK收到通知後，他會將控制權交還給應用程式，並指示交易內容是有效還是無效。

### 接收帳本通知訊息
應用程式可以隨時向節點發送通知請求，以接收區塊或事件通知。當帳本有更動時，節點會通知註冊請求的應用程式，從而確保應用程式能夠即時獲取帳本的最新狀態。
與查詢相反，帳本通知本身是個非同步的過程。通知本身是個很簡單的流程，應用程式只需向節點發送通知請求即可。當帳本有更動時，節點會通知註冊請求的應用程式。而通知有兩種形式，事件通知（event notification）以及區塊通知（block notification）。

## 錢包（Wallet）與身份（Identity）
在Hyperledger Fabric中，身份和錢包是應用程式與區塊鏈網路互動的核心。

### 使用身份
身份在區塊鏈網路中扮演著重要的角色，每個網路元件（如節點、排序節點、CA、組織）都有自己的唯一身份，這些身份通常以X509證書形式存在。理論上，其他證書類型也是可能的，但不常見。每個參與者的 X.509 證書均由其組織的證書頒發機構（CA）頒發。
所有的元件透過網路通道結合在一起，且相關資訊被配置在一組MSP定義（MSP definitions）中。該定義描述了每個組織以及其關鍵角色，可以想像為一間公司的公司登記。透過MSP，每個在通道中的人都可以很快地知道對方身份所代表的組織。

### 使用錢包
錢包用於存儲身份資訊，並通過SDK的Gateway與區塊鏈網路進行交互。錢包的存儲形式可以多種多樣，如本地儲存（當應用程式運作在網頁上時很有用）、資料庫或硬體安全模組（Hardware Security Module 簡稱 HSM）。
錢包是透過SDK提供的gateway來與通道交互。以下是一個範例
```js
const userName = 'pedroId1@orgA.example.com'
const wallet = new FileSystemWallet('../identity/user/pedro/wallet')
const connectionOptions = {
 identity: userName,
 wallet: wallet,
 eventHandlerOptions: {
 commitTimeout: 100,
 strategy: EventStrategies.MSPID_SCOPE_ANYFORTX
 }
 }
await gateway.connect(connectionProfile, connectionOptions)
```
### Gateways 與 Discovery
Gateway 將所有元件結合在一起，讓應用程式專注於主要功能（查找、提交、通知）的開發。Discovery 服務則利用 gossip 協定幫助 SDK 自動發現網路中的其他元件，簡化了網路的配置。

#### Gateways
可以將 Gateway 視為使用者與網路互動的連接點。我們只需要定義以下兩點。
1. connectionProfile：定義組織的連線資訊。
2. connectionOptions：定義應用程式與網路互動的設定，例如身份或錢包。

接著即可透過API`gateway.connect()`將所有的一切串接再一起。
下面是一個connectionProfile的範例：
```
name: vehicle-networks
version: 1.0.0
organizations:
 OrgA:
  mspid: OrgA.MSP
  peers:
   - peer1.orgA.example.com
  certificateAuthorities:
   - ca1.example.com
peers:
 peer1.orgA.example.com:
 url: grpc://peer1.orgA.example.com:7051
certificateAuthorities:
 ca1.example.com:
 url: http://ca1.example.com:7054
 caName: ca1.orgA.example.com
```
我們只需要定義簡單的資訊，當SDK連上區塊鏈網路時，discovery 會自動拓墣（topology），將剩下的資訊補足並取代原本的 connectionProfile。

#### Discovery
因為 Discovery，我們可以使用很簡單的 connectionProfile 便可以連上區塊鏈網路。順帶一提，在舊版的 fabric 中，connectionProfile 需要完整的記錄所有在通道中的組織集結點資訊，相較之下新版的連線就方便許多。
Discovery 本身是個利用 gossip 的通訊協定去搜尋其他網路元件行為的稱呼。我們只需要定義網路中的一個節點，discovery 便可以為我們拿回該節點連接的所有通道相關資訊。SDK會找到其他節點並可以知道他們是否安裝著合約，預設上，SDK會假定有安裝合約的節點為背書節點。
Discovery不僅止於節點。他也可以透過定義在通道配置中的 **錨節點（anchor peer）** 找到其他的組織。

### evaluateTransaction 與 submitTransaction 的不同
在看官方文件時，會發現這兩個方法看起來都是類似的用途，但主要的差異如下。
evaluateTransaction 用於在特定節點上查詢資料，而不會經過共識流程，也不會更改帳本內容；而submitTransaction 則會執行交易，經過共識流程並將結果寫入帳本。因此，如果單一節點被篡改時，雖然不影響整個鏈上的資料正確性，但該組織的使用者可能會查詢到被篡改的資料。

而為什麼 evaluateTransaction 不會經過共識流程，是因為每個分散式帳本的內容理論上都會是相同的，所以在特定節點的帳本查詢理論上來說就會是同樣的資料。

### 事件（Events）與通知（Notifications）
通知是補足整個交易流程的最後一塊拼圖，與查詢或提交不同，通知是一個非同步過程。應用程式可以註冊監聽特定的事件，當這些事件發生時，節點會透過SDK通知應用程式。

事件是由合約所創造，包含在 output 當中，事件本身沒有 before-image 或是 after-image，他僅僅傳達事實。
下面是一個包含事件的交易：
```
Registration updateRegistration transaction:
 identifier: 1234567890
 proposal:
  input: {CAR1, Bob, {51.06,-1.32}}
  signature: input signed by Pedro
 response:
  output:
    {CAR1.currentOwner = Sara Seller,
     CAR1.currentOwner = Bob Buyer,
    event:{"regEvent",{car: CAR1, location: 51.06,-1.32}}}
 signatures:
  output signed by Sara Seller
  output signed by Bob Buyer

```
同樣的，在合約中新增事件也是一件簡單的事。
```ts
import { Context, Contract, Info, Returns, Transaction } from 'fabriccontract-api';
import { Car } from './car';
import { Registration } from './registration';
import { Location } from './location';
@Info({title: 'RegistrationContract', description: 'The registration smart contract' })
export class RegistrationContract extends Contract {
//...
 @Transaction()
 public async updateRegistration(ctx: Context, CarId: string,
 newReg: Registration,
 coord: GpsLocation)
 : Promise<Registration> {
 const exists = await this.registrationExists(ctx, carId);
 if (!exists) {
 throw new Error(`Cannot find registration for car ${carId}.`);
 }
 const updatedReg = new Registration();
 updatedReg.value = newReg;
 const buffer = Buffer.from(JSON.stringify(updatedReg));
 await ctx.stub.putState(CarId, buffer);
 const eventPayload: Buffer = Buffer.from(
 {'CarId': CarId, 'location': coord});
 await ctx.stub.setEvent('regEvent', eventPayload);
 return updatedReg;
 }
//...
```
上面的合約在交易時會產生一個叫做 RegEvent 的事件，且事件是獨立於交易寫入的。此事件也會包含在回傳的簽章中。
再來看看應用程式如何接收到事件。
```js
const userName = 'yogendraId@orgB.example.com';
const wallet = new FileSystemWallet('../identity/user/yogendra/wallet');
connectionProfilePath = path.resolve(__dirname, 'registration-network.json');
connectionProfile = JSON.parse(fs.readFileSync(connectionProfilePath,
'utf8'));
connectionOptions = {
 identity: userName,
 wallet: wallet,
 eventHandlerOptions: {
 commitTimeout: 100,
 strategy: EventStrategies.MSPID_SCOPE_ANYFORTX
 }
 };
 await gateway.connect(connectionProfile, connectionOptions);
regNetwork = await gateway.getNetwork('vehicle-registration');
contract = await network.getContract('RegistrationPackage',
'Registration');
// Listen for regEvent notifications
console.log(`Listening for registration event.`);
const listener =
 await contract.addContractListener('reg-listener',
 'regEvent',
(error: Error, event: any) => {
 if (error) {
 console.log(`Error from event: ${error.toString()}`);
 return;
 }
 const eventString: string = 'chaincode_id: ${event.chaincode_id}',
 tx_id: ${event.tx_id}, event_name: "${event.event_name}",
 payload: `${event.payload.toString()}`;
 console.log('Event caught: ${eventString}');
});
```
上面的`addContractListener()`傳入三個參數，監聽器的名字、監聽的事件以及事件處理函式。當`addContractListener()`完成後，節點就會記得我們發出的通知要求，當有事件產生時，就會透過SDK回傳兩個參數（error, event）回來。而 event 的結構如下：
- chaincodeId 是智能合約組合的名字。事件是包含在交易中，而交易則是透過合約生成的。 
- tx_id 是交易 ID
- event_name 是產生事件的名字。
- event_payload 則是事件的內容。
當應用程式停止，監聽器會自然被移除，但事件依然會生成。兩者是解耦合的。

每個節點都可以產生事件通知，但還是可以透過設定擋設定負責產生通知的節點（event hub），他節點即使收到事件，也不會產生通知。

### 應用程式的設計策略
根據應用程式的需求，可以採用不同的設計策略：
1. 應用程式同步：應用程式等待交易成功寫入帳本後再繼續操作。
2. 應用程式非同步：應用程式不等待交易回應，並且可以執行其他不相關的交易。
3. 交易非同步：應用程式可以同時處理交易與事件監聽，將兩者視為分開的應用程式。

## 小結
這篇簡單紀錄了使用 Hyperledger Fabric 開發一個應用程式的要點，涵蓋了查詢帳本、提交交易以及接收通知等核心功能。通過使用fabric-network package、Gateway 與 Discovery 服務，可以更簡單地與區塊鏈網路進行互動，實現應用程式的各項需求。

Hyperledger Fabric 筆記（三）

本系列文章是以 [Blockchain with Hyperledger Fabric, Second Edition](https://www.amazon.com/Blockchain-Hyperledger-Fabric-decentralized-applications/dp/1839218754) 書中的內容為基礎，配合一些實務上遇到的問題所做的筆記。

在區塊鏈系統中，帳本與資料庫的運作雖然看似相似，但兩者間存在一個關鍵的不同點。帳本僅允許交易的添加，不允許修改和移除。正因為如此，我們將寫入區塊鏈的交易視為不可變的。

## 驗證
所有記錄在帳本上的交易都會經過兩個完整性檢查：

1. 業務對象的更改是有效的：需要確認修改前的狀態與帳本狀態一致。
2. 所有必要的組織都同意變更：需要所有必要的背書節點背書。

所有被寫入區塊中的交易都會被確認，並標記為有效或無效的交易。所有交易都會被記錄在區塊中，但只有有效的交易會影響後續流程。

## MVCC（多版本控制）
Hyperledger Fabric 使用 MVCC 機制來確保帳本的一致性並避免雙重花費產生。例如，攻擊者可能透過手段讓同一枚代幣被多次使用，這會造成帳本結果不一致。傳統的中心化系統可能會透過鎖定機制避免同一鍵值被重複修改，但在去中心化的 Fabric 網路中無法做到這一點。

MVCC 是一種用於處理交易的並發執行和隔離的機制。它允許在一個數據庫中同時存在多個版本的數據，並且允許用戶在不干擾其他用戶的情況下執行交易。數據庫在執行交易時會在背景中創建一個新版本的數據，並在交易完成後將該版本提交到數據庫中。當另一個用戶執行交易時，數據庫會再次創建一個新版本的數據，從而同時存在多個數據版本。在讀取數據時，數據庫會選擇最新版本並返回給用戶。這樣，用戶就可以在不干擾其他用戶的情況下安全地讀取數據/執行交易。版本的儲存是透過讀寫集來進行的。

## 帳本
區塊儲存的是交易資料，物件狀態則儲存在狀態資料庫中。這兩者是應用程式與智能合約主要互動的對象。區塊鏈是帳本的核心組件，即使狀態資料庫被刪除或遺失，我們仍然可以透過區塊鏈的交易資料重新生成物件狀態。但如果區塊鏈遺失，則無法再重新獲取過去的交易歷史。

## 狀態資料庫（State Database）
狀態資料庫儲存所有物件的狀態，因此是最常被讀取的帳本組件。它被稱為世界狀態（World State）。與比特幣等區塊鏈不同，帳本不必每次都計算過往的交易來獲得現有狀態，而是直接從狀態資料庫讀取。

### 狀態
狀態的結構是一組鍵值對（key-value pairs），鍵值為物件的名稱（例如：CAR1），而其值則是名稱值對（name-value pairs），記載該物件的詳細資訊（例如：Owner: Sara）。

### 狀態集合（State Collections）
我們將世界狀態視為帳本的預設集合。此外，也可以創建指定的集合。例如，將車子的品牌、型號等資訊儲存在世界狀態中，而將擁有者、車輛編號等私密資料儲存在另一個集合中。

## 交易流程
![](/images/application-and-smart-contracts-operate-within-a-consensus-framework.png '交易流程')
1. 應用程式提交交易：應用程式提交交易到區塊鏈網路中，這裡可以想像應用程式實際上是在說「我希望將 CAR1 的擁有者由 Sara 轉移給 Bob。」應用程式只能完成交易流程中的提交部分。

2. 背書請求：Fabric 確認背書策略（endorsement policy），並將交易發給相應組織的節點上的智能合約。

3. 合約執行：智能合約訪問帳本，透過輸入的值計算輸出結果。合約回傳的內容包含before-image和after-image，但不會對帳本產生更改。

4. 簽名與交易組裝：節點上的合約傳回結果後，每個節點將結果簽名並組裝。交易會被放進塊中，通常節點回傳結果一致，否則會根據大多數相同結果來決定。

5. 共識與寫入區塊鏈：最終的共識發生在第五步，所有交易被放入區塊鏈，但只有有效交易會改變物件狀態。即使節點無權參與交易，也可判斷交易簽章是否合法。

如果交易結果不一致，則會根據endorsement policy做出判斷，如果endorsement policy規定需要所有簽章，則即使大部分相同，該交易依然為無效交易。

## 智能合約
### 背書政策（Endorsement Policy）
背書政策是隨著智能合約一起運行的，每個智能合約都有特定的背書政策。這是 Hyperledger Fabric 與比特幣或以太坊區塊鏈的不同之處。雖然背書政策與智能合約綁定，但兩者可以分開處理。例如，當有新的組織加入網絡時，可以單獨更改背書政策，而無需更新智能合約。

背書政策可以設為以下幾種形式：
```
AND('ORG1.Member', 'ORG2.Member')
OR('ORG1.Member', 'ORG2.Member', 'ORG3.Member')
OUTOF(2, 'ORG1.Member', 'ORG2.Member', 'ORG3.Member')
```
儘管背書政策是對所有組織公開的，但合約本身則不是，這確保了合約內部的業務邏輯對所有組織保持隱藏。

### 基於狀態的背書（State-based Endorsement）
背書政策甚至可以針對單獨物件進行設定。舉例來說，如圖所示，CAR1 如果要更新狀態，則必須由 Sara 簽章。如果 CAR1 被轉移給了 Bob，背書政策也需要相應地修改。
![](/images/state-based-endorsement.png '基於狀態的背書')


Hyperledger Fabric 交易的儲存與驗證

Hyperledger Fabric 筆記（二）

本系列文章是以 [Blockchain with Hyperledger Fabric, Second Edition](https://www.amazon.com/Blockchain-Hyperledger-Fabric-decentralized-applications/dp/1839218754) 書中的內容為基礎，配合一些實務上遇到的問題所做的筆記。

Hyperledger Fabric是一個企業級的區塊鏈平台，主要提供模組化與可擴展的解決方案，以滿足業務網路的需求。這篇文章描述其主要的組成元素、設計原則、參考架構、運行機制及驗證過程。

## Hyperledger Fabric的組成元素
Hyperledger Fabric有三個重要的組成元素：

1. 成員管理（Membership Service）
成員管理服務負責頒發和管理網路中成員的憑證。雖然Hyperledger Fabric提供了自己的成員管理服務（Hyperledger Fabric CA），但用戶也可以使用任何能夠頒發EC證書的系統（基於X509的PKI）。

2. 排序節點（Dedicated Orderer Nodes）
排序節點的主要功能是將新創建的區塊廣播至區塊鏈網路中。Hyperledger Fabric提供了三種類型的排序方式：Solo（適用於開發測試）、Raft（適用於生產環境）和Kafka（具有高容錯性）。排序服務是可插拔的，只需實現基於gRPC接口定義的原子廣播API（Atomic-Broadcast API）即可。
![](/images/eager-update-everywhere-with-distributed-locking.png '排序節點')

3. 節點（Peers）
節點負責執行智能合約並維護帳本。具體來說，節點負責：

- 背書交易（Endorsement）：執行但不提交交易。
- 從排序節點接收批量背書交易，然後驗證並提交交易，以消除非確定性。

## Hyperledger Fabric的設計原則
Hyperledger Fabric的設計基於以下幾個核心原則：

1. 可模組化與可擴展性
Hyperledger Fabric的架構設計允許用戶根據需求模組化各個組件，例如：

- 共識層
- 合約（Chaincode）層
- 溝通（Gossip）層
- 資料儲存
- 身份服務
- 可插拔密碼學
2. 操作互通性
Hyperledger Fabric提供向後操作性，以確保在升級時不影響現有操作。然而，這並不意味著提供不同Hyperledger專案之間或不同區塊鏈網路之間的互操作性。

3. 安全的解決方案
企業和業務網路的安全性是Hyperledger Fabric最重要的考量之一，確保所有交易的機密性和完整性。

4. 不被察覺的Token
Hyperledger Fabric不使用加密資產、加密貨幣或代幣作為建立信任系統的激勵機制。儘管其支持資產代幣化，但這與作為激勵生成的系統代幣是完全不同的概念。

5. 豐富且易操作的API
Hyperledger Fabric提供了豐富且易於操作的API，以確保區塊鏈網路可以與企業系統或商業網路順利整合，而不會暴露區塊鏈網路系統本身。

## Hyperledger Fabric的參考架構
以下是Hyperledger Fabric架構中的重要元件：

1. 會員服務（Membership Services）
會員服務模組在區塊鏈網路創建時負責建立根憑證（Root of Trust），並確保管理員的身份。會員服務本質上是一個證書頒發機構，利用PKI來管理私鑰，並向網路成員頒發憑證，保證網路的安全性。

2. 交易（Transactions）
交易是向區塊鏈發起的請求，用來執行帳本上的函式。交易由智能合約（Chaincode）執行，透過密碼學驗證鏈上的哈希值來確保交易的完整性。

3. 通道（Channel）
一個Hyperledger Fabric區塊鏈網路中可以包含多條通道。每個通道擁有各自的帳本、共識協議、智能合約、加入規則和節點等，實現資料隔離與隱私保護。

4. 狀態資料庫（State Database）
狀態資料庫，也被稱為世界狀態（World State），儲存帳本的當前狀態。與帳本不同的是，帳本儲存完整的交易紀錄，而世界狀態儲存的是最新的狀態。可選的資料庫包括：

- LevelDB：內建的鍵值對資料庫，支援鍵查詢、組合鍵查詢及範圍鍵查詢。
- CouchDB：除了支援上述功能外，還支援富查詢（Rich Query）及索引（Index）。
5. 合約服務（Contract Service）
合約作為交易的一部分，是儲存在帳本上的應用程式級別的程式碼。鏈碼執行的交易會改變世界狀態。合約需要安裝在節點上，並在特定通道和對等節點上實例化。合約可以在通道內所有節點間共享，也可以僅與特定子集合共享。

6. 事件（Events）
在驗證節點或合約的過程中會產生事件（預定義的通道事件和合約生成的自定義事件）。應用程式可以監聽這些事件並做出相應的行動。事件可以透過WebHooks或Kafka等工具傳遞。從2.0版本開始，新增了包括提交區塊、交易、特定組織的私有數據等事件。

7. 共識（Consensus）
共識是區塊鏈系統的核心。Hyperledger Fabric中的共識服務允許網路中的成員提出並認證經過數位簽章的交易。共識機制是可插拔的，並與Hyperledger提出的endorse-order-validate模型緊密相關。排序服務將多個交易分批放入區塊中，透過哈希值串接形成區塊鏈。

8. 帳本（Ledger）
Hyperledger Fabric的帳本是加密分布式的，透過追加寫入（Append-Only）資料結構來實現。每個節點都分別維護自己所屬通道的帳本副本。

9. 加密資料（Private Data）
加密資料允許組織在帳本上儲存加密的資料，這些資料儲存在授權節點上的加密狀態資料庫中。合約可以透過有權限的節點存取這些加密資料。

10. SDK
客戶端的SDK允許使用者部署和調用帳本上的交易。目前支援Node.js和Java（Go與Python版本正在開發中）。

## Hyperledger Fabric的運行架構
Hyperledger Fabric的運行架構可分為以下幾個步驟：

1. 交易提交（Transaction Proposal）
交易透過客戶端SDK提交，同時將交易發送至通道中每個參與共識的背書節點（Endorsing Peers）。

2. 背書交易（Transaction Endorsement）
每個背書節點執行交易，並回簽執行結果。結果以交易的讀寫集（Read-Write Set）的形式存在，並回傳至SDK。每個節點可能同時執行多筆交易，支援來自不同通道的併發交易。

3. 提交交易至排序服務（Transaction Submission to Ordering Service）
SDK將收到的已背書交易提交至排序服務。排序服務接收背書交易，並將其排序後放入區塊，然後將區塊傳送給通道中的所有節點。

4. 交易驗證（Transaction Validation）
節點收到區塊後會先進行驗證，包括檢查背書政策（Endorsement Policy）及狀態資料庫中讀寫集的讀取部分。經過驗證後，區塊被提交到帳本上，交易則被提交到狀態資料庫。

## 節點種類
Hyperledger Fabric中的節點可分為以下幾種類型：

1. 承諾節點（Committing Peer）
承諾節點負責維護帳本及狀態，並提交交易。這些節點不參與交易的背書。

2. 背書節點（Endorsing Peer）
背書節點負責執行交易並簽署背書結果，這些結果會被排序節點使用以決定是否將交易納入區塊。不同通道可以有不同的背書政策。

3. 排序節點（Ordering Node）
排序節點負責交易的排序和打包，並將區塊廣播至整個網路。這些節點不執行交易或維護帳本，只處理交易排序。

## 驗證
驗證過程在Hyperledger Fabric中至關重要，確保了交易的合法性和網路的一致性。驗證由以下兩個角色共同完成：

1. 背書驗證（Endorsement Validation）
- 執行者：背書節點。
- 職責：確認交易執行結果符合智能合約的邏輯，並根據預定的背書政策對交易進行簽名。
- 作用：確保交易內容的正確性，防止惡意或錯誤的交易進入排序流程。
2. 排序驗證（Ordering Validation）
- 執行者：排序節點。
- 職責：驗證已背書的交易是否滿足提交到帳本的條件，並控制交易的順序性，確保整個網路達成共識。
- 作用：維護網路中交易的有序性和一致性，防止雙重支付等問題的發生。


Hyperledger Fabric：架構、組成與運行機制