트론(TRX)

트론 지갑 구조

트론의 중앙화 지갑은 다음과 같이 구성되어 있습니다.

  • 대표주소
  • 수수료주소
  • 자식주소

TIP
수수료주소는 토큰 집금 시 필요한 수수료(TRX)를 자식주소에 충전할 때 사용합니다.






자식주소

자식주소 생성 API를 호출하여 자식주소를 생성합니다. 일반적으로 자식주소는 엔드 유저 당 1개씩 부여합니다. 생성한 자식주소는 콘솔의 [자식주소 정보]에서 확인하거나 자식주소 목록 조회 API를 호출하여 확인할 수 있습니다.

Response 예시

[
  {
    "address": "TX1VZmgXET9Ews14fuZW2nTmmpnD6YeoaX",
    "name": "테스트용 자식주소"
  }
]

❗️

트론은 자식주소를 활성화하기 위해 TRX나 TRC-10을 입금해야 합니다. 그렇지 않으면 옥텟에서 자식주소가 조회되더라도, 트론 네트워크 상에서는 자식주소가 조회되지 않습니다.






입금

입금 상태

외부에서 보낸 자산이 대표주소나 자식주소에 도착하면 옥텟은 이를 입금으로 인식합니다. 단, 입금 트랜잭션이 블록에 포함되었더라도 입금을 완료로 처리하지 않습니다. 트랜잭션의 완결성을 보장하기 위해 추가로 블록이 생성되어야 해당 트랜잭션을 완료(FINALIZED)로 처리합니다. 외부에서 자산을 보냈으나 대표주소나 자식주소에 도착하지 않았다면 해당 트랜잭션은 인식되지 않습니다. 따라서 입금 트랜잭션에는 실패(FAILED) 상태가 없습니다.

상태명내용
UNFINALIZED입금 트랜잭션이 블록에 포함된 상태
FINALIZED입금 트랜잭션이 블록에 포함된 뒤 다음 블록이 생성된 상태

입금 트랜잭션이 블록에 포함된 후 19개의 블록이 추가로 생성되어야 해당 트랜잭션을 입금 완료로 처리합니다.

테스트넷메인넷
19 block (약 60초)19 block (약 60초)


입금 확인

1. 콘솔에서 확인하기

콘솔의 [입출금 내역]에서 입금 내역을 확인할 수 있습니다. UNFINALIZED 상태인 입금은 '진행'으로 표시되며, FINALIZED 상태인 입금은 '완료'로 표시됩니다.


2. 웹훅으로 확인하기

대표주소나 자식주소에 입금이 완료되면 입금 웹훅이 전송됩니다. 전송된 웹훅으로 입금 여부를 확인할 수 있습니다. 웹훅 이용 방법과 전송되는 데이터 형태는 웹훅 페이지를 참고하세요.






집금

집금 과정

자식주소에 보관된 자산은 집금을 요청하기 전까지는 대표주소로 이동하지 않습니다. 따라서 대표주소의 잔액이 부족하지 않도록 주기적으로 집금을 진행해야 합니다.

특정 자산의 집금을 요청하면 모든 자식주소에 보관된 TRX 또는 토큰이 대표주소로 이동합니다. 이때 자식주소 당 트랜잭션이 1개씩 발생합니다. 예를 들어 자식주소 10개에 TRX가 보관되어 있다면 총 10개의 트랜잭션이 발생합니다.

단, 특정 자식주소에서 진행 중인 집금이 있다면 새로운 집금을 신청할 수 없습니다. 진행 중인 집금이 완료되어야 새로운 집금을 진행할 수 있습니다.

🚧

집금 전 대표주소를 활성화하세요.

활성화된 대표주소로만 집금을 진행할 수 있습니다.
집금을 진행하기 전 먼저 대표주소가 활성화되어 있는지 확인해야 합니다.


1. TRX 집금

TRX 집금 수수료는 트랜잭션 당 1회씩 발생합니다. Bandwidth Point(BP)를 수수료로 사용하며, 사용할 BP를 모두 소진한 경우 TRX를 수수료로 사용합니다. 이는 집금할 자산에서 차감됩니다. 이때, 집금할 자산이 예상 수수료보다 적은 자식주소에서는 집금이 진행되지 않습니다. 집금 진행 과정은 다음과 같습니다.

  1. 집금을 요청합니다.
  2. 집금을 실행할 자식주소 별 트랜잭션을 생성합니다.
  3. 최적 수수료를 계산한 뒤 트랜잭션을 전파합니다.
  4. 트랜잭션이 블록에 반영되면 집금이 완료됩니다.

2. TRC-10 집금

TRC-10 집금 수수료는 트랜잭션 당 1회씩 발생합니다. Bandwidth Point(BP)를 수수료로 사용하며, 사용할 BP를 모두 소진한 경우 TRX를 수수료로 사용합니다. 이때 자식주소에 수수료로 지불할 TRX가 없다면 수수료주소에서 자식주소로 TRX를 충전해줍니다. 이 과정에서도 수수료(수수료 충전 비용)가 발생합니다. 자식주소는 전송받은 TRX를 수수료로 지불하고 집금을 진행합니다. 집금 진행 과정은 다음과 같습니다.

  1. 집금을 요청합니다.
  2. BP를 모두 소진한 경우, 집금 수수료로 사용할 TRX를 수수료주소에서 자식주소로 충전합니다.
  3. 집금을 실행할 자식주소 별 트랜잭션을 생성합니다.
  4. 최적 수수료를 계산한 뒤 트랜잭션을 전파합니다.
  5. 트랜잭션이 블록에 반영되면 집금이 완료됩니다.

3. TRC-20 집금

TRC-20 집금 수수료는 트랜잭션 당 1회씩 발생합니다. Bandwidth Point와 Energy를 수수료로 사용하며, 사용할 Bandwidth Point나 Energy를 모두 소진한 경우 TRX를 수수료로 사용합니다. 이때 자식주소에 수수료로 지불할 TRX가 없다면 수수료주소에서 자식주소로 TRX를 충전해줍니다. 이 과정에서도 수수료(수수료 충전 비용)가 발생합니다. 자식주소는 전송받은 TRX를 수수료로 지불하고 집금을 진행합니다. 집금 진행 과정은 다음과 같습니다.

  1. 집금을 요청합니다.
  2. BP나 Energy를 모두 소진한 경우, 집금 수수료로 사용할 TRX를 수수료주소에서 자식주소로 충전합니다.
  3. 집금을 실행할 자식주소 별 트랜잭션을 생성합니다.
  4. 최적 수수료를 계산한 뒤 트랜잭션을 전파합니다.
  5. 트랜잭션이 블록에 반영되면 집금이 완료됩니다.


집금 수수료

집금 수수료는 트랜잭션 당 1회씩 발생합니다.

  • TRX 집금 시 : 트랜잭션이 발생하는 주소에서 수수료가 차감됩니다.
  • 토큰 집금 시 : 트랜잭션이 발생하는 주소에서 수수료가 차감됩니다. 단, 해당 주소에 수수료로 사용할 TRX가 없다면 수수료주소에서 수수료로 사용할 자산을 충전받은 뒤 이를 사용합니다.


집금 상태

집금 상태는 집금 과정에 따라 7가지로 구분됩니다. 자식주소에 보관된 자산은 집금 대기(AWAITING_GATHERING) 상태입니다.

집금 요청 시 수수료 충전이 필요하다면 자산의 상태가 수수료 충전 대기 중(AWAITING_FEE_INJECTION)으로 변경됩니다. 수수료 충전 트랜잭션이 생성되면 자산의 상태가 수수료 충전 중(FEE_INJECTING)으로 변경됩니다. 수수료 충전을 실패한 경우 자산의 상태가 수수료 충전 실패(FEE_INJECTION_FAILED) 처리됩니다.

수수료 충전을 성공하여 집금 트랜잭션이 생성되면 자산의 상태가 집금 중(GATHERING)으로 변동됩니다. 해당 트랜잭션이 블록에 포함되면 자산의 상태가 집금 완료(COMPLETED) 처리되며 집금이 완료됩니다.

집금을 시도했으나 트랜잭션이 실패한 경우 자산의 상태가 집금 실패(GATHERING_FAILED) 상태로 남게 됩니다. 수수료 충전 실패 및 집금 실패 상태인 자산은 다시 집금 대상에 포함됩니다. 집금을 시도했으나 수수료가 부족하여 트랜잭션이 생성되지 못한 경우 집금 대기(AWAITING_GATHERING) 상태로 남게 됩니다.

상태명내용
AWAITING_GATHERING집금 대기 중
AWAITING_FEE_INJECTION수수료 충전 대기
FEE_INJECTING수수료 충전 중
FEE_INJECTION_FAILED수수료 충전 실패
GATHERING집금 트랜잭션 생성
COMPLETED집금 트랜잭션 완료
GATHERING_FAILED집금 트랜잭션 실패


집금하기

자식주소에 보관된 자산을 대표지갑으로 이동합니다. 다음과 같이 2가지 방법으로 집금을 진행할 수 있습니다.

1. 콘솔에서 집금하기

콘솔 - 지갑 선택 - [집금 내역]에서 집금을 진행할 수 있습니다. [집금하기] 버튼을 클릭하고 집금할 자산과 수량을 확인한 뒤 집금을 진행하세요.


2. API로 집금하기

집금 신청 API를 호출하면 집금이 진행됩니다.

Response 예시

[
  {
    "success": true,
    "uuid": "97410344-a48b-4f7e-a1ee-2feff91bebaa",
    "childAddresses": [
      "TX1VZmgXET9Ews14fuZW2nTmmpnD6YeoaX"
    ]
  },
  {
    "success": false,
    "childAddresses": [
      "TL6pYZx8XHQLdTuXLcaK6PfWXgxYD4MtRA"
    ],
    "errorCode": "ERR_0420002",
    "errorMessage": "The amount to be gathered is less than the minimum amount to be gathered."
  }
]


집금 확인

1. 콘솔에서 확인하기

지갑 선택 - [집금 내역] - [집금 내역]에서 집금 내역을 확인할 수 있습니다.


2. API로 확인하기

집금 신청 정보 조회 API를 호출하면 특정 집금 트랜잭션의 진행 상태를 확인할 수 있습니다.

Response 예시

{
  "idx": 1681,
  "status": "AWAITING_FEE_INJECTION",
  "createdDate": "2023-02-15T07:54:04.030Z",
  "modifiedDate": "2023-02-15T07:54:04.030Z",
  "coin": {
    "idx": 117,
    "symbol": "BTT",
    "nameKo": "BTT",
    "nameEn": "BTT",
    "status": "ACTIVATED",
    "type": "TRC20",
    "contractAddress": "TNuoKL1ni8aoshfFL1ASca1Gou9RXwAzfn",
    "decimals": 18,
    "createdDate": "2023-02-08T09:30:43.084Z",
    "modifiedDate": "2023-02-10T00:24:07.052Z"
  },
  "feeInjectionTransaction": null,
  "feeInjectionFee": {
    "idx": 1392898,
    "gasLimit": "500000.00000000000000000000",
    "gasPrice": "1.00000000000000000000",
    "rate": null,
    "unit": "sun",
    "createdDate": "2023-02-15T07:54:04.026Z",
    "modifiedDate": "2023-02-15T07:54:04.026Z"
  },
  "gatheringTransaction": null,
  "gatheringFee": {
    "idx": 1392897,
    "gasLimit": "500000.00000000000000000000",
    "gasPrice": "1.00000000000000000000",
    "rate": null,
    "unit": "sun",
    "createdDate": "2023-02-15T07:54:04.022Z",
    "modifiedDate": "2023-02-15T07:54:04.022Z"
  },
  "errorCode": null,
  "errorMessage": null
}

3. 웹훅으로 확인하기

대표주소로 집금이 완료되면 집금 웹훅이 전송됩니다. 전송된 웹훅으로 집금 여부를 확인할 수 있습니다. 웹훅 이용 방법과 전송되는 데이터 형태는 웹훅 페이지를 참고하세요.






출금

출금 과정

중앙화 지갑에서 외부로 자산을 보내려면 반드시 대표주소에서 출금해야 합니다. 자식주소에서는 외부로 자산을 출금할 수 없습니다.

  1. 출금을 요청합니다.
  2. 트랜잭션을 생성합니다.
  3. 최적 수수료를 계산한 뒤 트랜잭션을 전파합니다.
  4. 트랜잭션이 블록에 반영되면 출금이 완료됩니다.


출금 상태

입금과는 달리 출금은 트랜잭션이 블록에 포함된 즉시 출금 완료(FINALIZED) 처리됩니다.

상태명내용
AWAITING_DECISION출금 승인 대기 중인 상태
REJECTED출금이 거절된 상태
AWAITING_WITHDRAWAL출금이 승인되어 출금 대기 중인 상태
PENDING출금 트랜잭션이 생성된 상태
FINALIZED출금 트랜잭션이 블록에 포함된 상태
FAILED출금 트랜잭션이 실패한 상태


출금하기

출금 신청 API를 호출하면 대표주소에서 외부로 출금을 요청할 수 있습니다. 출금 요청에 성공하면 uuid 값이 반환됩니다. 해당 값으로 출금 진행 상태를 조회할 수 있습니다.

Response 예시

{
  "uuid": "8bc699a0-7dbd-4b34-b546-e908b448907d"
}


출금 확인

1. 콘솔에서 확인하기

콘솔의 [입출금 내역]에서 출금 내역을 확인할 수 있습니다. AWAITING_WITHDRAWALPENDING 상태인 출금은 '진행'으로 표시되며, FINALIZED 상태인 출금은 '완료'로 표시됩니다.


2. API로 확인하기

출금 트랜잭션 정보 조회 API를 호출하면 특정 출금 트랜잭션의 진행 상태를 확인할 수 있습니다.

Response 예시

{
  "idx": 2221883,
  "coin": {
    "idx": 12,
    "symbol": "TRX",
    "nameKo": "트론",
    "nameEn": "Tron",
    "status": "ACTIVATED",
    "type": "DEFAULT",
    "contractAddress": null,
    "decimals": 6,
    "createdDate": "2022-11-22T08:39:25.000Z",
    "modifiedDate": "2022-12-27T07:45:08.014Z"
  },
  "uuid": "23d2de3e-4cb0-40f7-9341-51b1fb4d81ae",
  "fromAddress": "TDpz5ZE56QWpx8eWJmsbfqf65tqR2ndrdU",
  "toAddress": "TFumbcWfBRaqp8PXGbuem25GW79J3Z6yTx",
  "amount": "1.00000000000000000000",
  "memo": null,
  "requestId": "202301171702",
  "type": "API",
  "description": "",
  "requiredApprovalCount": 2,
  "useApiAutoApproval": true,
  "useFeeDelegation": false,
  "feePayerAddress": null,
  "status": "SENT",
  "createdDate": "2023-01-17T08:03:22.476Z",
  "modifiedDate": "2023-01-17T08:03:34.000Z",
  "rejectedDate": null,
  "transaction": {
    "idx": 238694,
    "uuid": "23d2de3e-4cb0-40f7-9341-51b1fb4d81ae",
    "type": "WITHDRAWAL",
    "txid": "7901b93ee393fb26be32165fb9f9146c1e33051d6043426209f9f5be9fd03b51",
    "fromAddress": "TDpz5ZE56QWpx8eWJmsbfqf65tqR2ndrdU",
    "toAddress": "TFumbcWfBRaqp8PXGbuem25GW79J3Z6yTx",
    "amount": "1.00000000000000000000",
    "usedFee": null,
    "nonce": null,
    "blockHeight": null,
    "serialized": "0a85010a027fd322080c095801d142b9b240e8cc88f6db305a67080112630a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412320a15412a526368acc3dde7ce80b9cb8557f6e34b95e8fb121541412a4ce8b3313d31fec3301f840bc674795b29df18c0843d7083fa84f6db301241c852087cb623b56cfebb29c095726e65530fdbf25c07eacef5da22b95490c205f3c8d8655f33357404457f57325957856bc5ac84e9f7829169e64564c93c0c2901",
    "memo": null,
    "status": "PENDING",
    "outputIndex": 0,
    "createdDate": "2023-01-17T08:03:34.138Z",
    "modifiedDate": "2023-01-17T08:03:34.138Z",
    "unfinalizedDate": null,
    "finalizedDate": null,
    "failedDate": null
  },
  "errorCode": null,
  "errorMessage": null
}

3. 웹훅으로 확인하기

대표주소에서 외부로 출금이 완료되면 출금 웹훅이 전송됩니다. 전송된 웹훅으로 출금 여부를 확인할 수 있습니다. 웹훅 이용 방법과 전송되는 데이터 형태는 웹훅 페이지를 참고하세요.






잔액 조회 기준

주소 잔액 조회 API를 호출하면 특정 주소에 보관된 자산의 잔액을 확인할 수 있습니다. 이때 조회되는 잔액은 총 잔액(Total Balance)과 사용 가능 잔액(Liquid Balance)으로 나누어집니다.

  • 총 잔액은 confirmation이 1 이상인 모든 자산을 의미합니다.
  • 사용 가능 잔액은 집금 또는 출금 가능한 자산을 의미합니다. 자식주소의 사용 가능 잔액은 집금 가능한 자산을 의미하며, 대표주소의 사용 가능 잔액은 출금 가능한 자산을 의미합니다.





수수료

Bandwidth Points (BP)

트랜잭션 전송 시 BP를 수수료로 사용합니다. BP는 매일 각 주소에 600BP씩 무료로 지급됩니다. BP가 부족할 경우 자동으로 TRX를 사용하여 수수료를 지불합니다.

BurnedTRX = Bandwidth Consumed x the unit price of Bandwidth

Energy

TRC-20 전송과 같은 트랜잭션 실행 시 energy를 수수료로 사용합니다. Energy가 부족할 경우 자동으로 TRX를 사용하여 수수료를 지불합니다.

BurnedTRX = Energy quantity x the unit price of Energy





Faucet

테스트넷일 경우 Faucet 사이트에서 테스트용 TRX를 얻은 뒤 입금해야 합니다. 테스트넷에 실제 TRX를 입금하면 입금이 인식되지 않습니다.