|
| 1 | +# Wrapped HBAR (WHBAR) |
| 2 | + |
| 3 | +## WHBAR (ERC) in the Hedera Ecosystem |
| 4 | + |
| 5 | +Wrapped HBAR (WHAR) is an ERC-compatible wrapper that follows the ERC20 standard for Hedera's native HBAR token. Built on widely adopted wrapper contract principles, WHBAR makes it easier for developers and users to integrate Hedera’s native token into decentralized applications (dApps). This contract enables users to seamlessly convert HBAR into an ERC20 token and vice versa, making it easier to integrate with the broader web3 and DeFi ecosystems. |
| 6 | + |
| 7 | +*** |
| 8 | + |
| 9 | +## Core Functionalities |
| 10 | + |
| 11 | +* **Deposit & Mint:** |
| 12 | + |
| 13 | + When you call the `deposit()` function and send HBAR, the contract mints an equivalent amount of WHBAR. Each unit of HBAR (represented in tinybars with 8 decimals) is matched with one unit of WHBAR. This ensures that the wrapped token maintains parity with the native token. |
| 14 | +* **Withdraw & Burn:** |
| 15 | + |
| 16 | + To redeem your underlying HBAR, you call the `withdraw(amount)` function. The contract burns the specified WHBAR tokens and releases the corresponding HBAR back to your wallet. This burn mechanism is crucial for maintaining the correct token supply and preserving the peg between HBAR and WHBAR. |
| 17 | +* **ERC20 Standard Compliance:** |
| 18 | + |
| 19 | + WHBAR implements all standard ERC20 functions (e.g., `transfer`, `approve`, `transferFrom`), ensuring seamless interaction with wallets, exchanges, and various DeFi protocols that support ERC20 tokens. |
| 20 | + |
| 21 | +<figure><img src="../../.gitbook/assets/unwrapping-hbar-mermaid.png" alt=""><figcaption><p>HBAR wrapping/unwrapping flow from user wallet</p></figcaption></figure> |
| 22 | + |
| 23 | +*** |
| 24 | + |
| 25 | +## Implementation Guide |
| 26 | + |
| 27 | +Developers can integrate WHBAR into their applications by leveraging the following functions.  |
| 28 | + |
| 29 | +### Wrapping HBAR |
| 30 | + |
| 31 | +To convert HBAR into its ERC20 representation (WHBAR), use the `deposit()` function. Keep in mind that: |
| 32 | + |
| 33 | +* **Native HBAR:** Uses **8** decimal places (**tinybars**). |
| 34 | +* **WHBAR (ERC20):** Uses **8** decimal places (**tinybars**)and _ONLY for deposits_ (wrapping) uses 18 decimal places (weibars). |
| 35 | + |
| 36 | +The conversion from HBAR to WHBAR involves adjusting for these decimal differences. For example, to wrap native HBAR into WHBAR, call `deposit()` and send your HBAR as `msg.value` in weibars (10¹⁸ per HBAR): |
| 37 | + |
| 38 | +{% code overflow="wrap" %} |
| 39 | +```solidity |
| 40 | +/** |
| 41 | + * @notice Deposits HBAR and mints an equivalent amount of WHBAR |
| 42 | + * @dev This is the only supported method for obtaining WHBAR |
| 43 | + */ |
| 44 | +function deposit() public payable { |
| 45 | + // To wrap 10 HBAR into WHBAR |
| 46 | + // Note: 1 HBAR = 10^18 weibars; conversion handles the decimal difference. |
| 47 | + whbarContract.deposit{value: 10 * 10**18}(); |
| 48 | +} |
| 49 | +``` |
| 50 | +{% endcode %} |
| 51 | + |
| 52 | +### Unwrapping WHBAR |
| 53 | + |
| 54 | +When you want to convert back to redeem WHBAR for native HBAR, call the `withdraw()` function with `amount` in **tinybars** (10⁸ per HBAR). The value in WHBAR is directly mapped back to HBAR with the same 8 decimal places: |
| 55 | + |
| 56 | +{% code overflow="wrap" %} |
| 57 | +```solidity |
| 58 | +/** |
| 59 | + * @notice Burns WHBAR tokens and returns the equivalent HBAR |
| 60 | + * @param amount The amount of WHBAR to burn |
| 61 | + */ |
| 62 | +function withdraw(uint256 amount) public { |
| 63 | + // To unwrap 5 WHBAR back to HBAR |
| 64 | + whbarContract.withdraw(5 * 10**8); |
| 65 | +} |
| 66 | +``` |
| 67 | +{% endcode %} |
| 68 | + |
| 69 | +This burns 5 WHBAR and sends back 5 HBAR to the wallet. |
| 70 | + |
| 71 | +{% hint style="success" %} |
| 72 | +#### **Important Note: Decimal Nuance** |
| 73 | + |
| 74 | +When depositing HBAR, remember the conversion nuances between decimal places. |
| 75 | + |
| 76 | +* **Native HBAR & WHBAR Token:** 8 decimals (tinybars).  |
| 77 | +* **RPC `msg.value`:** 18 decimals (weibars).  |
| 78 | + |
| 79 | +Although the `deposit()` function requires input in 18 decimal weibars, WHBAR tokens and all related transfers and balances use 8 decimals, identical to native HBAR in tinybars. |
| 80 | +{% endhint %} |
| 81 | + |
| 82 | +*** |
| 83 | + |
| 84 | +## Standard ERC20 Functions |
| 85 | + |
| 86 | +WHBAR supports all standard ERC20 operations: |
| 87 | + |
| 88 | +<table><thead><tr><th width="145.08203125">Function</th><th width="205.3828125">Description</th><th>Example</th></tr></thead><tbody><tr><td><code>transfer</code></td><td>Send WHBAR directly to another address</td><td><code>whbar.transfer(recipient, amount)</code></td></tr><tr><td><code>approve</code></td><td>Authorize a third party to spend your WHBAR</td><td><code>whbar.approve(spender, amount)</code></td></tr><tr><td><code>transferFrom</code></td><td>Transfer WHBAR as an authorized spender</td><td><code>whbar.transferFrom(owner, recipient, amount)</code></td></tr><tr><td><code>balanceOf</code></td><td>Check WHBAR balance of an address</td><td><code>whbar.balanceOf(address)</code></td></tr><tr><td><code>totalSupply</code></td><td>Get the total amount of WHBAR in circulation</td><td><code>whbar.totalSupply()</code></td></tr></tbody></table> |
| 89 | + |
| 90 | +*** |
| 91 | + |
| 92 | +## Contract Deployments |
| 93 | + |
| 94 | +The WHBAR contract implementation is available on GitHub in the [Hedera Smart Contracts repository](https://github.com/hashgraph/hedera-smart-contracts/blob/main/contracts/wrapped-tokens/WHBAR.sol). |
| 95 | + |
| 96 | +<table><thead><tr><th width="173.6015625">Network</th><th width="146.49609375">Contract ID</th><th>EVM Address</th></tr></thead><tbody><tr><td><strong>✅ Hedera Mainnet</strong></td><td><a href="https://hashscan.io/mainnet/contract/0.0.8840785">0.0.8840785</a></td><td>0xb1F616b8134F602c3Bb465fB5b5e6565cCAd37Ed</td></tr><tr><td><strong>✅ Hedera Testnet</strong></td><td><a href="https://hashscan.io/testnet/contract/0.0.5816542?pa=1&pr=1&ps=1&pf=1">0.0.5816542</a></td><td>0xb1F616b8134F602c3Bb465fB5b5e6565cCAd37Ed</td></tr><tr><td>🔜 <strong>Other Networks</strong></td><td>Coming soon</td><td>Coming soon</td></tr></tbody></table> |
| 97 | + |
| 98 | +_**Source Code:**_ [_WHBAR.sol_](https://github.com/hashgraph/hedera-smart-contracts/blob/main/contracts/wrapped-tokens/WHBAR.sol) |
| 99 | + |
| 100 | +*** |
| 101 | + |
| 102 | +## **Security Considerations: **_**Audit and Testing**_ |
| 103 | + |
| 104 | +* **Audit and Review:**\ |
| 105 | + Although the WHBAR contract has been independently reviewed, developers and users should conduct their own security assessments. Even small oversights in smart contracts may lead to vulnerabilities. |
| 106 | +* **Test in a Sandbox:**\ |
| 107 | + Always test interactions in a testnet environment before deploying or integrating with mainnet contracts. This helps ensure the behavior matches expectations. |
| 108 | +* **Follow Best Practices:**\ |
| 109 | + Double-check function inputs and transaction amounts. Always use the designated functions (`deposit()` and `withdraw()`) to prevent unintended fund loss. |
| 110 | + |
| 111 | +*** |
| 112 | + |
| 113 | +## Integration Best Practices |
| 114 | + |
| 115 | +* **Check allowances**: Before attempting `transferFrom` operations, verify that sufficient allowance has been granted. |
| 116 | +* **Verify contract addresses**: Always double-check you're interacting with the official WHBAR contract addresses listed in the documentation. |
| 117 | +* **Handle decimals properly**: Since both HBAR and WHBAR use 8 decimals, calculations are straightforward. Only for deposits, use 18 decimals to represent weibars. |
| 118 | + |
| 119 | +{% hint style="danger" %} |
| 120 | +**Critical**: HBAR sent directly to the contract address through methods other than the **`deposit()`** function will be permanently locked in the contract due to Hedera’s CryptoTransfer mechanics. |
| 121 | +{% endhint %} |
0 commit comments