하이퍼레저 컴포저의 플레이그라운드는 비즈니스 네트워크 환경설정, 배포, 테스팅에 대한 사용자 인터페이스를 제공합니다. 이외 플라이그라운드의 고급기능은 사용자가 비즈니스 네트워크 보안을 관리하게 해주거나, 비즈니스 네트워크에 참가자들을 초대하거나 여러 블록체인 네트워크를 연결할 수 있도록 해주기도 합니다.
플레이그라운드를 처음 사용한다면, 아래 플레이그라운드 튜토리얼을 추천합니다. 해당 튜토리얼은 비즈니스 네트워크 카드로 상호작용하기 전 새로운 블록체인 비즈니스 네트워크를 생성하고 배포하고 테스트하는 방법을 알려줍니다.
주의: 두 명 이상의 사용자가 하이퍼레저 컴포저 플레이그라운드를 사용해 동일한 하이퍼레저 패브릭 객체에 접속하려 한다면, 각 사용자는 비즈니스 네트워크 정의가 다른 유저에 의해 업데이트 된 후 브라우저를 새로고침해야만 합니다. 브라우저를 새로고침하면 다른 사용자에 의해 변경된 비즈니스 네트워크 정의가 반영됩니다. 다른 사용자가 변화한 내용을 업데이트하지 않고 비즈니스 네트워크를 변경하면, 해당 내용은 손실됩니다.
Navigating Playground
The Business Networks page
비즈니스 네트워크 페이지는 플레이그라운드를 시작하는 기본 화면입니다. 여기서 사용할 수 있는 모든 비즈니스 네트워크 카드를 볼 수 있습니다. 각 비즈니스 네트워크 카드는 블록체인 비즈니스 네트워크에 접속하는데 필요한 모든 정보를 갖고 있습니다. 유효한 비즈니스 네트워크 카드로만 블록체인 비즈니스 네트워크에 접속할 수 있습니다. 한번 배포된 비즈니스 네트워크에 접속하면 Define 페이지를 볼 수 있습니다.
이 페이지에서 할 수 있는 것들은 다음과 같습니다:
비즈니스 네트워크에 접속하기. 이미 배포된 비즈니스 네트워크와 그에 대한 비즈니스 네트워크 카드가 준비되었다면, 해당 비즈니스 네트워크에 접속하기 위해 Connect now를 클릭할 수 있습니다.
비즈니스 네트워크 배포하기. 플레이그라운드를 처음 사용하거나 새로운 네트워크를 시작하려 한다면 자신만의 네트워크를 시작할 수 있습니다. 새로운 비즈니스 네트워크를 시작할 때 샘플 네트워크를 기반으로 비즈니스 네트워크를 정의하거나 작업물에서 스스로 생성할 수도 있습니다.
비즈니스 네트워크 카드로 상호작용하기. 비즈니스 네트워크 카드는 이미 존재하는 비즈니스 네트워크에 접속하는데 사용됩니다. 또한 비즈니스 네트워크 카드는 connection profile과 identity의 조합입니다. 이 카드는 identity나 카드를 삭제하거나, 카드를 export하거나, 대응하는 비즈니스 네트워크에 연결하는 기능을 제공합니다.
비즈니스 네트워크 카드 import하기. 컴퓨터에 있는 .card 파일을 import하는 가장 간단한 방법은 비즈니스 네트워크 페이지에서 비즈니스 네트워크 카드를 추가하는 것입니다.
user ID와 secret 사용해서 접속하기. 네트워크 관리자로부터 ID와 secret을 부여받았다면, Connect using credentials를 클릭해서 접속하고 비즈니스 네트워크 카드를 생성할 수 있습니다.
플레이그라운트 튜토리얼을 사용해 실행하기. 어디서부터 시작해야할지 모르겠다면 플레이그라운드 튜토리얼을 통해 비즈니스 네트워크를 새엇ㅇ하고 기본 동작들을 수행해볼 수 있습니다.
Business network options
비즈니스 네트워크 카드를 사용해 한번 비즈니스 네트워크에 접속하면, Define 탭이나 Test 탭에 사용할 수 있는 여러가지 옵션들이 있습니다.
좌측 상단은 사용중인 connection profile 이름이며 접속한 비즈니스 네트워크입니다. 위의 예제에서 connection profile은 Web이라 불리고 비즈니스 네트워크 이름은 basic-sample-network입니다.
Define 및 Test 탭으로의 링크. Define 탭에서는 비즈니스 네트워크 내용을 추가, 수정, 삭제할 수 있고, Test 탭에서는 Define 탭에 정의되어 있는 asset이나 participant를 생성할 수 있으며, 비즈니스 네트워크의 기능들을 테스트 할 수 있습니다.
우측 상단의 드롭다운메뉴는 비즈니스 네트워크에 접속하는데 사용되는 identity를 나타냅니다. 드롭다운메뉴는 Identity Registry에 대한 링크를 포함합니다. 또 비즈니스 네트워크에서 로그아웃하고 비즈니스 네트워크 페이지로 돌아갈 수도 있습니다.
The Define tab
Define 탭은 비즈니스 네트워크를 생성, 편집, 수정하는데 사용됩니다.
Define탭의 왼쪽은 현재 비즈니스 네트워크 정의 파일 리스트를 나타냅니다. 파일 내용을 보려면 파일을 클릭하면 되고, 그러면 편집모드로 나타납니다. Add a file 버튼을 통해 비즈니스 네트워크에 새로운 파일을 추가할 수도 있습니다. 모델파일, 스크립트파일, 접근제어파일, 쿼리파일이 비즈니스 네트워크에 추가될 수 있습니다.
비즈니스 네트워크 정의에 파일을 추가하거나 수정하면 네트워크에 변경된 내용을 Deploy changes 버튼을 통해 변경된 내용을 배포할 수 있습니다. Deploy changes 버튼을 누른 후에는 Test 탭에서 변경된 내용을 시험해볼 수 있습니다. Export 버튼은 현재 비즈니스 네트워크를 .bna 파일로 다운로드할 수 있게 해줍니다.
주의: 두 명 이상의 사용자가 하이퍼레저 컴포저 플레이그라운드를 사용해 동일한 하이퍼레저 패브릭 객체에 접속하려 한다면, 각 사용자는 비즈니스 네트워크 정의가 다른 유저에 의해 업데이트 된 후 브라우저를 새로고침해야만 합니다. 브라우저를 새로고침하면 다른 사용자에 의해 변경된 비즈니스 네트워크 정의가 반영됩니다. 다른 사용자가 변화한 내용을 업데이트하지 않고 비즈니스 네트워크를 변경하면, 해당 내용은 손실됩니다.
The Test tab
Test 탭은 Define 탭에서 정의한 asset, participant, transaction를 사용해 배포된 비즈니스 네트워크를 테스트할 수 있습니다.
Test 탭의 왼족에는 각 participant와 asset 타입이 나열되어 있습니다. participant, asset 혹은 All Transactions를 클릭하면 해당 타입에 활성화되어있는 모든 객체를 보여주는 registry가 나옵니다. 예를 들어 SampleParticipant를 클릭하면 생성된 모든 SampleParticipants를 보여주는 registry가 나옵니다. 많일 Test탭을 처음 사용한다면 registry들은 비어있을 것입니다.
각 registry에서 대응하는 asset, participant를 생성하거나 transaction을 제출할 수 있습니다.
All transactions registry는 Historian이라고도 알려져 있습니다. 여기서는 비즈니스 네트워크에서 발생하는 각 트랜잭션 기록을 확인할 수 있으며, 이 기록은 participant나 asset 생성같은 시스템 이벤트도 포함합니다. transaction registry에서는 트랜잭션을 제출하고 어떤 리소스가 변경되었는지 확인함으로써 그 트랜잭션의 영향을 확인할 수 있습니다.
Adaptation Layer는 기존 블록체인 시스템을 캘리퍼 프레임워크에 통합하는데 사용됩니다. 각 어댑터는 블록체인의 native SDK나 RESTful API를 사용해 'Caliper Blockchain NBIs'를 구현합니다. 하이퍼레저 패브릭 1.0과 소투스가 현재 지원되며 이더리움 및 다른 블록체인 시스템도 지원 예정입니다.
Interface & Core Layer
인터페이스 및 코어 레이어는 핵심 기능을 구현하고 상위 애플리케이션을 위한 인터페이스를 제공합니다. 네 종류의 NBI가 제공됩니다.
Blockchain operating interfaces: 벡엔드 블록체인에 있는 스마트 컨트랙트를 배포하거나, 컨트랙트를 호출하거나, 원장의 상태를 쿼리하는 것 등의 동작을 포함합니다.
Resource Monitor: 모니터를 시작 혹은 중지하고 CPU, 메모리, 네트워크 IO 등 벡엔드 블록체인 시스템의 리소스 사용 상태를 가져오는 작업을 포함합니다. 현재 두 종류의 모니터를 제공하며, 하나는 로컬 / 원격 도커 컨테이너의 상태를 확인하는 것이고, 또 다른 하나는 로컬 프로세스의 상태를 확인하는 것입니다. 추후에 더 많은 모니터들이 구현될 예정입니다.
Performance Analyzer: 미리 정의된 성능 수치 (TPS, 지연, 성공률 등) 를 읽고 벤치마크 결과를 출력합니다. 주요 지표는 블록체인 NBIs를 호출하는 동안 기록됩니다. 예를 들어 생성 시간, 트랜잭션 커밋 시간, 트랜잭션 결과 등이 있습니다. 이러한 들은 결과를 생성하는 데 사용됩니다.
Report Generator: 테스트 결과를 HTML 로 생성하는 기능을 포함합니다.
Application Layer
애플리케이션 레이어는 일반적인 블록체인 시나리오를 테스팅하는 것을 포함합니다. 각 테스트는 벡엔트 블록체인 네트워크와 테스트 인자를 정의하는 환경설정 파일을 갖고 있습니다. 이 테스트는 블록체인 시스템의 성능을 테스느하는데 사용할 수 있습니다.
기본 블록체인 엔진은 개발자들이 프레임워크를 이해하고 스스로 빠르게 테스트를 할 수 있도록 구현되어 있습니다. 벤치마크 엔진을 어떻게 사용하는지는 이후에 설명합니다. 물론, 개발자들은 프레임워크 없이 NBIs를 직접 사용해 테스트를 할 수도 있습니다.
Benchmark Engine
Configuration File
두 종류의 환경설정 파일이 사용됩니다. 하나는 벤치마크 설정 파일인데, 워크로드같은 벤치마크 인자를 정의합니다. 또 다른 하나는 블록체인 설정 파일로 SUT와 상호작용하는 것을 돕는데 필요한 정보를 정의합니다.
name&description: 사람이 읽을 수 있는 형태의 벤치마크에 대한 이름 및 설명입니다. 이는 리포트 생성기가 테스트 리포트를 생성할 때 사용합니다.
clients: 클라이언트 타입 및 관련 인자를 정의합니다. 'type' 속성은 'local' 혹은 'zookeeper' 이어야 합니다.
local: 이 경우, 로컬 프로세스가 fork되어 블록체인 클라이언트처럼 행동합니다. fork된 클라이언트 수는 'number' 속성에 정의되어야 합니다.
zookeeper: 이 경우, 클라이언트는 다른 머신에 위치하며 마스터 주키퍼를 통해 태스크를 수행합니다. 주키퍼 서버 주소 및 주키퍼 클라이언트에 의해 로컬에서 실행되어 시뮬레이팅할 블록체인 클라이언트 수가 정의되어야 합니다. 주키퍼 환경설정의 예는 아래와 같습니다. "type" : "zookeeper", "zoo" : { "server" : "10.229.42.159:2181", "clientPerHost" : 5 }
label: 테스트에 대한 힌트입니다. 예를 들어, 성능을 테스트하기 위해 주로 사용될 트랜잭션을 언급하기 위해 트랜잭션 이름을 라벨 이름으로 사용할 수 있습니다. 또한 이 값은 blockchain.getContext()의 컨텍스트 이름으로 사용됩니다. 예를 들어, 개발자가 다른 패브릭 채널에 대해 성능을 측정하고 싶을 때, 다른 패브릭 채널에 대해 각각 다른 라벨로 테스트를 수행할 수 있습니다.
txNumber: 각 테스트 차수에서 수행될 다른 트랜잭션 수를 배열로 정의합니다. 예를 들어, [5000, 400]은 총 5000개의 트랜잭션이 첫 번째 차수에서생성될 것이며 두 번째 테스트에서는 400개가 생성될 것임을 의미합니다.
txDuration: 각 테스트 차수에서 실행할 시간을 배열로 정의합니다. 예를 들어 [150, 400]은 두 번의 테스트가 진행될 것을 의미하며, 첫 번째는 150초동안, 두 번째는 400초 동안 수행될 것임을 의미합니다. txNumber와 함께 지정하면 txDuration 옵션이 우선 적용됩니다.
rateControl: 각 테스트 차수에서 벤치마크 테스트를 하는 동안 사용자가 정의한 rate control을 배열로 정의합니다. 정의하지 않을 경우 기본 값은 'fixed-rate'이며 이는 벤치마킹을 1 TPS rate로 설정합니다. 정의되었다면, rate control 메카니즘이 존재해야 하며, 어느 메시지가 보내지고, 혹은 메세지 속도 프로파일을 지정하는 데 사용할 수 있는 옵션이 제공 것입니다. 각 테스트 차수에서 txNumver나 txDuration이 정의되어 있다면 이에 대응하는 rate control item을 rateControl 배열에 갖고 있어야 합니다. 사용 가능한 속도 컨트롤러 및 사용자 정의 속도 컨트롤러에 대한 사항은 Rate Controller 섹션을 참고하세요.
trim: 테스트 리포트에 포함되는 warm-up 및 cool-down 단계를 제거하기 위해 클라이언트 결과에 트리밍 기능을 수행합니다. 이 기능을 지정했다면, 트림 옵션은 차수 별 측정을 고려합니다. 예를 들어 txNumber가 30으로 수행된다면 각 클라이언트로 부터 온 초기 30개의 트랜잭션과 제일 마지막 30개의 트랜잭션 결과는 결과 통계를 생성할 때 무시됩니다. txDuration이 사용된 경우, 초기 및 마지막 30초의 결과는 무시됩니다.
arguments: 사용자 정의 테스트 모듈로 전달되는 인자를 정의합니다.
callback: 이 테스트 차수에서 사용되는 사용자 정의 모듈을 정의합니다. 더 자세한 사항은 User Defined test module 섹션을 참고하세요.
monitor: 리소스 모니터 유형과 모니터 객체, 모니터링 시간 간격을 정의합니다.
docker: 도커 모니터는 로컬 혹은 원격 호스트에 있는 도커 컨테이너를 모니터링하는데 사용됩니다. Docker Remote API는 원격 컨테이너의 상태를 수집하는데 사용됩니다. 예약된 컨테이너 이름이 'all'인 경우 호스트의 모든 컨테이너는 모니터링 됩니다. 위의 예제에서, 모니터가 초 당 두 개의 컨테이너 상태를 수집한다면, 하나는 로컬 컨테이너인 'peer0.org1.example.com'이고 다른 하나는 '192.168.1.100'에서 도커 리스닝 포트가 2375인 원격지 컨테이너 'orderer.example.com' 입니다.
process: 프로세스 모니터는 로컬 프로세스를 모니터할 때 사용됩니다. 예를 들어, 사용자는 블록체인 클라이언트를 시뮬레이팅할 때 리소스 사용량을 모니터하기 위해 이 모니터를 사용할 수 있습니다. 'command'와 'argument' 속성은 프로세스를 정의합니다. 'multiOutput' 속성은 여러 프로세스일 경우 정의합니다. 'avg'는 이 프로세스들의 리소스 사용량에 대한 평균값을 나타내며 'sum' 은 총 합계를 나타냅니다.
others: 구현중
Master
마스터는 3단계로 구성된 기본 테스트를 구현한다.
Preparing stage: 이 단계에서, 마스터는 블록체인 환경설정 파일로 내부 블록체인 객체를 생성하고 초기화한다. 또 환경설정에 정의된 스마트 컨트랙트를 배포하고 벡엔드 블록체인 시스템의 리소스 사용량을 모니터링하기위한 모니터 객체를 시작한다.
Testing stage: 이 단계에서, 마스터는 벤치마크 환경설정 파일에 따라 테스트를 수행하기 위해 루프를 시작한다. 작업은 정의된 워크로드에 따라 생성되고 클라이언트들에게 할당된다. 클라이언트들로부터 수집된 성능 통계는 이후 분석을 위해 저장된다.
Reporting stage: 각 테스트 차수로부터 클라이언트들에게서 수집된 결과가 분석된다. 이는 자동으로 HTML 형태의 리포트를 생성한다. 리포트 샘플은 다음과 같다.
Clients
Local Clients
이 모드에서 마스터는 로컬에 실제 테스팅 작업을 수행하는 여러 개의 클라이언트(자식 프로세스)를 포크하기위해 Node.js 클러스터 모듈을 사용한다. Node.js는 기본적으로 단일쓰레드이므로, 로컬 클러스터는 멀티코어머신에서 클라이언트의 성능을 향상시키기 위해 사용될 수 있다.
전체 워크로드는 자식 프로세스들에게 동등하게 나뉘어서 할당된다. 자식 프로세스는 벡엔드 블록체인과 상호작용할 수 있는 임시로 생성된 컨텍스트를 사용해 블록체인 클라이언트처럼 행동한다. 컨텍스트는 보통 클라이언트의 신원 및 암호화 정보를 가지고 있으며 이는 테스팅 작업이 끝나면 반환된다.
하이퍼레저 패브릭에서 컨텍스트는 또한 특정 채널에 바인딩될 수 있다. 이 관계는 패브릭 환경설정 파일에 정의된다.
클라이언트는 사용자가 정의한 테스팅 로직을 갖고 있는 테스트 모듈을 호출한다. 모듈에 대해서는 이후에 설명한다.
로컬 클라이언트는 첫 번째 테스트 차수가 시작될 때 한 번만 시작될 수 있으며, 테스트가 모두 끝나면 삭제된다.
Zookeeper Clients
이 모드에서 여러 개의 주키퍼 클라이언트는 독립적으로 실행된다. 주키퍼 클라이언트는 실행된 테스팅 작업을 모니터링하기위해 스스로 등록한다. 테스트가 끝나면 성능 통계 결과를 갖고 있는 znode가 생성된다.
주키퍼 클라이언트는 또한 여러 개의 자식 프로세스 (로컬 클라이언트) 를 포크하여 위 테스팅 작업을 실질적으로 수행한다.
더 자세한 내용은 Zookeeper Client Design 섹션에서 확인할 수 있다.
User Defined Test Module
테스트 모듈은 트랜잭션을 생성하고 제출하는 함수가 구현된 것이다. 이렇게 함으로써 개발자들은 자신의 테스팅 로직을 구현할 수 있고, 이를 벤치마크 엔진에 통합할 수 있다.
세 가지 함수가 구현 및 export 되며, 모든 함수들은 약속된 객체를 반환한다.
init: 각 테스트 차수가 시작할 때 클라이언트에 의해 호출되며, 주어진 블록체인 객체, 컨텍스트, 사용자 지정 인자를 벤치마크 환경설정 파일에서 읽어온다. 블록체인 객체 및 컨텍스트는 이후 사용을 위해 저장되어야 하며 다른 초기 작업은 여기서 실행된다.
run: 실제로 트랜잭션이 생성 및 제출되며, 이 때 캘리퍼의 블록체인 API를 사용한다. 클라이언트는 워크로드에 따라 이 함수를 반복적으로 호출한다. 각 호출에서 하나의 트랜잭션만 제출되는 것을 추천하지만, 필수 사항은 아니다. 여러 개의 트랜잭션이 매번 제출되면 실제 워크로드는 구성된 워크로드와 다를 것이다. 함수는 비동기 방식으로 실행되어야 한다.
이 튜토리얼은 구글, 페이스북, 트위터 등에서 사용하고 있는 OAUTH 2.0 인증 방식을 이용하는 방법에 대해 설명합니다. 이 방법을 이용해 REST 서버 객체의 리소스에 대한 접근 권한을 부여하거나 블록체인 네트워크의 end user가 배포된 스마트 컨트랙트나 비즈니스 네트워크와 상호작용할 수 있도록 할 수 있습니다. 개요도는 아래 그림에 나와 있고, 인증 플로우에 대해 더 자세히 나타낸 그림은 더 아래쪽에 있습니다. 튜토리얼을 진행하면서 REST 서버를 다중 사용자 모드로 실행시키고, REST API를 통해 리소스에 접근하는 여러 블록체인 id로 심플 Trade 네트워크와 상호작용하는 테스트를 진행합니다. 튜토리얼을 진행하기 위해 Google 계정 및 권한 설정을 해야 합니다. (이 작업을 진행하기 위해서는 appendix를 참고하세요. 그리 오래걸리지 않습니다.) 또 최소한 튜토리얼에 나오는 ID와 메타데이터를 사용해야 합니다. 기본 블록체인 네트워크로는 하이퍼레저 컴포저를 사용합니다.
참고: 우리는 아래 링크 내 Step 3 'Setting up your IDE'에 나온 'Development Fabric' 네트워크를 사용합니다.
다양한 Passport 전략이 있습니다. 비즈니스 조직 관점에서 SAML, JSON Web Tokens (JWT), LDAP 같은 기업 전략은 확실히 적합합니다. (예: 조직 내 Active Directory server) 우리는 이 튜토리얼에서 Google+ API를 사용한 인증 방식을 제공합니다. 이 방식은 구글 계정을 가진 누구든지 쉽게 사용할 수 있으며 (어떻게 하는지는 Appendix를 참고하세요.) 서비스 환경설정을 할 수 있고, 미들웨어를 미리 설치하는 것에 대한 걱정 없이 이 튜토리얼을 진행할 수 있습니다.
OAUTH2.0은 실제로는 'authorization protocol' 이지만 'delegated authentication sheme' 처럼 사용됩니다. authentication은 보통 개인 credential을 이용해 신원을 확인하는 것을 의미합니다. 반면 여기서 사용되는 OAUTH2.0 authenticationdms 'delegate' authentication sheme로 사용됩니다. 백그라운드로 확장할 수 있는 다양한 '역할' 들이 있습니다. 컴포저 REST 서버의 역할은 Google+ API OAuth2.0 sheme에 의해 보호되는 비즈니스 네트워크 리소스에 대한 접근을 제공하는 것입니다. 리소스 소유자는 우리가 설정한 (appendix에 나오듯이) Google+ API 사용자 계정이며, 이 소유자의 역할은 클라이언트 애플리케이션에 동의(혹은 기타)를 부여하는 것입니다. Google+ authorization 서버는 리소스 소유자에게 동의를 요청하고 REST 클라이언트 (예: 웹 클라이언트 애플리케이션)에 access token을 발행해서 보호된 리소스에 접근할 수 있게 해줍니다. 더 작은 API 제공자도 동일한 애플리케이션이나 authorization 서버 및 리소스 서버용 Google+의 URL 공간을 사용할 수 있습니다. 이는 즉, 웹 애플리케이션 사용자 (비즈니스 네트워크에 접근하기 위해 REST API를 사용하는) 가 들어오면, 이 사용자는 사전등록을 위해 별도로 아무것도 하지 않아도 됨을 의미합니다. 애플리케이션 사용자는 구성된 클라이언트 애플리케이션에서 동의를 얻습니다. (OAUTH2.0 플로우가 구성되지 않아도) 이 튜토리얼에서 우리는 REST API를 사용하기 위해 브라우저를 사용하고 어떻게 이 authentication 플로우가 실제로 동작하는지 확인합니다.
access key는 다음 동의에 따라 부여됩니다. token이 클라이언트가 OAuth2.0에 의해 보호되고 있는 API에 접근하는 것을 허락해줍니다. OAuth2.0에서 이 access token은 "bearer tokens"라고 불리며 정보에 접근할 때 별도의 signature나 cryptography없이 단독으로 사용될 수 있습니다. 게다가 access token은 사용자 웹 브라우저의 로컬 저장소 내 쿠키에 저장됩니다. 사용자가 연속적인 요청을 수행하면 access token은 쿠키에서 검색할 수 있으며, 사용자를 reauthenticating할 필요없이 이 access token은 유효합니다.
REST 서버는 MongoDB를 사용해 비즈니스 네트워크 카드 (네트워크에 연결하기 위해 필요한)를 유지하도록 구성됩니다. 보통 조직은 아래에 설명된 여러 개의 REST 서버 Docker image를 실행하고 MongoDB 사본같은 고가용성의 영구 저장소를 구성합니다. 고가용성을 위한 구성 요소들은 애플리케이션 사용자가 REST에 배포된 비즈니스 네트워크에 대한 접근 권한을 잃지 않고도 관리자가 REST 서버 객체를 중단, 재시작 혹은 제거할 수 있도록 해줍니다.
이 튜토리얼은 권한이 없는 사용자로 수행해야 합니다. (sudo나 그 이상의 권한이 필요하지 않습니다.)
Step 1: Set up the Persistent DB Credentials Data Stor using MongoDB
앞서 언급했듯이, 우리는 적절한 비즈니스 네트워크 카드가 REST wallet으로 import되면 credential을 영구저장소에 저장합니다.
Start the MongoDB Instance
터미널을 열어서 아래 명령어를 실행하세요.
docker run -d --name mongo --network composer_default -p 27017:27017 mongo
docker image가 다운로드되는 화면이 나오고 SHA256 메시지가 출력될 것입니다. MongoDB docker 컨테이터 객체가 시작됩니다. 여기서는 REST 서버와의 간단한 네트워크 접속을 위해 --network composer_default를 사용하는 것이 중요합니다.
Step 2: Build the REST Server Docker Image with OATUH2.0 module
$HOME 디렉토리에서 dockettmp라는 임시 디렉토리를 생성하고 그 곳으로 이동하세요.
cd $HOME ; mkdir dockertmp
cd dockertmp
임시 폴더에서 Dockerfile이라는 docker 파일을 생성하고 아래 내용을 순차적으로 붙여넣으세요. (RUN과 npm 라인의 백슬래쉬를 포함해서 - 계속 이어진다는 문자열입니다.)
FROM hyperledger/composer-rest-server
RUN npm install --production loopback-connector-mongodb passport-google-oauth2 && \
npm cache clean --force && \
ln -s node_modules .node_modules
이 Docker 파일은 docker image를 /hyperledger/composer-rest-server에 위치시키고 두 개의 npm모듈을 추가적으로 설치합니다:
Dockerfile이 있는 폴더에서 커스텀 Docker REST Server 이미지를 생성하세요.
docker build -t myorg/composer-rest-server .
-t 플래그에 주어진 파라미터는 이 Docker 이미지의 이름을 지정합니다. 우리는 여기서 'myorg/composer-rest-server라고 이름을 붙입니다.
마지막 2줄의 'Successfuly built'를 포함해 아래와 같은 결과를 확인할 수 있습니다.
docker build -t myorg/composer-rest-server .
Sending build context to Docker daemon 4.203GB
Step 1/2 : FROM hyperledger/composer-rest-server
---> e682b4374837
Step 2/2 : RUN npm install --production loopback-connector-mongodb passport-google-oauth2 && npm cache clean --force && ln -s node_modules .node_modules
---> Running in 7a116240be21
npm WARN saveError ENOENT: no such file or directory, open '/home/composer/package.json'
npm WARN enoent ENOENT: no such file or directory, open '/home/composer/package.json'
npm WARN composer No description
npm WARN composer No repository field.
npm WARN composer No README data
npm WARN composer No license field.
+ passport-google-oauth2@0.1.6
+ loopback-connector-mongodb@3.4.1
added 114 packages in 7.574s
npm WARN using --force I sure hope you know what you are doing.
---> a16cdea42dac
Removing intermediate container 7a116240be21
Successfully built a16cdea42dac
Successfully tagged myorg/composer-rest-server:latest
INFO: 위처럼 'npm warn messages'가 출력되어도 괜찮습니다. 이는 무시해도 좋습니다.
마지막으로 하나 윗 폴더로 이동합니다.
cd ..
Step 3: Define Environment variables for REST Server instance configuration
$HOME 디렉토리에 envvars.txt파일을 생성하고 아래 환경설정 내용을 붙여넣으세요. 아래 내용 중 cliend ID와 clientSecret은 본인의 Google API+ 클라이언트 정보를 입력해야 합니다. (Appendix에 나온 것 처럼)
여기서 정의한 환경변수는 우리가 Google OAuth2와 영구 데이터 소스로 MongoDB를 사용한 authentication으로 다중 사용자 서버를 사용한다는 것을 의미합니다.
첫 번째 라인은 네트워크를 시작할 비즈니스 네트워크 카드 이름, 즉 비즈니스 네트워크에 정의된 특정 REST 관리자를 의미합니다. 또한 우리는 이 환경설정에서 REST 서버가 사용할 데이터 소스와 authentication provider를 정의합니다. 이것들은 각각 COMPOSER_DATASOURCES와 COMPOSER_PROVIDERS 변수입니다.
Step 4: Load environment variables in current terminal and launch the persistent REST Server instance
환경 변수를 포함해 방금 생성한 envvars.txt 파일과 동일한 경로에서 아래 커맨드를 실행하세요.
source envvars.txt
INFO 커맨드의 결과물이 아무것도 출력되지 않을 것입니다. envvars.txt에 문법 오류가 발생했다면 에러 메시지가 출력될 것입니다.
아래와 같이 "echo" 커맨드를 두 번 사용해서 환경변수들이 실제로 잘 셋팅되었는지 확인합니다.
echo $COMPOSER_CARD
echo $COMPOSER_PROVIDERS
Step 5: Deploy the sample Commodities Trading Business network to query from REST client
우리는 특정 네트워크 IP정보를 가진 다른 위치에 REST 서버를 호스팅하기 때문에 connection.json파일을 업데이트 해야합니다. 그래야 docket hostname (영구 REST 서버 객체 내에 있는) 이 서로의 IP 주소를 확인할 수 있습니다.
아래의 한 줄은 'localhost' 주소를 docker hostname으로 대체하고 REST 관리자 카드에 들어가는 새로운 connection.json을 생성합니다. 우리는 이 커스텀한 connection.json 파일을 튜토리얼 끝 부분에 있는 OAUTH2.0 REST authentication 을 테스트할 때 사용합니다. 빠르게 hostname을 변경하기 위해 hostname을 복사 붙여넣기 한 다음 $HOME 디렉토리에서 아래 한 줄짜리 명령어를 실행하세요.
INFO: 관리자 id인 restadmin이 초기값으로 사용됩니다. REST 서버는 restadmin이라는 id를 특정 id, 예를 들어 jdoe가 REST client wallet에 셋팅될 때까지 사용합니다.
"System: general business network methods" 섹션으로 이동하세요.
"/system/historian" API로 이동해 "Try it out!" 버튼을 클랙하세요.
우리는 REST 서버 접근을 보호하기 위해 Google+ passport OAUTH2.0 authentication을 사용하도록 설정했기 때문에 아마 Authorized error가 출력될 것입니다. OAUTH2.0 authentication을 통해 한번 authentication이 완료되면 브라우저의 REST API는 Trade Commodity 비즈니스 네트워크와 상호작용할 수 있습니다. (즉, 비즈니스 카드가 import되면)
Step 9: Create some Participants and Identities for testing OAUTH2.0 authentication
이제 비즈니스 네트워크와 상호작용할 수 있느지 테스트하기 위해 특정 참가자 집합과 id를 만들어야 합니다. REST서버는 다중 사용자 모드에서 여러 명의 REST 클라이언트를 처리할 수 있습니다. 우리는 composer CLI 명령어를 사용해 아래와 같이 참가자 및 id를 추가할 것입니다. 첫 번째 이름은 Jo Doe입니다.
Step 10: Authenticating from the REST API Explorer and testing using specific identities
http://localhost:3000/auth/google 로 이동하세요. 이 주소는 Google Authentication consent 화면으로 바로 이동하게 해줍니다.
아래 credential을 이용해 로그인하세요. (아래의 예는, 권고대로 튜토리얼 Appendix에 지침에 따라 직접 설정해야 합니다.)
- Email: composeruser01@gmail.com
- Password:
Google에 의해 authenticated되고 REST 서버 (http://localhost:3000/explorer)로 돌아가 좌측 상단에 access token 메세지를 확인할 수 있습니다. 토큰을 보기 위해 'Show' 버튼을 클릭하세요.
REST 서버는 Google+ OAUTH2.0 서비스 (이 프로젝트/클라이언트 범위에서 정의하고 OAUTH2.0 서비스에 대한 Appendix에서 설정한 client credential을 사용) 로 인증되기 때문에, 블록체인 id 혹은 Trade Commodity 비즈니스 네트워크와 상호작용하기 위해 비즈니스 네트워크 카드를 사용하는 관점에서 보면 우리는 사실 아무것도 하지 않았습니다. 우리는 다음으로 이전에 생성한 jdoe 라는 id를 사용할 것입니다.
Step 11: Check the Default Wallet and Import the card and set a default Identity
먼저, Wallets 내 REST endpoint로 가서 GET 동작을 수행해 wallet의 내용을 각져오세요. wallet이 아무런 비즈니스 네트워크 카드도 가지고 있지 않음을 확인하세요. [ ] 와 같이 텅 비어 있어야 합니다.
REST client wallet에 id를 추가해야합니다. 그리고 이 id를 API 를 호출하는 기본값으로 설정해야 합니다. /Wallets 내 POST로 이동하세요. 이는 /Wallets/Import endpoint라고 불립니다.
jode_exp.card를 import하기 위해 선택하세요. 그리고 카드의 이름을 jdoe@trade-network로 입력한 후 'Try it Out'을 클릭하세요.
스크롤을 내리세요. HTTP Status code가 204 (요청 성공) 이어야 합니다.
다음으로 GET /wallest 로 돌아가세요.
이제 jdoe@trade-network 가 wallet에 import된 것을 확인할 수 있습니다. default property의 값이 true임을 확인하세요. 이는 이 비즈니스 네트워크 카드가 Commodity Trading 비즈니스 네트워크와 상호작용할 때 기본값으로 사용됨 (다른 것으로 변경하기 전까지) 을 의미합니다.
Step 12: Test interaction with the Business Network as the default ID jdoe
System REST API Methods 섹션으로 이동해 /GET/System/Historian 섹션을 클릭하세요.
'Try it Out'을 클릭하세요. Historian Registry에서 블록체인 id인 'jdoe'와 트랜잭션 집합을 확인할 수 있습니다.
Trader 로 이동해 /GET Trader endpoint를 확장하고 'Try it Out' 을 클릭하세요.
authenticated session에서 jdoe로 REST 서버와 상호작용할 수 있는지 확인합니다.
이제 현재 생성된 모든 Trader 참가자를 확인할 수 있습니다. ACL이 설정되면 어느 것을 볼 수 있는지에 대한 제약사항이 설정됩니다. (현재 샘플 네트워크에는 적용되지 않지만, ACL 규칙은 ACL tutorial에서 볼 수 있습니다.) 비즈니스 네트워크에 접근하는 REST API가 플레이그라운드, JS APIs, CLI 등 같은 비즈니스 네트워크와 상호작용하는 다른 것들과 마찬가지로 이제 접근 제어를 할 수 있습니다.
POST /wallet/import 로 돌아가서 kcoe_exp.card를 import하고 이름을 kcoe@trade-network로 설정한 후 'Try it Out'를 클릭하세요. 성공적인 응답 (204) 을 받아야 합니다.
하지만, 이 카드를 사용하기 위해서는 Wallet 의 default카드로 설정해야 합니다. POST /wallet/name/setDefault/로 이동해 kcoe@trade-network 를 default 카드 이름으로 설정하고 Try it Out을 클릭하세요. 이제 디폴트 카드가 되었습니다.
Trader 로 돌아가 /GET Trader endpoint를 확장한 뒤 'Try it Out'을 클릭하세요. 우리는 지금 다른 카드 이름을 사용하고 있으며 여전히 인증을 받으면 REST 서버와 상호작용할 수 있다는 것을 확인해야 합니다.
Conclusion
이것으로 튜토리얼을 마칩니다. 여기서는 클라이언트 기반 Google OAUTH2.0 authentication 서비스를 어떻게 구성하고 클라이언트 애플리케이션을 인증할 수 있는지, 또 매 요청마다 인증하지 않고 보호된 리소스 서버 (REST 서버 객체) 와 상호작용하는 동의를 제공할 수 있는지에 대해 살펴보았습니다. 게다가 REST 서버는 다중 사용자 모드로 운영되어 여러 블록체인 id가 동일한 클라이언트 세션에서 토큰 만료 시간 등에 따라 배포된 Commodity Trading 비즈니스 네트워크와 상호작용할 수 있었습니다.
아래 appendix는 이 튜토리얼에서 Google Authentication scheme가 어떻게 설정되었는지 알려줍니다.
아래와 같은 화면을 볼 수 있을 것입니다. 검색창에 Google+를 입력해 출력된 Google+ API 아이콘을 클릭하세요.
Google+ APIs를 클릭해 활성화하세요.
아직 프로젝트를 갖고 있지 않다면 API를 사용하기 위한 프로젝트를 생성해야 합니다. 'Create Project'를 클릭하세요.
이름을 입력해야 합니다. 'GoogleAuth'라고 입력하고 이 경우에는 ProjectID를 기록해둡니다. 여기서는 proven-caster-19547로 표시되며 이는 나중에 사용됩니다.
프로젝트를 생성한 후 Google+ API 페이지로 다시 돌아가세요. 이제 프로젝트 이름을 볼 수 있고 'Enable' 옵션을 확인할 수 있습니다. 'Enable'을 클릭하세요.
Step A2: Create Credentials Service Account
서비스를 활성화 시키면 이 서비스를 사용하기 위한 Service Account Credentials를 생성할 수 있습니다. 'Create Credentials'를 클릭하세요.
어떤 종류의 credential이 필요한지 묻는 몇 가지 질문이 나옵니다. 아래 스크린샷을 참고해 질문에 답하세요. 'Google+ API', 웹서버 (예: Node js. Tomcat) , 애플리케이션 데이터, Engine사용 안함 등을 선택하세요.
What credentials do I need를 선택하세요.
다음으로 Credentials service account를 설정합니다. 이름은 'GoogleAuthService'로 합니다. 드롭다운 메뉴에서 'Project'를 선택하고 Owner 역할과 JSON 타입을 선택합니다.
'Get your Credentials'를 선택합니다. 이는 JSON 포맷의 service credential을 다운로드할 것입니다. 이를 안전한 장소에 저장하세요.
JSON 파일을 애플리케이션 credential과 함께 저장합니다. credential을 다운로드 받은 후 사이트는 credentials 홈페이지로 돌아갈 것이며 새로운 서비스 account key를 볼 수 있습니다.
Step A3: Create OAUTH2.0 Consent
'OAuth consent screen' 탭으로 이동하세요. 'Google Auth REST OAUTH2 service' 같은 'product name'이 필요할 것입니다. 요청에 대한 권한에 동의할 때 배너창이 나타납니다. (즉, 우리가 main tutotial에서 REST 클라이언트로 테스트할 때 ) 그리고 email주소를 입력한 후 'Save'를 클릭하세요.
OAuth consent 화면은 튜토리얼의 사용자가 Google Auth REST Service로 인증할 때 볼 수 있는 화면입니다.
Step A4: Create OAuth2.0 Client ID credentials for the Credentials Service Account
'Web Applicaton'을 선택하고 'Web Client 1' 같은 샘플 이름을 지정하세요.
'Authorised Javascript Origins' 섹션에 아래 URI를 추가하세요. 이것은 클라이언트 애플리케이션, 즉 REST 서버입니다. (http://localhost:3000)
우리는 아래에 'Authorized Redirect URIs'를 추가해야 합니다. 이것은 인증된 세션이 Google+ OAUTH2.0 authentication service에서 동의를 얻은 후 리다이릭팅되는 곳입니다. 컴포저 REST 서버 환경변수 (특히 envvars.txt 파일 내 COMPOSER_PROVIDER 변수) 에 구성한 것과 콜백함수가 매칭될 것입니다.
'Autorized Redirect URIs' 에서 아래 URIs를 autorised URIs로 추가하세요. 참고: 아래 URI를 복사 붙여넣기 하는것이 가장 좋습니다. 그리고 브라우저에서 각 라인별로 ENTER를 입력하세요. URI 라인 편집기는 간혹 입력 중에 내용을 지울 수 있기 때문입니다. (예: URI입력시 잠시 멈추는 경우)
Access control과 authorization은 하이퍼레저 컴포저의 매우 중요한 부분이며, 이는 블록체인에 있는 멤버 조직간 공유되는 비즈니스 네트워크의 securiry architecture입니다. 하이퍼레저 컴포저는 관리자가 어떤 참가자가 비즈니스 네트워크의 어떤 리소스 혹은 데이터에 접근할 수 있는지를 제어할 수 있게 해줍니다. 이 참가자들은 일반적으로 각 멤버 조직 내에서 동작하며 원장에 대한 그 조직만의 접근 제어 요구사항을 가지고 있습니다. 동시에 모든 멤버 조직 혹은 비즈니스 네트워크에서 상호작용하는 특정 멤버에 공통으로 공유되는 데이터에 대한 접근 제한도 가지고 있습니다.
이 튜토리얼에서는 Commodity Trading network라는 비즈니스 네트워크를 살펴봅니다. 이 네트워크는 이전 튜토리얼 혹은 sample networks에서 볼 수 있습니다. 우리는 이 샘플 네트워크에서 ACL이 어떻게 동작하는지 예를 살펴봅니다.
Access control rules (ACLs를 정의하는 언어)는 크게 두 가지로 나뉩니다.
시스템 네임스페이스 (네트워크 및 시스템 동작 관리) 내 시스템, 네트워크, 관리자 리소스 및 동작에 대한 접근 권한
특정 도메인 비즈니스 네트워크의 ACLs를 통해 주어진 비즈니스 네트워크 자체에 대한 (예: Create, Read, Update assets) 리소스 및 연산 수행에 대한 접근 권한
이 튜토리얼은 몇 가지 간단한 조건의 접근 규칙을 실행해보기 위해 온라인 플레이그라운드를 사용합니다. 그렇게 하면 다양한 id로 샘플 네트워크와 상호작용할 수 있습니다. 이 다양한 id들은 결국에는 우리가 접근 제어를 적용하길 원하는 블록체인의 사용자입니다. 또, 참가자 역할이 어떻게 접근을 제어할 수 있는지도 살펴보고, 여러 id들을 지정된 참가자 역할 (예: Regulator)에 매핑할 수도 있습니다. 실제 블록체인 네트워크에서 Node JS 애플리케이션, CLI 혹은 실제 REST 연산 같은 모든 작업은 비즈니스 네트워크를 제어하는 ACLs의 대상으로 제어됩니다. 책임성은 id레벨로 볼 수 있습니다.
원하는 경우, 이 튜토리얼의 규칙을 이전에 개발한 하이퍼레저 컴포저에 적용할 수도 있습니다. developer tutorial에 사용된 샘플 Commodity Trading 비즈니스 네트워크를 배포하기만 하면 됩니다. 단, 앞에서 언급했듯이 global trading network ACL 규칙을 제거하는 것을 기억하세요. 그러면 해당 환경에서 작업할 준비가 된 것입니다.
Prerequisites
없음. 인터넷 연결만 되면 됨
Step One: Access the Online Playground and select your business nework
우리는 컴포저 샘플 네트워크 저장소에 있는 샘플 비즈니스 네트워크인 trade-network를 사용할 것입니다.
스크롤을 내려 trade-network 샘플을 클릭하세요. 위로 다시 스크롤하면 이름, 설명 및 네트워크 관리 카드 필드가 채워집니다.
Deploy 버튼이 활성화된 상태에서 비즈니스 네트워크를 배포하기 위해 Deploy 버튼을 클릭하세요. (이름이 trade-network가 맞는지 확인하세요)
마지막으로 'Connect Now'를 눌러 배포된 비즈니스 네트워크에 접속하세요. (default id는 우측 상단에 표시되어 있습니다)
'Trade Network' README 파일이 활성화되어 있어야 하며 왼쪽 열에는 비즈니스 네트워크의 구성 요소를 볼 수 있습니다. 이 중 하나는 리소스에 대한 액세스를 제어하는 ACL파일인 permissions.acl입니다. 기본적으로 샘플 비즈니스 네트워크는 모든 액세스 기능을 켜놓습니다. 물론, 궁극적으로 제품 스타일의 환경과는 다릅니다.
Create Trader Participants
화면 상단의 'Test' 탭을 클릭하세요. 이 탭은 샘플 Trader 참가자를 생성하기 위한 곳입니다.
왼쪽의 Trader를 클릭하세요. 그리고 아래와 같이 우측 상단 Create New Participant를 클릭해 아래와 같이 새로운 참가자를 생성하세요. - 아래 예제는 'TRADER1'을 나타냅니다.
'Test' 탭에서 왼쪽 'Commodity'를 클릭해 Commodity records를 생성합니다. 생성하는 Commodity의 소유자 (owner field) 는 위에서 생성한 'Trader' 참가자와 관련이 있습니다. owner이 relationship field임을 주목하세요.
우측 상단의 'Issue new ID'를 클릭하세요. 그러면 'Issue New Identity' 창이 뜰 것입니다.
ID Name 필드에 id로 tid1을 입력하세요. 이는 TRADER1의 id로 사용됩니다.
Participant 필드에 TRADER1을 입력해서 참가자를 검색하세요. 그리고 참가자의 풀네임을 클릭하세요.
'Create New'를 클릭해 계속진행합니다.
'Issue new ID' 단계 (위의 step 2-5)를 tid2-6까지 각 TRADER 참가자에 매핑하기 위해 반복하세요.
중요: 하이퍼레저 컴포저 기반 환경 (온라인 환경이 아닌) 에서 새로운 ID를 발급하는 경우 'Add to Wallet' 옵션을 사용해 발급된 id를 wallet에 모두 추가해야 합니다.
Add Commodity Trading network access control rules
배포한 'Commodity Trade network' 샘플 네트워크는 비즈니스 네트워크 참가자가 asset registry같은 레지스트리에 접근할 수 있게 하거나, 혹은 원장의 이력 레코드를 볼 수 있게 하는 것을 관리할 수 있도록 표준 시스템 및 네트워크 ACLs 규칙을 가지고 있습니다.
하지만 우리는 거래와 관련된 특정 접근 제어 규칙을 추가하려고 합니다. 먼저 달성하고자 하는 것을 정의하는 것으로 시작합니다. ACLs의 주요 특징은 명시적으로 허용하지 않는 한, 비즈니스 네트워크 내 리소스에 대한 기본적인 액세스는 참가자들에게 암묵적으로 거부되어 있는 것입니다.
permissions.acl파일의 현재 ACLs를 보면 파일에 특정 시스템 또는 관리가 규칙이 정의되어 있음을 알 수 있습니다. 이는 참가자가 컴포저 시스템 이력 레지스트리에 기록하기 같은 컴포저 시스템 연산을 사용할 수 있도록 하는 것입니다.
시작하기전, 우리는 permissions.acl 파일에 있는 하나의 'global' 규칙을 제거해야합니다. 왜냐하면 우리의 거래 네트워크는 일반적으로 샘플 네트워크처럼 사용되기 때문입니다. 아래는 제거할 규칙입니다.
rule Default {
description: "Allow all participants access to all resources"
participant: "ANY"
operation: ALL
resource: "org.example.trading.*"
action: ALLOW
}
permissions.acl 파일에서 위 내용을 지우고 시스템 또는 관리자 규칙은 내버려둡니다. 그리고나서 좌측 하단의 UPDATE 버튼을 클릭해 변경된 내용을 적용하세요.
우리 규칙 측면에서, 아래는 우리가 적용하고자 하는 정책입니다.
Everyday activities - rule objectives:
1a. Trader는 자신의 profile만을 조회하고 업데이트할 수 있습니다. (Participant record)
1b. Trader는 자신이 소유한 assets과 관련된 모든 연산에 접근할 수 있습니다. (Commodities)
'Trader' 유형의 참가자만이 Trade 트랜잭션을 제출할 수 있도록 제한합니다. (시간이 지나면 실제 운영중인 비즈니스 네트워크 모델에 정의된 여러 트랜잭션이 있을 수도 있으므로)
Historical records - rule objectives:
Trader은 트랜잭션 이력 중 그들이 생성한 것만을 볼 수 있습니다.
REG (Regulator) 유형의 참가자는 Traders (참가자들이 자신의 profile에서 작업하는 것과 마찬가지로) 에 의해 생성된 모든 트랜잭션이력을 볼 수 있습니다. 이와 관련해 2가지 규칙 (4a, 4b)가 있습니다
이 시점에서 org.example.trading (우리의 Commodity Trading 비즈니스 네트워크) 네임스페이스에는 비즈니스 네트워크 ACLs이 정의되어 있지 않습니다. (단지 시스템용만 존재) 그러므로 비즈니스 네트워크 내 리소스에 대한 접근은 초기값에 의해 명시적으로 거부되어 있습니다.
Rule 1a - Trader profile restriction rule
먼저, Trader가 자신의 기록만을 조회하고 업데이트할 수 있도록 하는 규칙입니다.
tid1 id로 전환하기 위해 우측 상단의 current identity를 클릭하고 ID Registry를 선택 후 tid1의 'use now'를 클릭하세요. 그런 다음 'Test' 탭으로 이동합니다.
현재 아무런 Trader 기록이 없는 것을 확인하세요.
우측 상단 'ID Registry'를 사용해 'admin' 사용자 id로 전환합니다. 그리고 'Define' 탭으로 가서 왼쪽 'Access Control' (permissions.acl)을 클릭하세요.
아래 규칙을 주석이 끝나고 코드의 제일 위에 붙여넣으세요. 붙여넣고 나면 3개의 'System' 및 'Network' 시스템 규칙이 있을 것입니다.
Rule:
rule R1a_TraderSeeUpdateThemselvesOnly {
description: "Trader can see and update their own record only"
participant(t): "org.example.trading.Trader"
operation: READ, UPDATE
resource(v): "org.example.trading.Trader"
condition: (v.getIdentifier() == t.getIdentifier())
action: ALLOW
}
좌측 하단의 UPDATE버튼을 눌러 비즈니스 네트워크를 업데이트 하세요.
이 규칙은 여기서는 플레이그라운드, 혹은 실제 애플리케이션의 current id에 매핑된 현재 Trader 참가자가 자신의 Trader 기록을 READ / UPDATE할 수 있도록 합니다.
TEST THE ACL: 우측 상단 'ID Registry'를 이용해 tid1의 id로 사용자를 전환하고 'Test' 탭을 클릭하세요. TRADER1의 기록만 있는지 확인하세요. 이 id로는 그것만 보여야 합니다.
Rule 1b - Trader Asset Ownership - allow update by owners only
기본적으로, Trader는 이전에 생성된 Commodity를 보거나 업데이트할 수 없습니다.
우리는 Trader가 소유자로 지정된 Commodity에 접근할 수 있는 규칙이 필요합니다.
tid1 id로 전환하기 위해 우측 상단의 current identity를 클릭하고 ID Registry를 선택 후 tid1의 'use now'를 클릭하세요. 그런 다음 'Test' 탭으로 이동합니다.
현재 아무런 Trader 기록이 없는 것을 확인하세요.
우측 상단 'ID Registry'를 사용해 'admin' 사용자 id로 전환합니다. 그리고 'Define' 탭으로 가서 왼쪽 'Access Control' (permissions.acl)을 클릭하세요.
아래 규칙을 위에서 붙여넣은 규칙들 위에 첫번째 줄에 붙여넣으세요.
Rule:
rule R1b_TraderSeeTheirCommodities {
description: "Trader can see/work with their own Commodities"
participant(t): "org.example.trading.Trader"
operation: ALL
resource(c): "org.example.trading.Commodity"
condition: (c.owner.getIdentifier() == t.getIdentifier())
action: ALLOW
}
좌측 하단의 UPDATE버튼을 눌러 비즈니스 네트워크를 업데이트 하세요.
이 규칙은 현재 Trader 참가자가 자신이 소유한 Commodity 리소스에 대한 모든 연산에 접근할 수 있도록 합니다.
TEST THE ACL: 우측 상단 'ID Registry'를 이용해 tid1의 id로 사용자를 전환하고 'Test' 탭을 클릭하세요. TRADER1이 소유한 Commodity만 있는지 확인하세요. 이 id로는 그것만 보여야 합니다.
명시적으로 Trader인 TRADER1은 이 시점에 다른 Trader의 자산 (Commodity) 을 조회하거나 업데이트할 수 없습니다. 우리는 이런 기능을 위한 규칙은 필요하지 않습니다. 하지만 실제로는 특정 Trader가 소유자가 아니더라도 다른 Commodity를 볼 수 있는 것을 허용하는 비즈니스 정책이 있을 수도 있습니다.
Rule 2 - Restrictive rule: Only 'Trader' participants can submit 'Trade' smare contract transactions
기본적으로, Trader는 자신이 소유한 Commodity를 업데이트 하기 위한 Trade 트랜잭션 (모델에 정의되어 있고, Script 파일에 스마트 컨트랙트 로직이 쓰여 있는) 을 제출할 수 없습니다.
우리는 Trader가 자신이 'owner'로 지정된 Trade 트랜잭션을 제출할 수 있도록 하는 규칙이 필요합니다. Trade 트랜잭션은 현재 소유자가 Commodity의 소유자를 다른 Trader로 지정할 수 있게 합니다.
tid1 id로 전환하기 위해 우측 상단의 current identity를 클릭하고 ID Registry를 선택 후 tid1의 'use now'를 클릭하세요. 그런 다음 'Test' 탭으로 이동합니다.
아래 트랜잭션을 복사하고 붙여넣어 트랜잭션을 제출한 다음 현재는 Commodity의 소유자를 변경하기 위해 Trade 트랜잭션을 제출할 수 없는 것을 확인하세요. 아마 트랜잭션을 제출하기 위한 CREATE를 할 수 없다는 메세지를 받을 것입니다.
b. 왼쪽에 있는 'All Transactions'로 이동하여 트랜잭션이 제출되었는지 확인하세요. Historian의 첫 번째 레코드는 TRADE 트랜잭션이 전송되었음을 확인합니다. 참가자 TRADER1은 더이상 commodity의 소유자가 아닙니다. 반면 tid2의 id로 사용자를 변경하면 TRADER2가 소유하고 있는 두 개의 Commodity가 보일 것입니다.
Rule 3 - Enabling rule: Allow Traders to see their own historical records only
기본적으로, 시스템 ACLs (Historial records 레지스트리 일부인) 때문에 각 Trader (예: tid1, tid2 혹은 이와 관련된 id들) 은 모든 트랜잭션의 이력을 볼 수 있습니다. 예시로는 admin에 의해 수행되는 UpgradeBusinessNetwork가 있습니다.
우리는 Trader가 그들이 Historian에 제출한 트랜잭션만 볼 수 있게 권한을 낮춰야 합니다.
tid3 id로 전환하기 위해 우측 상단의 current identity를 클릭하고 ID Registry를 선택 후 tid3의 'use now'를 클릭하세요. 그런 다음 'Test' 탭으로 이동합니다.
현재 'system'과 관련된 트랜잭션 활동 및 다른 trdaer (TRADER1 and TRADER2) 도 볼 수 있는지 확인하세요.
우측 상단 'ID Registry'를 사용해 'admin' 사용자 id로 전환합니다. 그리고 'Define' 탭으로 가서 왼쪽 'Access Control' (permissions.acl)을 클릭하세요.
아래 규칙을 위에서 붙여넣은 규칙들 위에 첫번째 줄에 붙여넣으세요.
Rule:
rule R3_TradersSeeOwnHistoryOnly {
description: "Traders should be able to see the history of their own transactions only"
participant(t): "org.example.trading.Trader"
operation: READ
resource(v): "org.hyperledger.composer.system.HistorianRecord"
condition: (v.participantInvoking.getIdentifier() != t.getIdentifier())
action: DENY
}
이 규칙은 현재 Trader 참가자들이 자신이 블록체인 호출한 트랜잭션만 볼 수 있게 제한합니다.
좌측 하단의 UPDATE버튼을 눌러 비즈니스 네트워크를 업데이트 하세요.
TEST THE ACL:
a. 우측 상단 'ID Registry'를 이용해 tid3의 id로 사용자를 전환하세요. 'Identity Activation' 유형의 엔트리만 볼 수 있고 TRADER1과 TRADER2와 관련해서 제출된 트랜잭션 이력은 아무 것도 없을 것입니다. 이 것이 우리가 기대한 결과입니다.
b. 다음으로 tid1의 id로 사용자를 전환하세요. tid1과 관련된 트랜잭션 이력 (이전에 제출한 'TRADE' 트랜잭션 포함) 만 볼 수 있을 것입니다. 특히 Commodity 'CC' 소유주를 TRADER2로 이동한 것. (반대로 tid2, 전송받은 사람은 tid1에 의해 제출된 'TRADE' 트랜잭션의 이력을 볼 수 없고, 전송받은 Commodity 자산만 볼 수 있습니다.)
Rule 4a & 4b - Enabling rule: Allow Regulators to see their own profile and all historical activity, including Trades
이 규칙은 regulator가 비즈니스 네트워크에서 수행된 과거 거래를 검토/감시하는 것을 나타냅니다. 참가자 혹은 자산 자체에 대한 접근이 반드시 필요한 것은 아니며, 오히려 이와 관련된 활동을 필요로 합니다. (유즈케이스나 정책에 따라서)
우리는 아직 'Commodity Trading' 비즈니스 네트워크 모델에 'Regulator'를 갖고 있지 않습니다. 그래서 우리는 별도의 참가자 유형으로 이것을 추가한 다음, 누군가 regulator 역할을 할 수 있도록 만들어 hisotical records에 접근할 수 있게 할 것입니다. 하나 이상의 ID를 참가자 instance에 매핑할 수 있으며, Regulator가 그것으 ㄹ보여주는 좋은 예입니다.
admin id로 사용자를 전환하고 'Define' 탭을 클릭하세요.
모델 파일을 클릭하고 새로운 참가자 유형을 추가하세요. (Trader 참가자 아래에 추가하세요.)
Model:
participant Regulator identified by regId {
o String regId
o String firstName
o String lastName
}
ID registry에서 ID 101의 id를 생성하고 위에서 생성한 regulator 참가자인 'Reg101'에 매핑시키세요.
이 시점에서 Regulator는 시스템 ACL 규칙이 먼저 정의되었기 때문에 컴포저의 Historian에 있는 시스템 트랜잭션의 이력을 확인할 수 있습니다. 하지만 자신의 참가자 profile은 확인할 수 없습니다.
아래 규칙을 추가하세요.
Rule:
rule R4a_RegulatorSeeThemselves {
description: "Regulators can see and update their own record"
participant: "org.example.trading.Regulator"
operation: READ, UPDATE
resource: "org.example.trading.Regulator"
action: ALLOW
}
이 규칙은 단지 Regulator 참가자가 자신의 profile 기록을 업데이트 할 수 있게 하는 것입니다. (업데이트하길 원한다면 위에서 비슷한 것을 했으므로 테스트해볼수도 있습니다.)
비즈니스 네트워크에 새 규칙을 업데이트하기 위해 좌측 하단의 UPDATE 버튼을 클릭하세요.
Id Registry에서 Regulator id인 101로 사용자를 변경하고 'Use Now'를 클릭하세요.
이전 트랜잭션을 보여주는 Historical records를 볼 수 있는지 확인하세요. 그리고 AddAsset이나 AddParticipant같은 시스템 유형의 트랜잭션 활동에 대한 'view record'를 클릭하세요. Regulator역할을 가진 참가자라면 이 활동을 수행할 수 있습니다.
TRADE 트랜잭션에 대한 'view record'를 클릭하세요. 아무 일도 일어나지 않을 것입니다. regulator는 현재 ACLs를 통해 트랜잭션 키록을 볼 수 있는 권한이 없습니다.
규칙 변경을 위해 admin 사용자 id로 전환합니다.
아래 Regulator 권한 규칙을 permission.acl 파일 제일 위에 추가하세요.
Rule:
rule R4b_RegTransView {
description: "Grant Regulator full access to Trade Transactions"
participant: "org.example.trading.Regulator"
operation: ALL
resource: "org.example.trading.Trade"
action: ALLOW
}
좌측 하단의 UPDATE버튼을 눌러 비즈니스 네트워크를 업데이트 하세요.
이 규칙은 Regulator가 Trader 트랜잭션 리소스에 접근할 수 있게 해줍니다. 즉 Historian의 'view record'에서 Trade 트랜잭션을 볼 수 있습니다.
이 규칙은 또한 regulator에 매핑되거나 Regulator 참가자 registry에 있는 모든 id에 적용됩니다.
TEST THE ACL: trade 트랜잭션으로 다시 돌아가서 view the record를 수행할 수 있는지 확인하세요.
이 튜토리얼에서, 우리는 ACL 규칙을 순차적으로 생성하는 방법을 해보았으며, 예제인 Commodity Trading 비즈니스 네트워크의 참가자에게 부여되어야 하는 필수적인 접근 제어만 허용햇씁니다. 우리는 ACL 규칙이 참가자 (혹은 참가자 역할)에 적용되는 리소스에 대한 권한 부여 및 제어를 제공하는 방법을 살펴보았습니다. ACL은 리소스를 생성, 삭제 또는 업데이트하거나 트랜잭션을 실행할 수 있는지 여부에 관계없이 리소스 및 트랜잭션에 대한 접근 제어를 관리합니다. 우리는 또한 Access Control Language와 규칙에 대한 권한도 갖고 있습니다. '누가' '무엇을' 원장에서 할 수 있는지 능력을 가지고 있는지에 대한 조건이나 기준을 정의합니다.
하이퍼레저 컴포저에는 비즈니스 네트워크에서 다른 비즈니스 네트워크게 기록된 자산, 참가자 혹은 트랜잭션에 액세스할 수 있는 기능이 포함되어 있습니다.
이 튜토리얼은 다른 비즈니스 네트워크에서 하이퍼레저 컴포터 비즈니스 네트워크를 호출하기 위해 비즈니스 네트워크 개발자가 수행해야하는 단계를 보여줍니다. 이 튜토리얼에서는 동일한 비즈니스 네트워크를 두 번 배포합니다. 여기서 두 개의 비즈니스 네트워크는 동일한 채널에 있지만, 서로 다른 채널에 있을 수도 있습니다. 현재 튜토리얼에서 사용하는 비즈니스 네트워크는 developer tutorial에 있는 tutorial network입니다. 여기서 사용할 두 개의 비즈니스 네트워크는 각각 A와 B라고 부릅니다.
이 튜토리얼은 하이퍼레저 패브릭 기반의 여러 조직 블록체인 네트워크를 구성하는데 필요한 단계에 대해 설명합니다. 두 개의 조직으로 구성된 블록체인 네트워크는 하이퍼레저 패브릭에서 제공하는 샘플 네트워크를 기반으로 합니다. 또한, 필요한 보안 artifact를 생성하고 두 조직 간 네트워크를 보호하는 단계에 대해 설명합니다.
블록체인 네트워크가 구성되면, 우리는 비즈니스 네트워크가 어떻게 배포되는지 확인할 수 있습니다. (예: 샘플 네트워크의 Commodity 거래 비즈니스 네트워크) 이 비즈니스 네트워크는 체인코드 컨테이너를 운영하고 양 쪽 기관의 분산 원장에서 인스턴스화 됩니다. 그리고나서 우리는 각 조직의 신원 제공자로 생성된 서로 다른 참가자 및 신원 간 분산원장에서의 상호작용을 확인합니다.
먼저 첨부된 단일 기관 튜토리얼을 먼저 해보는 것이 좋습니다. 이 튜토리얼에서는 블록체인 네트워크를 단일 조직용 하이퍼레저 패브릭 객체에 배포하는 것을 먼저 보여주고 몇 가지 개념을 자세히 설명합니다.
이 튜토리얼의 하이퍼레저 패브릭 블록체인 네트워크 ( 두 개의 조직용) 는 docker 컨테이너를 사용해서 구성되며, 두 조직의 패브릭 네트워크는 동일한 머신에 있습니다. 현실 세계에서는 두 조직은 분리된 IP 네트워크나 도메인 혹은 secure 클라우드 환경에 있을 것입니다.
이 튜토리얼은 편의를 위해 색깔로 단계를 구분했습니다. '어느 조직'이 특정 단계를 따라야하는지, 혹은 두 조직 모두 필요한 단계일 수도 있습니다.
첫 번째 종류는 양 쪽 조직 모두 따라하는 단계입니다.
Org1은 Alice라 불리며 초록색 블록입니다.
Org2는 Bob이라 불리며 보라색 블록입니다.
이 단계는 스스로 따라할 수도 있고 친구 혹은 동료와 함께 따라할 수도 있습니다.
Prerequisites
이전에 컴포저 개발 환경을 설치했다면, 먼저 개발 환경에서 제공하는 하이퍼레저 패브릭 컨테이너를 해제해야 합니다.
cd ~/fabric-dev-servers
export FABRIC_VERSION=hlfv12
./stopFabric.sh
./teardownFabric.sh
다음으로는 아래 명령어를 사용해 GitHub Fabric Samples repository를 복사합니다. (중요: Fabric site에 있는 샘플을 사용하지 마세요, 이 튜토리얼에서 필요한 몇몇이 누락되어 있습니다.)
우리는 여러 조직용 튜토리얼을 하기 위해 Building Your First Network 패브릭 샘플을 사용합니다. 우리는 이 하이퍼레저 패브릭 네트워크를 'BYFN' (Building Your First Network) 네트워크라고 부를 것입니다. 조직을 별도의 물리적 컴퓨터 또는 다른 IP 네트워크에서 실행되는 별도의 가상 컴퓨터로 분할하려는 경우 이 튜토리얼의 범위를 벗어납니다.
Step One: Starting a Hyperledger Fabric network
이 튜토리얼을 따라하기 위해서는 새로운 하이퍼레저 패브릭 네트워크를 시작해야 합니다. 이 튜토리얼은 하이퍼레저 패브릭의 Building Your First Network tutorial에서 제공된 하이퍼레저 패브릭 네트워크를 사용할 것입니다.
1. fabric-samples 디렉토리로 이동하세요.
cd fabric-samples
2. 아래 커맨드를 사용해 cryptogen을 포함한 플랫폼 바이너리파일을 다운받으세요. (bash command를 위해 3 개의 파라미터가 필요합니다.)
("error: pathspec v1.x.x did not match" 메시지는 무시해도 좋습니다.)
3. 우리는 앞서 복사해둔 Git repo의 multi-org 브랜치를 사용해야 합니다.
git checkout multi-org
4. first-network 디렉토리로 이동하세요.
cd first-network
5. 다음으로 BYFN 네트워크를 시작합니다. 우리는 world state 데이터베이스로 CouchDB를 사용하고 있기 때문에 (byfn.sh 스크립트에) 부가적인 플래그가 필요합니다. (패브릭 BYFN 페이지에 나온 것과 약간 다름) 또, 우리는 각 조직 별 CA를 시작해야 합니다.
6. first-network 폴더에서 아래 커맨드를 순서대로 실행하세요.
./byfn.sh -m generate
./byfn.sh -m up -s couchdb -a
명령어가 성공적으로 동작하면 첫 번째 커맨드는 패브릭 네트워크 / security artifacts를 생성합니다. 두 번째 커맨드를 통해 BYFN 네트워크가 시작되고, 아래와 같이 출력되는지 확인하세요.
하지만, 다른 유형의 에러는 더 이전 버전의 하이퍼레저 컴포저에 카드가 저장되어 있을수도 있습니다. 그러므로 HOME 디렉토리에서 아래와 같은 명령어를 실행해 파일 시스템 내 카드 저장소를 삭제해야 합니다.
rm -fr $HOME/.composer
Step Two: Exploring the Hyperledger Fabric network
이 단계에서는 BFYN 네트워크 구성 및 요소들을 살펴볼 것입니다. 구성의 세부 요소들은 아래 단계를 완료해야 합니다.
Organizations
BYFN 네트워크는 Org1과 Org2, 두 개의 조직으로 구성되어 있습니다. Org1은 org1.example.com이라는 도메인 이름을 사용합니다. Org1의 MSP는 Org1MSP라고 불립니다. Org2는 org2.example.com이라는 도메인 이름을 사용하고 Org2MSP라는 MSP를 갖고 있습니다. 이 튜토리얼에서는 Org1과 Org2가 상호작용할 수 있는 블록체인 비즈니스 네트워크를 배포합니다.
Network components
하이퍼레저 패브릭 네트워크는 몇몇 구성요소로 이뤄져 있습니다.
- Org1의 두 개의 피어 노드: peer0.org1.example.com, peer1.org1.example.com
> request port (peer0) : 7051
> event hub port (peer0) : 7053
> request port (peer1) : 8051
> event hub port (peer1) : 8053
- Org1의 단일 CA: ca.org1.example.com
> CA port : 7054
- Org2의 두 개의 피어 노드: peer0.org2.example.com, peer1.org1.example.com
> request port (peer0) : 9051
> event hub port (peer0) : 9053
> request port (peer1) : 10051
> event hub port (peer1) : 10053
- Org2의 단일 CA: ca.org2.example.com
> CA port : 8054
- 단일 orderer 노드: orderer.example.com
> orderer port : 7050
위 구성요소들은 Docker 컨테이너 내에서 동작합니다. 하이퍼레저 컴포저가 Docker 컨테이너에서 동작할 때 위의 이름 (예: peer0.org1.example.com)은 하이퍼레저 패브릭 네트워크와 상호작용하는데 사용될 수 있습니다.
이 튜토리얼에서는 하이퍼레저 컴포저 커맨드를 Docker network 내에서 실행하기 보다는 host machine에서 실행합니다. 이는 하이퍼레저 컴포터 커맨드가 localhost를 호스트 이름으로 사용하고 공개된 컨테이너 포트를 사용해 하이퍼레저 패브릭 네트워크와 상호작용한다는 것을 의미합니다.
모든 네트워크 구성요소들은 통신 암호화에 TLS를 사용하여 보호됩니다. 해당 네트워크 구성요소에 연결하려면 모든 네트워크 구성요소에 대한 CA 인증서가 필요합니다. CA 인증서는 byfn.sh 스크립트가 들어있는 폴더에서 찾을 수 있습니다.
/tmp/composer/ca-orderer.txt파일 내용을 복사하고 INSERT_ORDERER_CA_CERT 자리에 넣으세요. 다시 한 번 언급하지만 모두 동일한 라인에 있어야 합니다.
완료되면 이 파일을 /tmp/composer/byfn-network.json 파일에 저장하세요.
이 connectino profile은 이제 네트워크의 일부분인 모든 피어, orderer, 인증서를 포함한 패브릭 네트워크 구성을 나타냅니다. 이 파일은 네트워크에 참여하는 모든 조직을 나타내고 이 네트워크에 있는 모든 채널을 정의합니다. 하이퍼레저 컴포저는 단일 채널과 상호작용할 수 있기 때문에 하나의 채널만이 정의되어 있습니다.
Step Three: Customizing the connection profile for Org1
이 단계는 alice가 속한 조직을 지정하는 것입니다. 타임아웃이 있는 클라이언트 섹션에서는 다음 블록을 위에서 작성한 /tmp/composer/byfn-network.json 이라는 connection profile 파일에 추가합니다. 이는 version 속성과 channel 속성 사이에 있습니다. 완료되면 /tmp/composer/org1/byfn-network-org1.json이라는 새로운 파일로 저장하세요.
먼저 사용자의 인증서 파일을 위치시켜야 합니다. 인증서는 신원확인의 공개된 부분입니다. 인증서 파일은 signcerts 하위 디렉토리에서 찾을 수 있으며 Admin@org1.example.com-cert.pem이라는 파일입니다.
다음으로 사용자의 개인키 파일을 위치시켜야 합니다. 개인키는 이 신원을 통해 트랜잭션을 인증할 때 사용됩니다. 개인 키 파일은 keystore 하위 디렉토리에서 찾을 수 있습니다. 개인 키 파일은 16진수 문자열로 접미어는 _sk입니다. 예를 들면 78f2139bfcfc0edc7ada0801650ed785a11cfcdef3f9c36f3c8ca2ebfa00a59c_sk와 같이 생겼습니다. 이 이름은 구성이 생성될 때마다 매번 바뀌므로 아래의 와일드 카드를 사용하세요.
이 두 파일 경로를 모두 기억하세요, 혹은 step 3에서 생성한 connection profile 파일인 /tmp/composer/orgl/byfn-network-org1.json 파일과 동일한 폴더에 복사해두세요. 이 파일은 다음 단계에서 필요합니다.
먼저 사용자의 인증서 파일을 위치시켜야 합니다. 인증서는 신원확인의 공개된 부분입니다. 인증서 파일은 signcerts 하위 디렉토리에서 찾을 수 있으며 Admin@org2.example.com-cert.pem이라는 파일입니다.
다음으로 사용자의 개인키 파일을 위치시켜야 합니다. 개인키는 이 신원을 통해 트랜잭션을 인증할 때 사용됩니다. 개인 키 파일은 keystore 하위 디렉토리에서 찾을 수 있습니다. 개인 키 파일은 16진수 문자열로 접미어는 _sk입니다. 예를 들면 d4889cb2a32e167bf7aeced872a214673ee5976b63a94a6a4e61c135ca2f2dbb_sk와 같이 생겼습니다. 이 이름은 구성이 생성될 때마다 매번 바뀌므로 아래의 와일드 카드를 사용하세요.
이 두 파일 경로를 모두 기억하세요, 혹은 step 3에서 생성한 connection profile 파일인 /tmp/composer/orgl/byfn-network-org2.json 파일과 동일한 폴더에 복사해두세요. 이 파일은 다음 단계에서 필요합니다.
위에서 볼 수 있듯이, 여러 조직 환경을 테스트하기 위해 trade-network라 불리는 하이퍼레저 컴포저 비스니스 네트워크를 사용합니다. 테스트를 하려면 trade-network.bna (샘플 네트워크에서 만들어진 비즈니스 네트워크 아카이브) 파일이 필요합니다. 이 파일을 가지고 있지 않다면 https://composer-playground.mybluemix.net/ 옆의 링크로 이동해 온라인 플레이그라운드에서 trade-network 샘플을 배포한 다음 admin으로 비즈니스 네트워크에 connect 하세요. 왼쪽 하단 버전을 0.1.14로 변경하고 현재 폴더에 trade-network.bna파일을 export하세요. 비즈니스 네트워크는 package.json 파일에 version 속성을 가지고 있습니다. 이 버전은 비즈니스 네트워크가 step 17에서 composer start 커맨드를 사용해 시작될 때 지정되어야 합니다. trade-network 샘플 네트워크를 사용하고 있다면 버전은 0.1.14입니다. (주의: 컴포저 튜토리얼 네트워크 tutorial-network같은 다른 네트워크를 비즈니스 네트워크로 사용하려 한다면 위의 network install 커맨드에 해당 파일을 이 튜토리얼의 비즈니스 네트워크 아카이브로 지정하고 버전 또한 알맞게 지정해야 합니다.)
network install 커맨드의 유용한 기능은 설치된 비즈니스 네트워크 이름과 버전 번호를 출력한다는 것입니다. 이는 아래 step 17에서 사용할 수 있습니다.
Step Twelve: Installing the business network onto the Hyperledger Fabric peer nodes for Org2
composer network install 명령어를 사용해 Step 4에서 connection profile 파일에 정의한 Org2의 하이퍼레저 패브릭 피어 노드에 비즈니스 네트워크를 설치하세요.
Step Thirteen: Defining the endorsement policy for the business network
운영중인 비즈니스 네트워크는 인증 정책을 가지고 있습니다. 이 정책은 트랜잭션이 블록체인에 커밋되기 전에 어느 조직이 트랜잭션을 검증할지를 결정하는 규칙을 정의합니다. 기본적으로 비즈니스 네트워크는 블록체인에 트랜잭션이 커밋되기 전 하나의 기관이 트랜잭션을 검증하도록 배포됩니다.
실제 블록체인 비즈니스 네트워크에서는 여러 기관들이 블록체인에 트랜잭션이 커밋되기 전 검증하기를 원합니다. 그리고 기본 검증 정책은 여기에 적합하지 못합니다. 그래서 비즈니스 네트워크를 시작할 때 검증 정책을 커스텀할 수 있습니다.
검증 정책과 관련해서는 하이퍼레저 패브릭 docs 내 아래 링크를 참고하면 더 상세한 정보를 알 수 있습니다.
방금 생성한 검증정책은 Org1과 Org2 모두 블록체인에 트랜잭션을 커밋하기 전 비즈니스 네트워크 내 트랜잭션을 검증해야만 합니다. Org1 혹은 Org2가 트랜잭션을 검증하지 않거나, 트랜잭션 결과에 동의하지 않으면 해당 트랜잭션은 비즈니스 네트워크에 의해 거절당합니다.
Step Fourteen: Understanding and selecting the business network administrators
비즈니스 네트워크가 시작되면, 초기 참가자 집단으로 구성됩니다. 이 참가자들은 비즈니스 네트워크를 시작하고 다른 참가자들을 비즈니스 네트워크에 초대하는 역할을 합니다. 하이퍼레저 컴포저에서 우리는 이 초기 참가자들을 비즈니스 네트워크 관리자라고 부릅니다.
여기서 Org1과 Org2는 동일한 권한을 갖고 있습니다. 각 조직은 비즈니스 네트워크에 관리자를 제공하고 , 해당 관리자들은 각 조직에 다른 참가자들을 초대합니다. Org1의 비즈니스 네트워크 관리자는 Alice이고 Org2의 관리자는 Bob입니다.
비즈니스 네트워크가 시작되면 모든 비즈니스 네트워크 관리자의 인증서 (신원확인의 공개파트) 는 비즈니스 네트워크를 시작하는 조직에 제출되어야 합니다. 비즈니스 네트워크가 시작되면, 모든 관리자들은 비즈니스 네트워크와 상호작용하는데 그들의 신원을 사용할 수 있습니다.
이 커맨드의 -u admin 과 -s adminpw 옵션은 하이퍼레저 패브릭 CA에 등록된 기본 사용자입니다.
인증서는 현재 작업 디렉토리의 alice폴더에 위치할 것입니다. 3개의 인증서가 생성되지만 2가지가 중요합니다. 이 두 가지는 admin-pub.pem이라는 공개키를 포함한 인증서와 admin-priv.pem이라는 개인키 파일입니다. admin-pub.pem파일만이 다른 조직과 공유되어야 합니다. admin-priv.pem파일은 비밀로 유지되어야 하며 조직을 대표해 트랜잭션을 인증하는데 사용됩니다.
Step Sixteen: Retrieving business network administrator certificates for Org2
composer identity request 커맨드를 사용해 Org2의 비즈니스 네트워크 관리자로 사용할 Alice의 인증서를 검색하세요.
이 커맨드의 -u admin 과 -s adminpw 옵션은 하이퍼레저 패브릭 CA에 등록된 기본 사용자입니다.
인증서는 현재 작업 디렉토리의 bob폴더에 위치할 것입니다. 3개의 인증서가 생성되지만 2가지가 중요합니다. 이 두 가지는 admin-pub.pem이라는 공개키를 포함한 인증서와 admin-priv.pem이라는 개인키 파일입니다. admin-pub.pem파일만이 다른 조직과 공유되어야 합니다. admin-priv.pem파일은 비밀로 유지되어야 하며 조직을 대표해 트랜잭션을 인증하는데 사용됩니다.
Step Seventeen: Starting the business networ
composer network start 커맨드를 사용해 비즈니스 네트워크를 시작하세요. 이 동작은 Org1에서만 수행합니다. 이 명령어는 step 13에서 생성한 /tmp/composer/endorsement-policy.json 파일을 사용합니다. 그리고 step 15, 16에서 Alice와 Bob에 의해 생성된 admin-pub.pem 파일을 사용합니다. 그러므로 위 모든 파일에 아래 명령어로 접근할 수 있어야 합니다.
composer network start -c PeerAdmin@byfn-network-org1 -n trade-network -V 0.1.14 -o endorsementPolicyFile=/tmp/composer/endorsement-policy.json -A alice -C alice/admin-pub.pem -A bob -C bob/admin-pub.pem
위 명령어가 수행되면, 비즈니스 네트워크는 시작됩니다. Alice와 Bob모두 비즈니스 네트워크에 접근해 시작할 수 있고 각 조직에 다른 참가자들을 초대할 수 있습니다. 하지만, Alice와 Bob은 이전 단계에서 생성한 인증서로 비즈니스 네트워크 카드를 생성해야 비즈니스 네트워크에 접근할 수 있습니다.
Step Eighteen: Creating a business network card to access the business network as Org1
composer card create 커맨드를 사용해 Org1의 비즈니스 네트워크 관리자인 Alice의 비즈니스 네트워크 카드를 생성하세요. 그러면 비즈니스 네트워크에 접근할 수 있습니다.
composer card import 커맨드를 사용해 방금 생성한 비즈니스 네트워크 카드를 import 하세요.
composer card import -f alice@trade-network.card
composer network ping 커맨드를 사용해 블록체인 비즈니스 네트워크 접속을 테스트하세요.
composer network ping -c alice@trade-network
위 커맨드가 성공적으로 동작하면, org.hyperledger.composer.system.NetworkAdmin#alice와 같은 참가자 신분을 확인할 수 있을 것입니다. 이제 블록체인 비즈니스 네트워크와 상호작용하고 다른 참가자들을 초대하는데 이 비즈니스 네트워크 카드를 사용할 수 있습니다.
참가자를 생성하고 해당 참가자에 매핑된 ID를 발급하고 해당 ID로 블록체인 네트워크에서 자산을 생성할 수 있습니다.
마지막으로 이전에 생성한 Commodity 자산의 소유자를 변경하는 트랜잭션을 제출합니다. 우리는 자산 소유자인 Jon Doe로 트랜잭션을 제출하고 Dave Lowe에게 전달할 것입니다. 그리고나서 dlowe라고 매핑된 Org2의 trader 참가자로 소유자가 변경되었는지 확인할 것입니다. 아래 단계를 따라 수행하세요.
개발 환경에서는 블록체인 비즈니스 네트워크를 배포하는데 필요한 하이퍼레저 컴포저 구성과 함께 하이퍼레터 패브릭 단일 조직, 단일 피어 네트워크 (fabric-dev-servers)만 생성됩니다.
이 튜토리얼에서는 필요한 조직을 생성하는 방법을 포함해 관리자가 단일 조직에 대해 하이퍼레저 패브릭 객체에 블록체인 비즈니스 네트워크를 배포하기 위해 수행해야 하는 단계를 보여줍니다. 이후 튜토리얼에서는 블록체인 비즈니스 네트워크를 여러 조직의 하이퍼레저 패브릭 객체에 배포하는 방법을 보여줍니다.
하이퍼레저 패브릭 docs를 읽으면 이러한 구성 툴에 대한 추가 정보, 수행 방법 및 사용법에 대해 알 수 있습니다.
Organizations
간단한 하이퍼레저 패브릭 네트워크는 Org1이라는 단일 조직으로 구성됩니다. 조직은 org1.example.com이라는 도메인 이름을 사용합니다. 또한, 이 조직의 Membership Services Provider (MSP)는 Org1MSP라고 합니다. 이 튜토리얼에서는 Org1만 상호작용할 수 있는 블록체인 비즈니스 네트워크를 배포합니다.
Network components
하이퍼레저 패브릭은 몇몇 요소로 구성되어 있습니다.
- peer0.org1.example.com: Org1의 단일 피어 노드
> request port : 7051
> event hub port : 7053
- ca.org1.example.com: 단일 인증 권한
> CA port : 7054
- orderer.example.com
> orderer port : 7050
하이퍼레저 패브릭 네트워크 구성요소는 Docker 컨테이너에서 실행됩니다. Docker 컨테이너에서 하이퍼레저 컴포저를 실행하는 경우 위의 이름 (예: peer0.org1.example.com)을 사용하여 하이퍼레저 패브릭 네트워크와 상호작용할 수 있습니다.
이 튜토리얼에서는 Docker 네트워크 내부가 아닌 Docker 호스트 컴퓨터에서 하이퍼레저 컴포저 명령을 실행합니다. 즉, 하이퍼레저 컴포터 명령은 localhost를 호스트 이름으로 사용하고 노출된 컨테이터 포트를 사용해 하이퍼레저 패브릭 네트워크와 상호작용해야 합니다.
Users
조직 Org1은 Admin@org1.example.com이라는 사용자로 구성됩니다. 이 사용자는 관리자입니다. 조직의 관리자는 조직의 피어들에게 블록체인 비즈니스 네트워크의 코드를 설치할 수 있는 권한이 있으며, 구성에 따라 블록체인 비즈니스 네트워크를 시작할 수 있는 권한을 가질 수도 있습니다. 이 튜토리얼에서는 Admin@org1.example.com 사용자로 블록체인 비즈니스 네트워크를 배포합니다.
Admin@org1.example.com 사용자는 아래 디렉토리에 저장된 일력의 인증서와 개인 키 파일을 가지고 있습니다.
관리자 외에도 Org1의 CA(Certificate Authority)가 기본 사용자로 등록되어 있습니다. 이 기본 사용자는 등록 ID가 admin이고 패스워드는 adminpw입니다. 하지만, 이 사용자에게는 블록체인 비즈니스 네트워크를 배포할 수 있는 권한이 없습니다.
Channel
마지막으로, composerchannel이라는 채널이 생성되었습니다. 피어 노드인 peer0.org1.example.com은 이 채널에 조인되었습니다. 하이퍼레저 컴포저 블록체인 비즈니스 네트워크는 기존 채널에만 배포할 수 있지만, 하이퍼레저 패브릭 docs를 따라 추가 채널을 만들 수도 있습니다.
Step Three: Building a connection profile
Connection profile은 하이퍼레저 패브릭 네트워크를 찾고 연결하는데 필요한 모든 정보 (예: 모든 하이퍼레저 패브릭 네트워크 구성 요소의 호스트 이름 및 포트)를 지정합니다. 이 단계에서는 하이퍼레저 컴포저가 하이퍼레저 패브릭 네트워크에 연결하는데 사용할 connection profile을 생성합니다.
1. connection.json이라는 connection profile 파일을 생성하세요.
2. connection profile의 name, version, x-type속성을 connection.json파일 가장 위에 아래 세 줄을 추가하여 지정하세요.
여기서 우리는 composerchannel 채널과 해당 채널의 일부인 orderers, peers를 정의합니다. 또한 피어가 이 채널에서 수행할 역할도 지정합니다. 이 튜토리얼에서 우리는 이전에 정의된 레이블을 사용해 단일 orderer과 peer를 추가했습니다. 피어는 비즈니스 네트워크를 설치하므로 체인코드 쿼리를 처리하고 이벤트를 생성할 수 있는 트랜잭션 인증자가 됩니다. 블록체인 비즈니스 네트워크는 모든 지정된 피어 노드에 배포될 것입니다. 블록체인 비즈니스 네트워크가 배포되면, 지정된 피어 노드들은 블록체인 비즈니스 네트워크에 쿼리하고, 트랜잭션을 보증하고, 이벤트를 구독하는 데 사용됩니다.
8. 마지막 섹션은 클라이언트 섹션입니다. 이것은 클라이언트 애플리케이션 (하이퍼레저 컴포저 같은)에서 상호작용할 때 어떤 조직을 나타내는지와 몇 가지 추가 선택적인 타임아웃 등을 알기 위해 사용됩니다.
먼저 이 사용자를 위한 인증서 파일을 위치시켜야 합니다. 인증서는 신원확인의 공개파트입니다. 인증서 파일은 signcerts의 하위 폴더에서 찾을 수 있으며 Admin@org1.example.com-cert.pem이라는 파일입니다. 이 파일의 내용을 보면 아래와 같이 PEM 인코딩 된 인증서를 확인할 수 있습니다.
다음으로는 이 사용자의 개인 키 파일을 위치시켜야 합니다. 개인 키는 이 신원으로 트랜잭션을 인증할 때 사용됩니다. 개인 키 파일은 keystore 하위 디렉토리에서 찾을 수 있습니다. 개인 키 파일의 이름은 긴 16진수 문자열로, 접미어는 _sk입니다. (예: 114aab0e76bf0c78308f89efc4b8c9423e31568da0c340ca187a9b17aa9a4457_sk) 이름은 구성이 생성될 때마다 변경됩니다. 이 파일의 내용을 보면 다음과 유사한 PEM으로 인코딩 된 개인 키를 확인할 수 있습니다.
이 옵션은 step 4에서 위치시킨 Admin@org1.example.com 사용자의 개인 키 파일 경로를 나타냅니다.
-r PeerAdmin -r ChannelAdmin
여기서 우리는 사용자의 역할을 지정합니다. 이 정보는 하이퍼레저 컴포저의 플레이그라운드에서 어떤 사용자가 어떤 작업을 수행할 수 있는지 알기 위해 필요합니다. Admin@org1.example.com이라는 사용자는 하이퍼레저 패브릭 네트워크의 관리자로 PeerAdmin (체인코드 설치 가능) 과 ChannelAdmin (체인코드 객체 생성가능) 역할을 가집니다.
Step Six: Importing the business network card for the Hyperldeger Fabric administrator
하이퍼레저 컴포저는 지갑에 있는 비즈니스 네트워크 카드만 사용할 수 있습니다. 지갑은 비즈니스 네트워크 카드들을 포함하고 있는 파일 시스템 내 디렉토리 입니다. 이 단계에서는 step 5에서 생성한 비즈니스 네트워크 카드를 지갑으로 import해서 다음 단계에서 이 비즈니스 네트워크 카드를 사용할 수 있도록 합니다.
composer card import 명령어를 실행해 비즈니스 네트워크 카드를 지갑으로 import 하세요.
이제 PeerAdmin@fabric-network라는 이름을 지정해 비즈니스 네트워크 카드를 사용할 수 있습니다. 이제 블록체인 비즈니스 네트워크를 하이퍼레저 패브릭 네트워크에 배포할 모든 준비가 끝났습니다.
우리는 developer tutorial에서 생성한 tutorial-network라는 블록체인 비즈니스 네트워크를 배포할 것입니다. 아직 비즈니스 네트워크 아카이프 파일(.bna)을 만들지 않았다면 step 1, 2, 3 및 developer tutorial을 통해 생성하세요.
Step Seven: Installing the Hyperledger Composer business network onto the Hyperledger Fabric peer nodes
이 단계에서, 블록체인 비즈니스 네트워크를 하이퍼레저 패브릭 피어 노드의 모든 조직에 설치할 것입니다. 하이퍼레저 패브릭 용어에서 이것을 체인코드 설치라고 부릅니다.
이 옵션은 step 6에서 지갑으로 import한 비즈니스 네트워크 카드의 이름을 의미합니다.
--networkName tutorial-network
이 옵션은 tutorial-network의 블록체인 비즈니스 네트워크 이름을 의미합니다.
--networkVersion 0.0.1
이 옵션은 tutorial-network라고 불리는 블록체인 비즈니스 네트워크의 버전을 의미하며, 이는 비즈니스 네트워크의 package.json 내 version 속성에 정의되어 있습니다.
-A admin
블록체인 비즈니스 네트워크가 배포될 때, 블록체 비즈니스 네트워크 관리자가 될 참가자를 적어도 한 명 이상 생성해야 합니다. 이 참가자는 다른 참가자를 블록체인 비즈니스 네트워크에 onboarding할 책임이 있습니다. 여기서는 admin이라는 단일 블록체인 비즈니스 네트워크 관리자를 만들고자 합니다.
-S adminpw
이 옵션은 블록체인 비즈니스 네트워크 관리자 admin이 adminpw 비밀번호를 사용해 CA에서 인증서 및 개인 키를 요청하도록 지정하는 옵션입니다. 이 옵션을 지정하면 비즈니스 네트워크 관리자에게 지정된 이름이 CA에 이미 등록된 사용자의 기존 등록 ID여야 합니다.
이제 블록체인 비즈니스 네트워크가 시작되었으므로 생성된 비즈니스 네트워크 카드 파일 admin@tutorial-network.card를 사용하여 상호작용할 수 있습니다.
Step Nine: Importing the business network card for the business network administrator
composer card import 커맨드를 실행해 비즈니스 네트워크 카드를 지갑으로 import 하세요.
Update transaction logic to use queries and events
이제 도메인 모델이 업데이트 되었으므로, 우리는 이제 트랜잭션이 처리를 위해 제출될 때 실행되는 추가적인 비즈니스 로직을 작성할 수 있습니다. 이 튜토리얼에서 우리는 아래처럼 이벤트와 비즈니스 로직을 추가합니다.
1. 트랜잭션 처리 함수 파일(lib/logic.js)을 여세요.
2. 트랜잭션 내용을 아래 JavaScript코드로 변경하세요.
/**
* Track the trade of a commodity from one trader to another
* @param {org.example.mynetwork.Trade} trade - the trade to be processed
* @transaction
*/
async function tradeCommodity(trade) {
// set the new owner of the commodity
trade.commodity.owner = trade.newOwner;
let assetRegistry = await getAssetRegistry('org.example.mynetwork.Commodity');
// emit a notification that a trade has occurred
let tradeNotification = getFactory().newEvent('org.example.mynetwork', 'TradeNotification');
tradeNotification.commodity = trade.commodity;
emit(tradeNotification);
// persist the state of the commodity
await assetRegistry.update(trade.commodity);
}
/**
* Remove all high volume commodities
* @param {org.example.mynetwork.RemoveHighQuantityCommodities} remove - the remove to be processed
* @transaction
*/
async function removeHighQuantityCommodities(remove) {
let assetRegistry = await getAssetRegistry('org.example.mynetwork.Commodity');
let results = await query('selectCommoditiesWithHighQuantity');
for (let n = 0; n < results.length; n++) {
let trade = results[n];
// emit a notification that a trade was removed
let removeNotification = getFactory().newEvent('org.example.mynetwork','RemoveNotification');
removeNotification.commodity = trade;
emit(removeNotification);
await assetRegistry.remove(trade);
}
}
3. logic.js 파일 변경 내용을 저장하세요.
첫 번째 함수인 tradeCommodity는 들어오는 Trade 트랜잭션 내 commodity의 owner 속성을 변경할 것입니다. (새로운 참가자를 소유자로) 그리고 해당 효과에 대한 알림을 생략할 것입니다. 그리고나서 수정된 commodity를 다시 Commodity 객체를 저장하는 asset registry에 저장합니다.
두 번째 함수는 named query라고 불리는 'selectCommoditiesWithHighQuantity' (queries.qry 파일에 정의된) 쿼리로 quantity > 60인 모든 Commodity asset 기록을 리턴합니다. 이벤트는 생략하며 해당 Commodity를 AssetRegistry에서 제거합니다.
Step Two: Create a query definition file
이 쿼리는 queries.qry 파일 내 정의된 트랜잭션 처리 로직에 의해 사용됩니다. 각 쿼리 엔트리는 리소스 및 어느 쿼리가 실행될지를 결정하는 기준을 정의합니다.
1. tutorial-network 폴더 내, queries.qry파일을 생성하세요.
2. queries.qry 파일 내 아래 코드를 붙여넣으세요.
/** Sample queries for Commodity Trading business network
*/
query selectCommodities {
description: "Select all commodities"
statement:
SELECT org.example.mynetwork.Commodity
}
query selectCommoditiesByExchange {
description: "Select all commodities based on their main exchange"
statement:
SELECT org.example.mynetwork.Commodity
WHERE (mainExchange==_$exchange)
}
query selectCommoditiesByOwner {
description: "Select all commodities based on their owner"
statement:
SELECT org.example.mynetwork.Commodity
WHERE (owner == _$owner)
}
query selectCommoditiesWithHighQuantity {
description: "Select commodities based on quantity"
statement:
SELECT org.example.mynetwork.Commodity
WHERE (quantity > 60)
}
3. queries.qry 파일을 저장하세요.
Step Three: Regenerate your business network archive
비즈니스 네트워크 내 파일을 변경한 후, 비즈니스 네트워크는 비즈니스 네트워크 아카이브 (.bna)로 리패키징되어 하이퍼레저 패브릭 객체에 재배포되어야 합니다. 배포된 네트워크를 업그레이드 하기 위해서는 새로운 버전 및 버전 번호가 필요합니다.
1. tutorial-network 폴더에서 package.json 파일을 여세요.
2. version 속성을 0.0.1에서 0.0.2로 업데이트하세요.
3. 커맨드라인을 사용해 tutorial-network폴더로 이동하세요.
4. 아래 명령어를 실행하세요.
composer archive create --sourceType dir --sourceName . -a tutorial-network@0.0.2.bna
Step Four: Deploy the updated business network definition
우리는 수정된 네트워크가 블록체인의 가장 최신 버전이 되도록 배포해야 합니다. 우리는 이미 배포된 비즈니스 네트워크를 업데이트 하기 위해 새로 생성된 비즈니스 네트워크 아카이브 파일을 사용하고 있습니다. 이는 developer tutorial에서 사용한 것과 동일한 비즈니스 네트워크 이름을 갖고 있습니다.
1. 터미널로 이동해 tutorial-network@0.0.2.bna 파일을 포함하고 있는 디렉토리로 이동하세요.
Step Seven: Perform queries using the commodity trading REST API explorer
이제 몇몇 자산과 참가자가 생성되었으므로 우리는 생성된 쿼리 REST operation을 사용해 쿼리를 테스트할 수 있습니다.
Perform a simple REST query
이제 우리는 자산과 참가자가 있으므로 쿼리를 실행해 볼 수 있습니다.
실행해볼 수 있는 가장 단순한 REST 쿼리는 named query인 selectCommodities입니다.
'Query' REST Endpoint 탭을 확장해 모델 내 정의된 named query들을 볼 수 있습니다.
이 쿼리들은 이제 REST 쿼리로 노출되며 /GET operation이 생성됩니다. 쿼리에 대산 설명 (우리가 모델 정의에 작성한) 은 오른쪽에 보여집니다.
1. selectCommodities 쿼리 탭을 확장하세요.
2. 'Try it Out' 버튼을 클릭하세요.
그러면 모든 존재하는 Commodity들이 리턴될 것입니다. - 2개의 자산이 리턴되어야 합니다.
Perform Filtered REST Queries
이제 교환을 통해 이뤄진 모든 Commodity를 선택해 봅시다. - 예를 들어 메인 거래인 'EURONEXT'
1. query endpoint탭을 확장하고 'selectCommoditiesByExchange'를 선택한 후 스크롤을 아래로 내려 파라미터 섹션으로 이동하세요.
2. 'Exchange' 파라미터에 'EURONEXT'를 입력하세요.
3. 'Try it Out'을 클릭하세요.
결과는 'EURONEXT'에 의해 교환된 commodity만을 반환하며 이는 response body에 담겨있습니다.
Perform Transaction update using results from naemd Query
마지막으로, 우리가 쿼리 파일에 정의한 Quantity > 60 이상인 Commodity를 선택하는 간단한 쿼리를 회상해봅시다. 쿼리는 트랜잭션 함수를 사용할 때 매우 강력합니다. 쿼리를 사용하면 트랜잭션 로직은 자산 혹은 참가자 집합을 업데이트하거나, 생성/삭제 등의 행위를 수행할 수 있습니다.
우리는 selectCommoditiesWithHighQuantity 쿼리를 removeHighQuantityCommodities 트랜잭션에서 사용합니다. 만일 이 /GET operation을 REST 익스플로러에서 실행시키면, quantity가 60보다 큰 자산을 볼 수 있습니다.
이제 high quantity Commodities를 삭제하기 위해 쿼리를 사용해 봅시다.
먼저 얼마나 많은 Commodity들이 존재하는지 확인하세요 ('Commodity' /GET operation 사용). 그러면 적어도 두 개의 Commodities를 확인할 수 있을 것이며 그 중 하나 (Cocoa)는 quantity가 60보다 클 것입니다.
REST Endpoint의 /selectCommoditiesWithHighQuantity를 클릭한 후 /GET을 클릭하고 스크롤을 아래로 내려 'Try it Out' 버튼을 누르세요. 실제 쿼리를 확인해봅시다. 기준을 만족시키는 하나의 Commodity가 있을 것입니다.
이제 어느 Commodity를 삭제할 지 결정하는 'High Quantity' 쿼리 정의를 사용해 REST 트랜잭션을 실행시켜봅시다.
RemoveHighQuantityCommodities REST Endpoint를 클릭해 /POST operation이 보이게 하세요.
POST를 클릭하고 스크롤을 아래로 내리면 파라미터 섹션이 보입니다. 'Try it Out'을 클랙하세요.
참고: 'data' 섹션에 있는 어떤 데이터도 입력하지 않아도 됩니다.
스크롤을 아래로 내리면 트랜잭션 처리 함수 내부적으로 'remove'를 호출 (블록체인 트랜잭션) 하고 world state를 업데이트하는 트랜잭션 id를 볼 수 있습니다. - Reponse Code는 200dldjdi gkqslek.
마지막으로 우리 Commodities의 status를 확인해 봅시다. 'Commodity' REST Operation으로 돌아가 다시 한번 'Try it Out' 버튼을 사용해 /GET operation을 수행해보세요.
결과는 Commodidy 자산인 'Cocoa'가 사라져있을 것입니다. 즉, Commodity 자산의 quantity 가 60 이하인 것만 남아 있을 것입니다. 여기서는 'Corn'이 남아있습니다. named query는 트랜잭션 업데이트를 수행하고 (high quantity commodities를 제거하는) 비즈니스 로직을 수행했습니다.
Caliper는 Lerna에서 여러 패키지로 나뉘어 집니다. Lerna는 여러 패키지로 JavaScript프로젝트를 관리하는 도구입니다. Caliper를 구축하려면 먼저 필요한 기본 종속성을 가져와 Caliper 프로젝트를 실행시켜야 합니다. 기본 코드를 수정하는 경우 프로젝트를 다시 빌드해야 합니다.
Caliper root 폴더에서 기본 종속성을 설치하기 위해 npm install을 실행하세요.
패키지들이 빈 상태임을 확실히 하기 위해 npm run repoclean을 실행하세요.
Caliper repository에 있는 패키지를 실행하기 위해 npm run bootstrap을 실행하세요. 이 과정은 모든 패키지 종속성과 종속성 간 링크를 설치합니다. 설치에는 시간이 다소 소요될 수도 있습니다. ctrl+c로 중단될 경우, package.json 파일을 먼저 복구한 후 npm run bootstrap 명령어를 다시 실행하세요.
벤치마크는 Caliper 커맨드 인터페이스를 사용하여 실행할 수 있습니다. 빌드 과정에는 proxy npm 서버에 모든 Caliper 모듈을 게시한 다음 이 서버에서 CLI 패키지를 전체적으로 설치하는 통합테스트가 포함되어 있지만, 우리는 npm으로 Caliper 패키지를 게시할 준비를 하고 있습니다. Caliper CLI를 사용하려면 Caliper 테스트 유틸리티를 사용하는 것이 좋습니다.
Intall the Caliper CLI
우리는 아직 npm에 Caliper를 게시하지 않았지만 Caliper CLI는 <CaliperRoot>/packages/caliper-tests-integration/scripts/run-integration-tests.sh에 있는 테스트 스크립트를 통해 얻을 수 있습니다. 테스트 스크립트에는 테스트 할 특정 어댑터를 선택하기 위해 환경변수 세트가 필요합니다. 이것은 단지 CI 시스템의 요구사항일 뿐입니다.
Steps:
1. 위 섹션에서 설명한 Caliper 프로젝트 빌드를 아직 하지 않았다면, 빌드하세요.
2. Caliper CLI를 획득하기 위해 root Caliper 위치에서 아래 명령어를 실행하세요.
위 명령어는 npm 프록시 서버 (Verdaccio)를 시작하고, Caliper 모듈을 서버에 게시하고, 패키지를 전역 설치하고, 마지막으로 traget 벤치마크를 실행합니다. 현재 벤치마크 결과는 중요하지 않습니다. 벤치마크가 시작되면 명령을 발행한 스템에 Caliper 패키지가 전역으로 설치됩니다.
현재 Caliper 패키지는 다음 어댑터 클라이언트 라이브러리를 지원하도록 설정되어 있습니다:
Burrow: @monax/burrow@0.23.0
Composer: composer@0.20.8
Fabric: fabric-client@1.4.0
Iroha: iroha-helpers@0.6.3
Sawtooth: sawtooth-sdk@1.0.5
위와 다른 클라리언트 종속성이 있는 어댑터를 사용하여 벤치마크를 실행해야하는 경우 통합 테스트 스크립트를 실행하기 전 해당 package.json 파일을 수정한 다음 Caliper 프로젝트를 다시 빌드해야 합니다. 알려진 호환성 목록은 아래와 같습니다.
예를 들어, Hyperledger Fabric v1.1을 테스트하려면 grpc@1.10.1, fabric-ca-client@1.1.0, fabric-client@1.1.0을 사용하도록 caliper-fabric-ccp 어댑터를 수정해야합니다.
참고: Caliper 패키지가 npm으로 게시되면 위의 호환성 요구사항에 대한 버전을 게시하게 되며 npm install -g caliper-<package>@<version>을 사용하여 얻을 수 있는 Caliper버전으로 표가 업데이트 됩니다.
Run a Sample Benchmark
미리 정의된 벤치마크는 벤치마크 폴더에서 볼 수 있습니다. Caliper CLI에는 벤치마크 구성 및 테스트 파일이 포함된 workspace라는 개념이 있습니다.
벤치마크는 Caliper CLI command를 사용해 실행됩니다.
caliper benchmark run -w <path to workspace> -c <benchmark config> -n <blockchain config>
-w : workspace 디렉토리 경로 (필수)
-c : workspace에서 벤치마크 configuration 파일 상대경로 (필수)
-n : workspace에서 테스트할 블록체인 네트워크 config 파일의 상대경로
root Caliper 폴더에 있다고 가정하면, 아래 명령어는 Caliper 샘플에 있는 내용을 사용해 테스를 실행합니다.
caliper benchmark run -w ./packages/caliper-samples -c benchmark/simple/config.yaml -n network/fabric-v1.4/2org1peercouchdb/fabric-ccp-node.yaml
원하는 벤치마크를 수행하기 위해 caliper-sampls 디렉토리에 있는 파일을 수정하거나 추가할 수 있습니다. 벤치마크를 추가하기 전에 샘플 벤치마크 컨텐츠 및 구조를 확인하세요. 테스느 중인 블록체인 시스템, 벤치마크 구성, 스마트 계약 및 배포된 스마트 계약과 상호작용하는 테스트 파일(콜백)에 대한 고유 구성파일을 추가해야 합니다.
Run Benchmark with Distributed Clients (Experimental)
이 방식에서는, 여러 클라이언트가 동일한 벤치마크 수행을 위해 분산 호스트에서 실행될 수 있습니다.
1. Caliper CLI를 사용해 ZooKeeper 서비스를 시작하세요.
caliper zooservice start
2. Caliper CLI를 사용해 각 대상 머신에 caliper-zoo-client를 실행하세요.
caliper zooclient start -w ~/myCaliperProject -a <host-address>:<port> -n my-sut-config.yaml
3. configuration 파일에 있는 클라이언트 타입 설정을 zookeeper로 변경하세요.
Zookeeper는 클라이언트를 등록하고 메시지를 교환하는 데 사용됩니다. 시작된 클라이언트는 /caliper/clients/ 아래에 새로운 znode를 추가합니다. 벤치마크에서는 디렉토리를 점검하여 얼마나 많은 클라이언트가 있는지 알아보고 작업 부하에 따라 각 클라이언트에 작업을 할당합니다.
클라이언트 간에는 자동 시간 동기화가 없습니다. 'ntpdate'를 사용하는 것과 같이 대상 시스템 간의 시간을 수동으로 동기화해야 합니다.
블록체인 구성파일은 클라이언트를 실행하는 시스템에 있어야 하며 파일의 상대 경로 (캘리퍼 폴더에 상대적인) 가 일치해야 합니다. 구성의 모든 참조 파일도 존재해야 합니다.
이 튜토리얼은 처음부터 Hyperledger Composer 블록체인 솔루션을 작성하는 과정을 안내합니다. 몇 시간 내에 블록체인 혁신에 대한 아이디어, 실제 Hyperledger Fabric 블록체인 네트워크와의 트랜잭션 실행, 블록체인 네트워크와 상호작용하는 샘플 Angular 2 애플리케이션 생성/실행 등의 작업을 수행할 수 있습니다.
이 튜토리얼은 자신의 유즈케이스에 적용할 수 있는 기술 및 리소스에 대한 개요를 제공합니다.
참고: 이 튜토리얼은 Hyperledger Fabric v1.2와 함께 실행되는 Ubuntu Linux의 최신 Hyperledger Composer 빌드에 대해 작성되었으며, Mac 환경에서도 테스트할 수 있습니다.
Step One: Creating a business network structure
Hyperledger Composer의 주요 컨셉은 비즈니스 네트워크 정의 (Business network definition, BND)입니다.이는 블록체인 솔루션을 위한 데이터 모델, 트랜잭션 로직, 접근 제어 규칙을 정의합니다. BND를 생성하기 위해 우리는 적절한 프로젝트 구조를 생성해야 합니다.
가장 쉬운 방법은 Yeoman generator를 사용해서 비즈니스 네트워크 뼈대를 만드는 것입니다. 이렇게 하면 비즈니스 네트워크의 모든 구성 요소를 포함하는 디렉토리가 생성됩니다.
1. Yeoman을 사용해 스비즈니스 네트워크 뼈대를 만듭니다. 이 명령에는 비즈니스 네트워크 이름, 설명, 작성자 이름, 작성자 메일주소, 라이센스 선택 및 네임스페이스가 필요합니다.
yo hyperledger-composer:businessnetwork
2. 네트워크 이름에 tutorial-network를 입력하고, 설명, 작성자 이름, 작성자 메일주소 같은 필요 정보를 입력합니다.
3. 라이센스로 Apache-2.0을 선택합니다.
4. 네임스페이스로 org.example.mynetwork를 선택합니다.
5. 빈 네트워크를 생성할지 말지 물으면 No를 선택합니다.
Step Two: Defining a business network
비즈니스 네트워크는 자산, 참가자, 트랜잭션, 접근 제어 규칙, 그리고 부가적인 이벤트와 쿼리로 구성되어 있습니다. 이전 단계에서 생성된 비즈니스 네트워크 뼈대에는 비즈니스 네트워크의 모든 자산, 참가자, 트랜잭션에 대한 클래스 정의를 포함한 모델(.cto)파일이 있습니다. 비즈니스 네트워크 뼈대는 또한 기본적인 접근 제어(permission.acl) 문서와 트랜잭션 처리 함수를 포함한 기본적인 접근 제어 규칙인 가진 스크립트(logic.js)파일 그리고 비즈니스 네트워크의 메타데이터를 포함한 package.json 파일을 갖고 있습니다.
Modeling assets, participants, and transactions
처음으로 업데이트할 문서는 모델(.cto) 파일입니다. 이 파일은 Hyperledger Composer Modeling Language를 사용해 작성되어 있습니다. 모델 파일은 자산, 트랜잭션, 참가자, 이벤트에 대한 각 클래스의 정의를 포합합니다. 이는 암묵적으로 modeling language 문서에 있는 Hyperledger Composer System Model을 extend합니다.
1. org.example.mynetwork.cto 모델 파일을 여십시오.
2. 모델 파일 내용을 아래와 같이 변경하세요.
/**
* My commodity trading network
*/
namespace org.example.mynetwork
asset Commodity identified by tradingSymbol {
o String tradingSymbol
o String description
o String mainExchange
o Double quantity
--> Trader owner
}
participant Trader identified by tradeId {
o String tradeId
o String firstName
o String lastName
}
transaction Trade {
--> Commodity commodity
--> Trader newOwner
}
3. org.example.mynetwork.cto에 대한 변경사항을 저장하세요.
Adding JavaScript transcation logic
모델 파일에서 자산, 참가자 간 관계를 명시하는 Trade 트랜잭션이 정의되었습니다. 트랜잭션 처리함수 파일은 모델 파일에 정의된 트랜잭션을 실행시키는 JavaScript로직을 갖고 있습니다.
Trade 트랜잭션은 간단하게 거래될 Commodity 자산의 식별자를 가져와서 참가자 Trader의 식별자를 새 소유자로 지정합니다.
1. logic.js 스크립트 파일을 여세요.
2. 파일 내용을 아래와 같이 변경하세요.
/**
* Track the trade of a commodity from one trader to another
* @param {org.example.mynetwork.Trade} trade - the trade to be processed
* @transaction
*/
async function tradeCommodity(trade) {
trade.commodity.owner = trade.newOwner;
let assetRegistry = await getAssetRegistry('org.example.mynetwork.Commodity');
await assetRegistry.update(trade.commodity);
}
3. logic.js 변경 내용을 저장하세요.
Adding access control
1. permissions.acl파일에 있는 접근제어규칙을 아래와 같이 변경하세요.
/**
* Access control rules for tutorial-network
*/
rule Default {
description: "Allow all participants access to all resources"
participant: "ANY"
operation: ALL
resource: "org.example.mynetwork.*"
action: ALLOW
}
rule SystemACL {
description: "System ACL to permit all access"
participant: "ANY"
operation: ALL
resource: "org.hyperledger.composer.system.**"
action: ALLOW
}
2. permissions.acl 파일 변경 내용을 저장하세요.
Step Three: Generate a business network archive
이제 비즈니스 네트워크가 정의되었습니다. 이 비즈니스 네트워크는 배포가능한 비즈니스 네트워크 archive(.bna) 파일에 패키징되어야 합니다.
1. 커맨드 라인을 사용해 tutorial-network 폴더로 이동하세요.
2. tutorial-network 폴더에서, 아래 명령어를 실행하세요.
composer archive create -t dir -n .
명령어가 실행되고나면, tutorial-network 폴더에 생성된 tutorial-network@0.0.1.bna라는 비즈니스 네트워크 archive 파일이 호출됩니다.
Step Four: Deploying the business network
.bna파일 생성 후, 비즈니스 네트워크는 Hyperledger Fabric 객체로 배포될 수 있습니다. 일반적으로 PeerAdmin identity를 생성하기 위해 패브릭 관리자 정보가 필요합니다. PeerAdmin은 composerchannel 채널에 있는 체인코드를 실행하고 다른 피어들에게 체인코드를 설치하는 권한을 갖고 있습니다. 하지만, 개발환경설치과정에서 PeerAdmin은 이미 생성되어 있습니다.
비즈니스 네트워크가 설치된 후, 네트워크를 시작할 수 있습니다. 가장 좋은 방법은 배포 후 비즈니스 네트워크를 관리하기 위해 새 ID를 만드는 것입니다. 이 ID를 네트워크 관리자라고 합니다.
Retrieving the correct credentials
올바른 자격 증명을 가진 PeerAdmin 비즈니스 네트워크 카드는 개발환경설치과정에서 이미 생성되어 있습니다.
Deploying the business network
Hyperledger Fabric에 비즈니스 네트워크를 배포하려면 피어에 Hyperledger Composer 비즈니스 네트워크가 설치되어 있어야 합니다. 그리고 나서 비즈니스 네트워크를 시작할 수 있습니다. 네트워크 관리자가 되기 위해서는 새로운 참가자, 신원 및 관련 카드를 생성해야 합니다. 마지막으로 네트워크 관리자 비즈니스 네트워크 카드는 사용을 위해 import되어야 합니다. 그리고 그 네트워크가 응답하는지 확인하기 위해 ping을 수행할 수 있습니다.
1. 비즈니스 네트워크 설치를 위해 tutorial-network 폴더에서 아래 명령어를 실행하세요.
composer network ping 커맨드는 network ping을 확인하기 위해 비즈니스 네트워크 카드를 필요로 합니다.
Step Five: Generating a REST server
Hyperledger Composer는 비즈니스 네트워크를 기반으로 맞춤형 REST API를 생성할 수 있습니다. REST API는 웹 애플리케이션을 개발할 때 유용한 언어중심 추상화 계층을 제공합니다.
1. REST API 생성을 위해 tutorial-network 폴더로 이동해 아래 명령어를 실행하세요.
composer-rest-server
2. 카드 이름에 admin@tutorial-network를 입력하세요.
3. 생성된 API에서 네임스페이스를 사용할지 물으면 'never use namespaces'를 선택하세요.
4. 생성된 API를 보호할지 물으면 No를 선택하세요.
5. 이벤트 게시를 사용할지 물으면 Yes를 선택하세요.
6. TLS 보안을 사용할지 물으면 No를 선택하세요.
생성된 API는 배포된 블록체인 및 비즈니스 네트워크에 연결됩니다.
Step Six: Generating a skeleton Angular application
Hyperledger Composer는 REST API를 실행하는 Angular 4 응용프로그램을 생성할 수도 있습니다.
1. Angular 4 애플리케이션을 생성하기 위해 tutorial-network 폴더로 이동해 아래 명령어를 실행하세요.
yo hyperledger-composer:angular
2. 실행중인 비즈니스 네트워크에 연결할지 물으면 Yes를 선택하세요.
3. 일반적인 package.json 질문에 대해 입력하세요. (프로젝트명, 설명, 저자명, 이메일, 라이센스)
4. 비즈니스 네트워크 카드로 admin@tutorial-network를 입력하세요.
5. Connect to an existing REST API를 선택하세요.
6. REST 서버 주소로 http://localhost를 입력하세요.
7. 서버 포트로 3000를 입력하세요.
8. Namespaces are not used를 선택하세요.
Angular generator는 그리고나서 프로젝트 기반을 생성하고 모든 의존성을 설치합니다. 애플리케이션을 실행하기 위해 angular 프로젝트 폴더로 가서 npm start를 실행하세요. 이 명령어는 http://localhost:4200의 REST API를 실행하는 Angular 4 애플리케이션을 실행시킬 것입니다.
참고: Yo Angular application generator는 단순하고 기본적인 비즈니스 네트워크 모델 정의 (여기서는 trade-network 네트워크 모델 같은)에 기반한 웹 애플리케이션 뼈대를 만들기 위한 것입니다. Angular generator에 관한 상세 설명은 아래 링크를 참고하세요.
