Wallet Structure

The custodial wallet of Ethereum has the following structure.

• Main Address
• Fee Address
• Child Address

TIP
The fee address is used to recharge the child address with the fees (ETH) required to gather tokens.

Child Address

Octet supports EOA-type and CA-type child addresses for Ethereum. Each type has a different child-address-generating process and gathering method. One wallet can only generate one type of child address, which can be chosen when generating the wallet.

1. EOA

Generates child addresses by calling the Generate Child Address API. Generally, one child address is given to each end user. Generated child addresses can be checked from [Child Address Information] from the console or by calling the Access Child Address List API.

Response example

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

2. CA

CA-type child addresses should be deployed to the Ethereum network after they are generated. At this point, a deployment fee is charged per child address. You can still deposit to undeployed child addresses, and the deposited assets will be reflected on their balance and deposit history However, it will be excluded from the gathering targets. In other words, assets from child addresses are "only" gathered when they are deployed. During gathering, assets of undeployed child addresses will not be gathered.

Generating CA Child Addresses

Generates child addresses by calling the Generate Child Address API. Generally, one child address is given to each end user. Generated child addresses can be checked from [Child Address Information] from the console or by calling the Access Child Address List API.

Response example

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

Deploying CA Child Addresses

Deployment fee should be paid to deploy CA-type child addresses. The fee will be charged from the fee address. Therefore, you must check the balance of the fee address before deploying child addresses.

1. Deploy from the Console

You can deploy from the console - Select a wallet - [Wallet Information] - [Child Address]. Click the [Deploy] button of the child address to be deployed.

2. Deploy with API

Deploys child addresses by calling the Deploy CA Child Address API. You can check the deployment status by calling the Check CA Child Address Deployment Completion API.

Response example

{
  "result": true
}

Deposit

Deposit Status

When an asset from the outside arrives at the main or a child address, Octet recognizes it as a deposit. However, the deposit is not finalized even if the deposit transaction is included in the blocks. Additional blocks must be generated to finalize(FINALIZED) the transaction to ensure the integrity of the transaction. When an asset is sent to a main or a child address but has not arrived, that transaction is not recognized. Therefore, there is no FAILED status for the deposit transaction.

The number of blocks required to finalize the deposit is different depending on the network. Both testnet and mainnet require additional 20 blocks to finalize the transaction.

Deposit Confirmation

1. Checking from the Console

You can check the deposit status from [Transaction History] on the console. UNFINALIZED deposits are displayed as ‘Processing’, and FINALIZED deposits are displayed as ‘Completed’.

2. Checking with Webhooks

When a deposit is finalized to a main or a child address, a deposit webhook will be sent. You can check the deposit status from the received webhook. For more information about how to use webhooks and their data structure, check the 'Webhook' page.

Gathering

Gathering Process and Fees

Assets stored in child addresses don’t move to the main address unless gathering is requested. Therefore, gatherings should be made regularly to avoid a deficit in the main address. Gathering and charging processes for Ethereum vary depending on the types of the child address and assets.

1. EOA

Gathering ETH

When ETH gathering is requested for EOA-type child addresses, all BNBs or tokens stored in every child address get transferred to the main address. At this point, one transaction occurs per each child address. For example, if ETHs are stored in 10 child addresses, 10 transactions will occur in total.

A gathering fee occurs once for each transaction, and it is deducted from the asset to be gathered. Gathering will not be made for child addresses with assets less than the expected fees. Gathering process is as follows.

1. Request gathering.
2. Generate a transaction for each child addresses to be gathered.
3. Calculates the optimal fees and propagates the transactions.
4. Gathering is completed when transactions are confirmed in the blocks.

Gathering Tokens

When a token gathering is requested for EOA-type child addresses, all assets stored in every child address get transferred to the main address. At this point, one transaction occurs per each child address. For example, if tokens are stored in 10 child addresses, 10 transactions will occur in total. A gathering fee occurs for each transaction.

When there are not enough ETHs in the child address, ETHs in the fee address will be recharged to the child address. A fee (fee-recharging cost) will occur for this process as well. The child address pays the fee with the transferred ETHs and proceeds with the gathering. Gathering process is as follows.

1. Request gathering.
2. Recharge ETHs to pay the fee from the fee address to the child address.
3. Generate a transaction for each child addresses to be gathered.
4. Calculates the optimal fees and propagates the transactions.
5. Gathering is completed when transactions are confirmed in the blocks.

2. CA

Gathering ETH

The gathering will be automatically processed when ETH is deposited to the CA-type child address. No gathering fee occurs. When ETH is deposited to an undeployed child address, it will be gathered automatically after the child address is deployed.

Gathering Tokens

When a token gathering is requested for CA-type child addresses, all assets stored in every child address get transferred to the main address as one transaction. The gathering fee will be deducted from the fee address. Therefore, you must store the fee (ETH) in the fee address before starting the gathering to avoid a deficit in the main address. When a token is deposited to an undeployed child address, it will be gathered automatically after the child address is deployed.

1. Request gathering.
2. Generate a transaction for each child addresses to be gathered.
3. Pays fees from the fee address and propagate the transactions.
4. Gathering is completed when transactions are confirmed in the blocks.

Gathering Status

Gathering status can be specified into seven types, depending on the process. The asset stored in the child address is in AWAITING_GATHERING status.

When it needs a recharging of fees for the gathering, the status of the asset changes to AWAITING_FEE_INJECTION. When the fee transfer transaction is generated, the status of the asset changes to FEE_INJECTING. When it fails to recharge the fee, the status of the asset is processed to FEE_INJECTION_FAILED.

When the fee transfer is successful and generates a gathering transaction, the asset status changes to GATHERING. When the transaction is included in the blocks, the status of the asset is processed to COMPLETED and finishes the gathering.

When a gathering is tried and failed, the status of the asset remains as GATHERING_FAILED. Assets with a status of fee injection failed or gathering failed are included in the gathering target again. When a gathering is tried but failed to generate a transaction due to insufficient fees, it remains in AWAITING_GATHERING status.

Gather

Transfers the assets stored in the child address to the main address. Gatherings can be processed by one of the following two methods.

1. Gathering from the Console

You can gather from Console - Select a wallet - [Gathering History]. Click the [Gather] button, check the assets and the amount to gather, then proceed with the gathering.

2. Gathering with API

The gathering will be processed by calling the Request Gathering API.

Response example

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

Gathering Status Confirmation

1. Checking from the Console

You can check the gathering history from Select a wallet - [Gathering History] - [Gathering History].

2. Checking with API

You can check the gathering history by calling the Access Gathering Request Information API.

Response example

{
  "idx": 75,
  "status": "COMPLETED",
  "uuid": "061c3807-704a-477e-8a69-21bbfb71b16f",
  "createdDate": "2022-01-03T09:50:40.371Z",
  "modifiedDate": "2022-01-03T09:52:00.000Z",
  "coin": {
    "idx": 2,
    "symbol": "ETH",
    "nameKo": "이더리움",
    "nameEn": "Ethereum",
    "status": "ACTIVATED",
    "type": "DEFAULT",
    "contractAddress": null,
    "decimals": 18,
    "createdDate": "2021-09-20T07:41:22.042Z",
    "modifiedDate": "2021-12-23T07:07:48.272Z"
  },
  "feeInjectionTransaction": null,
  "feeInjectionFee": null,
  "gatheringTransaction": {
    "idx": 9013,
    "uuid": "78ac42ae-1624-48e1-a22e-b9f74a627934",
    "type": "GATHERING",
    "txid": "0xf51f75ca0276877d851af598d92e8bdab4d99d034b8c11ee967eaf38aad5f179",
    "fromAddress": "0x61Cb7bbc6Ca8FF2502ad7163059E57e962a1776B",
    "toAddress": "0x71b5De2970A32eEf6362AE7Bc3B73103b4392bB0",
    "amount": "0.00003700000000000000",
    "usedFee": "0.00002100000014700000",
    "nonce": 0,
    "blockHeight": "6135121",
    "serialized": null,
    "memo": null,
    "status": "FINALIZED",
    "outputIndex": null,
    "createdDate": "2022-01-03T09:51:00.797Z",
    "modifiedDate": "2022-01-03T09:52:00.000Z",
    "unfinalizedDate": "2022-01-03T09:52:00.000Z",
    "finalizedDate": "2022-01-03T09:52:00.000Z",
    "failedDate": null,
    "coin": {
      "idx": 2,
      "symbol": "ETH",
      "nameKo": "이더리움",
      "nameEn": "Ethereum",
      "status": "ACTIVATED",
      "type": "DEFAULT",
      "contractAddress": null,
      "decimals": 18,
      "createdDate": "2021-09-20T07:41:22.042Z",
      "modifiedDate": "2021-12-23T07:07:48.272Z"
    }
  },
  "gatheringFee": {
    "idx": 184,
    "gasLimit": "21000.00000000000000000000",
    "gasPrice": "2.00000000000000000000",
    "unit": "gwei",
    "createdDate": "2022-01-03T09:50:40.369Z",
    "modifiedDate": "2022-01-03T09:50:40.369Z"
  }
}

3. Checking with Webhooks

When the gathering to the main address is finished, a gathering webhook will be sent. You can check the gathering status from the webhook. For more information about how to use webhooks and their data structure, check the 'Webhook' page.

Withdrawal

Withdrawal Process

Assets must be withdrawn from the main address to transfer them from a custodial wallet to the outside. An asset cannot be transferred outside from the child address.

1. Request withdrawal.
2. Generate transaction.
3. Calculates the optimal fees and propagates the transactions.
4. Withdrawal is completed when the transactions are confirmed in the blocks.

Withdrawal Status

Unlike a deposit, a withdrawal is finalized(FINALIZED) at the moment when the transaction is included in the blocks.

Withdraw

You can request a withdrawal from the main address to the outside by calling the Request Withdrawal API. The uuid value will be returned when the withdrawal request is successful. The value can be used to access the withdrawal process.

Response example

{
  "uuid": "18012e3f-07f3-45ec-862b-f020c0ca935a"
}

Withdrawal Confirmation

1. Checking from the Console

You can check the withdrawal status from [Transaction History] on the console. AWAITING_WITHDRAWAL or PENDING withdrawals are displayed as ‘Processing’, and FINALIZED withdrawals are displayed as ‘Completed’.

2. Checking with API

You can check the progress of a specific withdrawal transaction by calling the Access Withdrawal Transaction Information API.

Response example

{
  "idx": 490,
  "uuid": "07efdcb2-b3fd-4fe7-bf47-c0b460b289e3",
  "fromAddress": "0x71b5De2970A32eEf6362AE7Bc3B73103b4392bB0",
  "toAddress": "0x295909dC67B76f936BD4119aDd877088602cCaD3",
  "amount": "2.00000000000000000000",
  "memo": null,
  "requestId": "25",
  "type": "API",
  "description": "",
  "requiredApprovalCount": 1,
  "useApiAutoApproval": true,
  "status": "SENT",
  "createdDate": "2022-01-25T09:25:02.383Z",
  "modifiedDate": "2022-01-25T09:25:10.000Z",
  "rejectedDate": null
}

3. Checking with Webhooks

When the withdrawal from the main address is finished, a withdrawal webhook will be sent. You can check the withdrawal status from the webhook. For more information about how to use webhooks and their data structure, check the Webhook page.

Balance Access Criteria

You can check the balance of the asset stored in a specific address by calling the Access Address Balance API. The accessed balances are specified into total balances and liquid balances.

• Total balance is all assets with a confirmation of 1 or above.
• Liquid balance only reflects the assets in finalized status. The liquid balance of a child address represents the assets that can be gathered, while the liquid balance of the main address represents the assets that can be withdrawn.

Fees

Estimated Fees

Estimated fees are calculated by multiplying the gas limit and the gas price.

Estimated Fees = Gas Limit x Max Fee Per Gas

• Gas Limit is the maximum gas usage. Octet sets Ethereum gas limit to 21,000, and the gas limit for tokens is set to 100,000 since it varies depending on how the tokens are implemented. The actual gas usage could be less than that, and the fees are charged for the actual gas usage.
• Max Fee Per Gas is the maximum value of the fee per gas. You can access the value in real-time by calling the Fee/Gas API. Actual fee per gas could be less than that.

Transaction Fees

Transaction Fees are calculated by multiplying the gas usage and the gas price.

Transaction Fees = Usage by Txn x Gas Price

• Gas Price includes the fee paid to the miner, Max Priority Fee Per Gas. Octet sets the value to 1 Gwei.

Faucet

In the case of the testnet, you must obtain a testing ETH from the faucet website and deposit it. When an actual ETH is deposited in the testnet, it will not be recognized.