Universal Ledger CLI 설정

비공개 미리보기

이 제품에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

이 출시 버전 액세스에 대한 자세한 내용은 액세스 요청 페이지를 참조하세요.

Universal Ledger CLI는 트랜잭션 제출 및 Universal Ledger 네트워크와의 상호작용을 용이하게 하기 위해 실험 목적으로 제공되는 명령줄 인터페이스입니다. 프로덕션 사용 사례의 경우 Universal Ledger API를 사용하여 통합을 빌드하는 것이 좋습니다.

이 가이드에서는 Universal Ledger CLI를 시작하는 방법을 설명합니다. 학습 내용:

• Universal Ledger CLI를 가져오고 설정합니다.

• CLI를 사용하여 계정을 만들고 관리합니다.

• CLI에서 사용할 수 있는 다른 명령어를 살펴봅니다.

시작하기 전에

이 가이드를 완료하려면 다음이 필요합니다.

• Universal Ledger API가 사용 설정된 Google Cloud 프로젝트

• 트랜잭션을 제출하고 Universal Ledger 네트워크의 계정 상태를 쿼리할 수 있도록 roles/universalledger.networkUser와 같은 IAM 역할

• 네트워크에서 나를 위해 생성된 기존 Universal Ledger 계정 아직 계정이 없는 경우 새 계정 요청을 참조하세요.

CLI 설정

설정을 간소화하기 위해 이 가이드는 Cloud Shell 세션에서 제공되는 기본 환경을 대상으로 작성되었습니다. 다른 환경에서 CLI를 사용하려면 이러한 명령어를 수정해야 할 수 있습니다.

콘솔에서 Cloud Shell을 활성화합니다. Google Cloud

Cloud Shell 활성화

실험용:바이너리는 Universal Ledger 비공개 미리보기에 참여하는 고객에게 Docker 이미지로 제공됩니다.ul-cli 이 바이너리는 현재 개발 중이며 제품의 새 버전에서 변경되거나 삭제될 수 있습니다.

다음 명령어를 실행하여 CLI 구성 파일을 저장할 디렉터리를 만듭니다.

mkdir -p ~/.config/ul-cli

다음 명령어를 각각 실행하여 ul-cli Docker 이미지를 가져오고, 바이너리 실행을 위한 별칭을 정의하고, 바이너리가 작동하는지 확인합니다.

docker pull us-docker.pkg.dev/gcul-artifacts/images/client/ul-cli:latest
alias ul-cli="docker run --rm -i --user $(id -u):$(id -g) \
    --volume /tmp:/tmp \
    --volume ~/.config/ul-cli:/home/.config/ul-cli \
    --volume ~/.config/gcloud:/home/.config/gcloud \
    --volume .:/workspace \
    --env HOME=/home \
    --workdir /workspace \
    us-docker.pkg.dev/gcul-artifacts/images/client/ul-cli:latest"
ul-cli --help

다음 명령어를 실행하여 CLI를 구성합니다.

ul-cli config setup projects/PROJECT_ID/locations/REGION/endpoints/NETWORK_NAME

다음을 바꿉니다.

• PROJECT_ID: Universal Ledger API가 사용 설정된 Google Cloud 프로젝트의 ID입니다.
• REGION: 연결하려는 엔드포인트의 리전입니다.
• NETWORK_NAME: 상호작용하려는 네트워크의 이름입니다.

적합한 엔드포인트를 선택하는 데 도움이 필요하면 사용 가능한 네트워크 및 리전을 참조하세요.

이전 명령어는

~/.config/ul-cli/config.yaml

CLI에서 사용하고 유지관리할 구성으로 파일을 만듭니다.

Universal Ledger 계정 관리

이 섹션에서는 기존 계정을 등록하고, 원장에서 나를 위한 새 계정을 만들고, 다른 사용자를 위한 새 계정을 만드는 방법을 설명합니다.

기존 계정 등록

네트워크의 다른 참여자가 계정을 만든 후에는 다음 명령어를 사용하여 CLI의 주소록에 계정 세부정보를 등록할 수 있습니다.

ul-cli accounts register \
    --alias ACCOUNT_ALIAS \
    --account-id ACCOUNT_ID \
    --key-name ACCOUNT_KMS_KEY

다음을 바꿉니다.

• ACCOUNT_ALIAS: 향후 명령어 호출에서 이 계정을 식별하기 위해 CLI에서 로컬로 사용되는 짧은 문자열입니다. 예: usd-operator, my-token-manager, test-user-account
• ACCOUNT_ID: 나를 위해 생성된 Universal Ledger 계정의 ID입니다.
• ACCOUNT_KMS_KEY: 이 계정에서 사용하는 Cloud KMS 키 버전 의 전체 리소스 ID입니다. 이 특정 키 버전의 공개 부분을 사용하여 계정을 만들어야 합니다. 예상 형식은 리소스 ID 검색 을 참조하세요.

이것은 계정 세부정보를 CLI 구성 파일에 기록하는 로컬 작업으로, 이 계정을 대신하여 원장에 요청을 서명하고 제출할 수 있습니다.

나를 위한 새 계정 만들기

새 계정은 ul-cli accounts create 하위 명령어를 사용하여 만들 수 있습니다. 예를 들어 신규 사용자 계정을 만들려면 다음을 사용할 수 있습니다.

ul-cli accounts create account \
    --alias NEW_ACCOUNT_ALIAS \
    --key-name NEW_ACCOUNT_KMS_KEY \
    --comment "NEW_ACCOUNT_COMMENT" \
    --roles NEW_ACCOUNT_ROLES \
    --sender ACCOUNT_MANAGER_ALIAS

다음을 바꿉니다.

• NEW_ACCOUNT_ALIAS: 향후 명령어 호출에서 이 계정을 식별하기 위해 CLI에서 로컬로 사용되는 짧은 문자열입니다.
• NEW_ACCOUNT_KMS_KEY: 새 사용자 계정에서 사용할 Cloud KMS 키 버전 의 전체 리소스 ID입니다.
• NEW_ACCOUNT_COMMENT: 신규 사용자 계정과 연결된 원장에 기록할 관련 정보가 포함된 문자열입니다. 이것은 원장에 저장되지만 Universal Ledger에서 달리 해석되지 않는 불투명한 값입니다. 생성되면 이 필드는 변경할 수 없으며 네트워크에 액세스할 수 있는 모든 사용자가 읽을 수 있습니다.
• NEW_ACCOUNT_ROLES: 새 사용자 계정에 할당할 역할 을 쉼표로 구분한 목록입니다. 예: payer, receiver, contract-creator, contract-participant
• ACCOUNT_MANAGER_ALIAS: CLI로 이전에 등록하거나 만든 계정 관리자의 별칭입니다.

이렇게 하면 지정된 계정 관리자를 대신하여 CreateAccount 트랜잭션이 서명되고 제출됩니다.

ul-cli accounts create --help를 실행하여 만들 수 있는 다른 종류의 계정에 사용할 수 있는 옵션을 확인합니다.

다른 사용자를 위한 새 계정 만들기

다른 사용자를 위한 계정을 만들려면 사용자에게 공개 키를 공유하고 파일에 저장해 달라고 요청하세요. 일반적으로 키에 PEM 인코딩 형식을 사용하는 것이 좋습니다. 예를 들어 서명 키가 SHA256 다이제스트가 포함된 P-256 타원 곡선을 사용하는 경우 pem_ec_p256_sha256.pub이라는 파일에 저장합니다.

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJ/vWkd5wgakFbVD25k8WM9Ll6We+
c8RVDS0R4G8xetsmFjfNW/ZxwWeB86IvMjxY8ZsdU9+W7BL5YM6rUB5yCQ==
-----END PUBLIC KEY-----

그런 후에 다음 명령어를 실행하여 계정을 만듭니다.

ul-cli accounts create account \
    --alias NEW_ACCOUNT_ALIAS \
    --public-key "$(cat pem_ec_p256_sha256.pub)" \
    --key-format pem_ec_p256_sha256 \
    --comment "NEW_ACCOUNT_COMMENT" \
    --roles NEW_ACCOUNT_ROLES \
    --sender ACCOUNT_MANAGER_ALIAS

다음을 바꿉니다.

• NEW_ACCOUNT_ALIAS: 향후 명령어 호출에서 이 계정을 식별하기 위해 CLI에서 로컬로 사용되는 짧은 문자열입니다. 그러나 비공개 키가 없으므로 트랜잭션을 서명하거나 제출할 수 없습니다.
• NEW_ACCOUNT_COMMENT: 신규 사용자 계정과 연결된 원장에 기록할 관련 정보가 포함된 문자열입니다. 이것은 원장에 저장되지만 Universal Ledger에서 달리 해석되지 않는 불투명한 값입니다. 생성되면 이 필드는 변경할 수 없으며 네트워크에 액세스할 수 있는 모든 사용자가 읽을 수 있습니다.
• NEW_ACCOUNT_ROLES: 새 사용자 계정에 할당할 역할 을 쉼표로 구분한 목록입니다. 예: payer, receiver, contract-creator, contract-participant
• ACCOUNT_MANAGER_ALIAS: CLI로 이전에 등록하거나 만든 계정 관리자의 별칭입니다.

이렇게 하면 지정된 계정 관리자를 대신하여 CreateAccount 트랜잭션이 서명되고 제출됩니다.

--public-key 및 --key-format 플래그는 모든 accounts create 하위 명령어에 사용할 수 있으므로 이를 사용하여 다른 종류의 계정을 만들 수도 있습니다. 지원되는 대체 공개 키 형식은 KeyFormat KeyFormat을 참조하세요.

관리 계정 나열

다음 명령어를 실행하여 Universal Ledger CLI로 로컬에 등록되거나 생성된 모든 계정을 확인합니다.

ul-cli accounts list

다른 명령어 살펴보기

--help 플래그를 사용하여 Universal Ledger CLI에서 사용할 수 있는 다른 모든 명령어와 하위 명령어를 살펴봅니다.

예를 들어 사용할 수 있는 최상위 명령어를 보려면 다음을 실행합니다.

ul-cli --help

여기에는 다음과 같은 다른 종류의 트랜잭션을 제출하는 하위 명령어가 포함됩니다.

• accounts: 계정을 등록하거나 만들고, 역할 추가 또는 삭제, 계정 세부정보 쿼리와 같은 기존 계정에 대한 관리 작업을 실행합니다.
• contracts: 프로그래매틱 계약에서 메서드를 배포하고, 권한을 부여하고, 호출합니다.
• issuance: 청산소가 토큰 관리자의 발행 한도를 늘리거나 줄이고 결제 작업을 실행합니다.
• tokens: 토큰 관리자가 사용자 계정에서 토큰을 발행하거나 소각합니다.
• wallet: 사용자 계정이 잔액에서 다른 사용자 계정으로 금액을 이체합니다.

다음 단계

• Universal Ledger API에 RPC 요청을 보내는 방법을 알아봅니다.
• Universal Ledger API 참조를 확인합니다.