Sui Bridge validator 노드 구성

bridge validator node(브리지 노드)를 실행하려면 브리지 위원회에 노드를 등록해야 한다. 노드를 올바르게 구성하면 최적의 성능과 유효한 metrics 데이터를 보장할 수 있다. 이 항목에 따라 브리지 노드가 올바르게 설정되었는지 확인한다.

Prerequisites

sui와 sui-bridge-cli를 설치한다.

Click to open

설치 지침

브리지 노드를 설정하고 실행하려면 다음 옵션 중 하나를 사용해 필요한 도구를 설치한다:

Install from tip of main:

$ cargo install --locked --git "https://github.com/MystenLabs/sui.git" sui sui-bridge-cli

Install with a commit sha:

$ cargo install --locked --git "https://github.com/MystenLabs/sui.git" --rev {SHA} sui sui-bridge-cli

Committee registration

네트워크에 참여하려면 먼저 브리지 위원회에 등록해야 한다.

Prepare for metadata

필수 메타데이터에는 두 가지가 있다:

BridgeAuthorityKey: 메시지에 서명하는 ECDSA 키이다. 메모리에 보관되는 hot key이므로, 다음 도구를 사용해 생성하고 파일에 기록해도 괜찮다.
브리지 노드가 listen하고 요청을 제공하는 REST API URL. 예: https://bridge.example-sui-validator.io:443. 포트가 올바른지 확인하고, URL에 따옴표 같은 유효하지 않은 문자가 들어가지 않도록 한다.

BridgeAuthorityKey를 생성하려면 다음을 실행한다:

$ sui-bridge-cli create-bridge-validator-key <PATH-TO-WRITE>

여기서 <PATH-TO-WRITE>는 key pair를 기록할 위치이다.

정보

키 유출을 방지하려면 안전한 환경(예: 노드가 실행되는 동일한 머신)에서 새 key pair를 생성하는 것을 강력히 권장한다.

Registration

authority key file과 REST API URL을 모두 준비했다면 Sui CLI를 사용해 등록할 수 있다:

$ sui validator register-bridge-committee --bridge-authority-key-path <BRIDGE-AUTHORITY-KEY-PATH> --bridge-authority-url <BRIDGE-AUTHORITY-URL>

Offline signing

validator account key를 cold storage에 보관하거나 오프라인 서명을 수행하려면 --print-only와 --validator-address 플래그(validator address 값 포함)를 사용한다. 그러면 직렬화된 unsigned transaction bytes가 출력되고, 원하는 서명 절차를 사용해 signed bytes를 만들 수 있다.

이를 실행하려면 다음 명령을 사용한다:

$ sui client execute-signed-tx

Update metadata (before committee is finalized)

key와 URL은 committee가 확정되기 전에는 변경할 수 있다. 메타데이터를 업데이트하려면 sui validator register-bridge-committee를 다시 실행하면 된다.

View registered metadata

온체인에 올바른 메타데이터를 등록했는지 다시 확인하려면 다음을 실행한다:

$ sui-bridge-cli view-bridge-registration --sui-rpc-url {SUI-FULLNODE-URL}

Update metadata (after committee is finalized)

브리지 노드 URL을 업데이트하려면 다음 명령을 사용한다:

$ sui validator update-bridge-committee-node-url

transaction을 오프라인으로 서명하는 방법은 이 페이지의 offline signing section을 참조한다.

Authority key rotation은 아직 지원되지 않는다.

Bridge node

성능과 metrics 모니터링을 위해 브리지 노드를 구성하는 방법에는 여러 가지가 있다. 다음 지침에 따라 환경에 맞게 최상의 결과를 얻도록 노드를 구성한다.

Bridge node hardware requirements

권장 하드웨어 요구 사항:

CPU: 물리 코어 6개
Memory: 16GB
Storage: 200GB
Network: 100Mbps

Web application firewall (WAF) protection for bridge node

validator 리소스를 고갈시키려는 분산 서비스 거부(DDoS) 공격 및 유사한 공격을 방어하려면 bridge server에 rate limit 보호를 제공해야 한다.

이 보호 기능은 요청 속도에 대한 세밀한 제어와 해당 요청에 대한 observability도 제공한다.

현재 권장 rate limit은 고유 IP당 초당 50 requests이다.

Web application firewall (WAF) options

예를 들어 다음과 같은 관리형 cloud service를 사용할 수 있다:

실용적인 IP 기반 rate limit을 위해 HAProxy 같은 오픈소스 load balancer도 사용할 수 있다.

축약한 HAProxy 구성 예시는 다음과 같다:

frontend http-in
    bind *:80
    # Define an ACL to count requests per IP and block if over limit
    acl too_many_requests src_http_req_rate() gt 50
    # Track the request rate per IP
    stick-table type ip size 1m expire 1m store http_req_rate(1s)
    # Check request rate and deny if the limit is exceeded
    http-request track-sc0 src
    http-request deny if too_many_requests

    default_backend bridgevalidator

backend bridgevalidator
    # Note the port needs to match the value in bridge node config, default is 9191
    server bridgevalidator 0.0.0.0:9191

오픈소스 load balancing 옵션을 선택한다면 해당 service에 대한 metrics 수집과 alerting도 반드시 구성해야 한다.

Bridge node config

템플릿을 만들려면 sui-bridge-cli 명령을 사용한다. BridgeClient를 실행하려면(다음 섹션 참조) --run-client를 파라미터로 전달한다.

$ sui-bridge-cli create-bridge-node-config-template {PATH}
$ sui-bridge-cli create-bridge-node-config-template --run-client {PATH}

생성된 구성에는 다음 parameter가 포함된다:

Parameter	설명
`server-listen-port`	브리지 노드가 요청 처리를 위해 listen하는 포트.
`metrics-port`	Prometheus metrics를 내보내는 포트.
`bridge-authority-key-path`	앞서 언급한 `sui-bridge-cli create-bridge-validator-key` 명령으로 생성한 Bridge Validator key의 경로.
`run-client`	브리지 노드에서 BridgeClient를 활성화할지 여부(자세한 내용은 아래 참조).
`approved-governance-actions`	지원하려는 governance action 목록.
`sui:sui-rpc-url`	Sui RPC URL.
`sui:sui-bridge-chain-id`	Sui Mainnet은 `0`, Sui Testnet은 `1`.
`eth:eth-rpc-url`	Ethereum RPC URL.
`eth:eth-bridge-proxy-address`	Ethereum의 Bridge Solidity contracts용 proxy address.
`eth:eth-bridge-chain-id`	Ethereum Mainnet은 `10`, Sepolia Testnet은 `11`.
`eth:eth-contracts-start-block-fallback`	BridgeNode가 Ethereum FullNode에서 조회를 시작할 block 번호. 이 값은 Solidity contracts가 배포된 block이거나 그보다 조금 이전이어야 한다.
`metrics:push-url`	원격 Sui metrics pipeline의 URL(예: `https://metrics-proxy.[testnet_OR_mainnet].sui.io:8443/publish/metrics`). 자세한 내용은 아래 metrics push section을 참조한다.

run-client: true인 경우 생성된 구성에서 다음 추가 field도 볼 수 있다:

Parameter	설명
`db-path`	BridgeClient용 데이터베이스 경로.
`sui:bridge-client-key-path`	BridgeClient key의 파일 경로. 이 key는 앞서 설명한 대로 `sui-bridge-cli create-bridge-client-key`로 생성할 수 있다. `run-client`가 true인데 `sui:bridge-client-key-path`를 제공하지 않으면 Sui에 transaction을 제출할 때 기본적으로 Bridge Validator key를 사용한다. key 분리를 위해 이는 권장되지 않는다.

BridgeClient

BridgeClient는 브리지 transfer 요청을 조율한다. BridgeNode에서 실행하는 것은 선택 사항이다. BridgeClient는 Sui network에 transaction을 제출하므로, 활성화하면 충분한 SUI 잔액이 있는 Sui account key가 필요하다.

BridgeNode에서 bridge_client 기능을 활성화하려면 BridgeNodeConfig에 다음 parameter를 설정한다:

run-client: true
db-path: <PATH-TO-DB>
sui:
    bridge-client-key-path: <PATH-TO-BRIDGE-CLIENT-KEY>

BridgeClient key pair를 생성하려면 다음을 실행한다:

$ sui-bridge-cli create-bridge-client-key <PATH_TO_BRIDGE_CLIENT_KEY>

새로 생성된 Sui Address가 출력된다. 그다음 운영에 사용할 수 있도록 이 address에 SUI를 충전해야 한다.

Build bridge node

다음 방법 중 하나로 브리지 노드를 빌드하거나 설치한다:

cargo install 사용.

$ cargo install --locked --git "https://github.com/MystenLabs/sui.git" --branch {BRANCH-NAME} sui-bridge

$ cargo install --locked --git "https://github.com/MystenLabs/sui.git" --rev {SHA-NAME} sui-bridge

소스 코드에서 컴파일.

$ git clone https://github.com/MystenLabs/sui.git

$ cd sui

$ git fetch origin {BRANCH-NAME|SHA}

$ git checkout {BRANCH-NAME|SHA}

$ cargo build --release --bin sui-bridge

curl/wget으로 사전 빌드된 바이너리 사용(Linux/AMD64 only).

$ curl https://sui-releases.s3.us-east-1.amazonaws.com/{SHA}/sui-bridge -o sui-bridge

사전 빌드된 Docker image 사용. Pull from Docker Hub: mysten/sui-tools:{SHA}

Run bridge node

브리지 노드 실행은 systemd나 Ansible로 Sui 노드를 실행하는 방식과 유사하다. 브리지 노드를 시작하는 명령은 다음과 같다:

$ RUST_LOG=info,sui_bridge=debug sui-bridge --config-path {BRIDGE-NODE-CONFIG-PATH}

Ingress

브리지 노드는 port 9191(또는 구성 파일에서 지정한 포트)로 TCP 연결을 수신한다. 브리지 노드를 실행하는 호스트에서 해당 포트의 incoming connection을 허용해야 한다.

원격 머신에서 curl로 ingress를 테스트하고 200 응답을 기대한다:

$ curl -v {YOUR_BRIDGE_URL}

Bridge node monitoring

노드가 실행 중인지 확인하려면 uptime을 사용한다.

브리지 노드 metrics 전체 목록과 설명은 sui-bridge crate에서 확인할 수 있다.

When `run-client: false`

이 경우 브리지 노드는 수동 관찰자로 실행되며 온체인 activity를 선제적으로 poll하지 않는다. 이때 중요하게 모니터링할 것은 다음과 같은 request 처리 metrics이다:

bridge_requests_received
bridge_requests_ok
bridge_err_requests
bridge_requests_inflight
bridge_eth_rpc_queries
bridge_eth_rpc_queries_latency
bridge_signer_with_cache_hit
bridge_signer_with_cache_miss
bridge_sui_rpc_errors

When `run-client: true`

이 경우 BridgeClient가 켜지고 blockchain과 선제적으로 동기화한다. 진행 상황을 추적할 때 가장 중요한 metrics는 다음과 같다:

bridge_last_synced_sui_checkpoints
bridge_last_synced_eth_blocks
bridge_last_finalized_eth_block
bridge_sui_watcher_received_events
bridge_eth_watcher_received_events
bridge_sui_watcher_received_actions
bridge_eth_watcher_received_actions

bridge_gas_coin_balance도 클라이언트 gas coin 잔액을 추적하는 중요한 metrics이며, 특정 threshold 아래로 내려가면 보충해야 한다.

Metrics push

브리지 노드는 network 수준 observability를 위해 원격 proxy로 metrics를 푸시할 수 있다.

metrics 푸시를 활성화하려면 BridgeNodeConfig에 다음 parameter를 설정한다:

metrics:
    push-url: https://metrics-proxy.[testnet|mainnet].sui.io:8443/publish/metrics

proxy는 metrics key pair를 사용해 푸시된 metrics를 인증한다. 이는 sui-node가 NetworkKey로 metrics를 푸시하는 방식과 유사하다. NetworkKey와 달리 브리지 노드 metrics key는 온체인에 기록되지 않으므로 일시적이어도 된다. BridgeNodeConfig에 metrics-key-pair field가 제공되면 거기에서 metrics key를 로드하고, 없으면 즉석에서 새 key pair를 생성한다. proxy는 각 node의 metrics public API key를 주기적으로 조회해 node 공개 키를 가져온다.

브리지 노드가 시작될 때 다음 줄이 한 번 기록될 수 있다:

unable to push metrics: error sending request for url (xyz); new client will be created

이 현상이 지속되지 않는다면 무시해도 된다. 그렇지 않다면 다음을 시도한다:

$ curl -i  {your-bridge-node-url-on-chain}/metrics_pub_key

공개 키가 올바르게 반환되는지 확인한다.

Committee registration​

Prepare for metadata​

Registration​

Offline signing​

Update metadata (before committee is finalized)​

View registered metadata​

Update metadata (after committee is finalized)​

Bridge node​

Bridge node hardware requirements​

Web application firewall (WAF) protection for bridge node​

Web application firewall (WAF) options​

Bridge node config​

BridgeClient​

Build bridge node​

Run bridge node​

Ingress​

Bridge node monitoring​

When run-client: false​

When run-client: true​

Metrics push​