hiero-ledger · simzzz · May 28, 2026 · May 14, 2026
@@ -6,16 +6,34 @@ Reference library for Smart Contracts utilized on the Hiero network with support
 
 ## Overview
 
-The Hiero network utilizes system contracts at a reserved contract address on the EVM to surface HAPI service functionality through EVM processed transactions.
+The Hiero network utilizes system contracts at reserved contract addresses on the EVM to surface HAPI (Hiero API) service functionality through EVM processed transactions.
 These system contracts are precompiled smart contracts whose function selectors are mapped to defined network logic.
 In this way EVM users can utilize exposed HAPI features natively in their smart contracts.
 
 The system contract functions are defined in this library and implemented by the [Hiero consensus node](https://github.com/hiero-ledger/hiero-consensus-node) repository as part of consensus node functionality.
 
+## System Contracts
+
+A **system contract** is not deployed bytecode — it is native consensus node logic exposed at a fixed EVM address. When a contract (or an externally owned account) calls one of these addresses, the node intercepts the call, decodes the function selector and arguments, executes the corresponding HAPI operation, and returns the result like any other contract call. This lets Solidity developers create tokens, manage allowances, schedule transactions, read exchange rates, and generate randomness without leaving the EVM.
+
+Every system contract function returns an `int64 responseCode` drawn from [`HederaResponseCodes.sol`](contracts/common/HederaResponseCodes.sol) (`SUCCESS` is `22`). Many services also expose **facade** (proxy / redirect) functions that let an externally owned account (EOA) call the service directly — for example by calling a token or schedule address — without first deploying a contract.
+
+The following system contracts are available on the Hiero network. Each links to a dedicated reference that lists every function, its selector hash, the consensus node release that introduced it, and the governing HIP.
+
+| System Contract | Address | Purpose | Defining HIPs | Reference |
+|---|---|---|---|---|
+| Hiero Token Service (HTS) | `0x167` | Create, manage, transfer, and query fungible tokens and NFTs; allowances; airdrops; KYC and freeze controls. | [206](https://hips.hedera.com/hip/hip-206), [218](https://hips.hedera.com/hip/hip-218), [358](https://hips.hedera.com/hip/hip-358), [376](https://hips.hedera.com/hip/hip-376), [514](https://hips.hedera.com/hip/hip-514), [719](https://hips.hedera.com/hip/hip-719), [904](https://hips.hedera.com/hip/hip-904) | [HTS System Contract Methods](contracts/token-service/README.md) |
+| Hiero Account Service (HAS) | `0x16a` | HBAR allowances, account/EVM address alias resolution, and signature verification (`isAuthorized`/`isAuthorizedRaw`). | [583](https://hips.hedera.com/hip/hip-583), [632](https://hips.hedera.com/hip/hip-632), [904](https://hips.hedera.com/hip/hip-904), [906](https://hips.hedera.com/hip/hip-906) | [HAS System Contract Methods](contracts/account-service/README.md) |
+| Hiero Schedule Service (HSS) | `0x16b` | Create, sign, authorize, query, and delete scheduled transactions, including scheduled native contract calls. | [755](https://hips.hedera.com/hip/hip-755), [756](https://hips.hedera.com/hip/hip-756), [1215](https://hips.hedera.com/hip/hip-1215) | [HSS System Contract Methods](contracts/schedule-service/README.md) |
+| Exchange Rate | `0x168` | Convert between tinycents (USD) and tinybars (HBAR) at the active network exchange rate. | [475](https://hips.hedera.com/hip/hip-475) | [Exchange Rate System Contract Methods](contracts/exchange-rate/README.md) |
+| PRNG | `0x169` | Generate a pseudo-random 32-byte seed from the network. | [351](https://hips.hedera.com/hip/hip-351) | [PRNG System Contract Methods](contracts/prng/README.md) |
+
 ## Backward Compatibility
 
 This repository targets the **Hiero** ecosystem. Documentation and project naming use **Hiero** throughout. However, the **Solidity public API** intentionally retains **Hedera-prefixed** identifiers for backward compatibility with existing contracts and tooling.
 
+## System Contract Details
+
 ### Hiero Token Service (HTS) System Contract
 
 The Hiero Token Service (HTS) functionality is defined by the [IHederaTokenService.sol](contracts/token-service/IHederaTokenService.sol) interface smart contract as defined in [HIP 206](https://hips.hedera.com/hip/hip-206), [HIP 376](https://hips.hedera.com/hip/hip-376) and [HIP 514](https://hips.hedera.com/hip/hip-514).
@@ -31,6 +49,14 @@ Reference smart contracts to call these functions as well as examples can be fou
 
 For further details on methods, hashes and availability please refer to [HAS System Contract Methods](contracts/account-service/README.md)
 
+### Hiero Schedule Service (HSS) System Contract
+
+The Hiero Schedule Service (HSS) functionality is defined by the [IHederaScheduleService.sol](contracts/schedule-service/IHederaScheduleService.sol) interface smart contract and its `IHRC755`, `IHRC756`, and `IHRC1215` extensions, as defined in [HIP 755](https://hips.hedera.com/hip/hip-755), [HIP 756](https://hips.hedera.com/hip/hip-756) and [HIP 1215](https://hips.hedera.com/hip/hip-1215). The contract is exposed via the `0x16b` address.
+HSS lets contracts and EOAs create scheduled transactions (including scheduled native contract calls), authorize and sign them, query scheduled token-create info, and delete schedules.
+Reference smart contracts to call these functions can be found under [contracts/schedule-service](contracts/schedule-service)
+
+For further details on methods, hashes and availability please refer to [HSS System Contract Methods](contracts/schedule-service/README.md)
+
 ### Exchange Rate System Contract
 
 The Exchange Rate functionality is defined by the [IExchangeRate.sol](contracts/exchange-rate/IExchangeRate.sol) interface smart contract as defined in [HIP 475](https://hips.hedera.com/hip/hip-475) and exposed via the `0x168` address.

@@ -1,20 +1,40 @@
 ## Hiero Account Service (HAS) System Contract Functions
 
-The Hiero Account Service (HAS) System Contract is accessible at address `0x16a` on the Hiero network. This contract interface introduces a new account proxy contract to interact with other contracts for functionality such as HBAR allowances. It enables querying and granting HBAR approval to a spender account from within smart contracts, allowing developers to grant, retrieve, and manage HBAR allowances directly in their code. Additionally, HAS can verify whether a given address (Hiero account or EVM address) is authorized based on a provided message hash and signature through the `isAuthorizedRaw` method.
+The Hiero Account Service (HAS) System Contract is accessible at address `0x16a` on the Hiero network. This contract interface introduces a new account proxy contract to interact with other contracts for functionality such as HBAR allowances. It enables querying and granting HBAR approval to a spender account from within smart contracts, allowing developers to grant, retrieve, and manage HBAR allowances directly in their code. HAS also resolves between Hiero account-num aliases and EVM address aliases ([HIP 632](https://hips.hedera.com/hip/hip-632)), and can verify whether a given address (Hiero account or EVM address) is authorized for a message and signature through the `isAuthorized` and `isAuthorizedRaw` methods.
+
+The HAS interface is defined by [`IHederaAccountService.sol`](IHederaAccountService.sol), with HIP-specific extension interfaces [`IHRC632.sol`](IHRC632.sol) (alias resolution and signature verification) and [`IHRC906.sol`](IHRC906.sol) (HBAR allowances). The abstract [`HederaAccountService.sol`](HederaAccountService.sol) contract provides ready-to-use wrappers around each call.
 
 The table below outlines the available Hiero Account Service System Contract functions:
 
-| Function Name     | Function Selector Hash | Consensus Node Release Version                                                       | HIP                                            | Method Interface                                                           |
-|-------------------|------------------------|--------------------------------------------------------------------------------------|------------------------------------------------|----------------------------------------------------------------------------|
-| `hbarAllowance`   | `0xbbee989e`           | [0.52](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.52) | [HIP 906](https://hips.hedera.com/hip/hip-906) | `hbarAllowance(address spender)`                                           |
-| `hbarApprove`     | `0x86aff07c`           | [0.52](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.52) | [HIP 906](https://hips.hedera.com/hip/hip-906) | `hbarApprove(address spender, int256 amount)`                              |
-| `isAuthorizedRaw` | `0xb2a31da4`           | [0.52](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.52) | [HIP 632](https://hips.hedera.com/hip/hip-632) | `isAuthorizedRaw(address, bytes /*messageHash*/, bytes /*signatureBlob*/)` |
-| `isAuthorized`    | `0xb2526367`           | [0.56](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.56) | [HIP 632](https://hips.hedera.com/hip/hip-632) | `isAuthorizedRaw(address, bytes /*messageHash*/, bytes /*signatureBlob*/)` |
+| Function Name              | Function Selector Hash | Consensus Node Release Version                                                       | HIP                                            | Method Interface                                                                                          |
+|----------------------------|------------------------|--------------------------------------------------------------------------------------|------------------------------------------------|------------------------------------------------------------------------------------------------------------|
+| `hbarAllowance`            | `0xfec46666`           | [0.52](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.52) | [HIP 906](https://hips.hedera.com/hip/hip-906) | `hbarAllowance(address owner, address spender) external returns (int64 responseCode, int256 amount)`        |
+| `hbarApprove`              | `0xa0918464`           | [0.52](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.52) | [HIP 906](https://hips.hedera.com/hip/hip-906) | `hbarApprove(address owner, address spender, int256 amount) external returns (int64 responseCode)`          |
+| `getEvmAddressAlias`       | `0xdea3d081`           | [0.54](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.54) | [HIP 632](https://hips.hedera.com/hip/hip-632) | `getEvmAddressAlias(address accountNumAlias) external returns (int64 responseCode, address evmAddressAlias)` |
+| `getHederaAccountNumAlias` | `0xbbf12d2e`           | [0.54](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.54) | [HIP 632](https://hips.hedera.com/hip/hip-632) | `getHederaAccountNumAlias(address evmAddressAlias) external returns (int64 responseCode, address accountNumAlias)` |
+| `isValidAlias`             | `0x308ef301`           | [0.54](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.54) | [HIP 632](https://hips.hedera.com/hip/hip-632) | `isValidAlias(address addr) external returns (int64 responseCode, bool response)`                          |
+| `isAuthorizedRaw`          | `0xb2a31da4`           | [0.52](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.52) | [HIP 632](https://hips.hedera.com/hip/hip-632) | `isAuthorizedRaw(address account, bytes memory messageHash, bytes memory signature) external returns (int64 responseCode, bool authorized)` |
+| `isAuthorized`             | `0xb2526367`           | [0.56](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.56) | [HIP 632](https://hips.hedera.com/hip/hip-632) | `isAuthorized(address account, bytes memory message, bytes memory signature) external returns (int64 responseCode, bool authorized)` |
 
-The Hiero network also makes facade contract calls available to EOAs for improved experience.
-Facade function allow for EOAs to make calls without requiring a deployed contract
+The Hiero network also makes facade contract calls available to EOAs for an improved experience.
+Facade functions allow EOAs to make calls without requiring a deployed contract — the EOA calls its own account address directly.
 The table below outlines the available Hiero Account Service (HAS) System Contract facade functions:
 
-| Function Name                          | Function Selector Hash | Consensus Node Release Version                                                        | HIP                                            | Method Interface                                                                                       | Comments |
-|----------------------------------------|------------------------|---------------------------------------------------------------------------------------|------------------------------------------------|--------------------------------------------------------------------------------------------------------|----------|
-| `setUnlimitedAutomaticAssociations`    | `0xf5677e99`           | [0.56](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.56)  | [HIP 904](https://hips.hedera.com/hip/hip-904) | `setUnlimitedAutomaticAssociations(bool enableAutoAssociations) external returns (int64 responseCode)` |          |
+| Function Name                       | Function Selector Hash | Consensus Node Release Version                                                       | HIP                                            | Method Interface                                                                                       | Defining Interface                                       |
+|-------------------------------------|------------------------|--------------------------------------------------------------------------------------|------------------------------------------------|--------------------------------------------------------------------------------------------------------|----------------------------------------------------------|
+| `hbarAllowance`                     | `0xbbee989e`           | [0.52](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.52) | [HIP 906](https://hips.hedera.com/hip/hip-906) | `hbarAllowance(address spender) external returns (int64 responseCode, int256 amount)`                  | [`IHRC906AccountFacade.sol`](IHRC906AccountFacade.sol)   |
+| `hbarApprove`                       | `0x86aff07c`           | [0.52](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.52) | [HIP 906](https://hips.hedera.com/hip/hip-906) | `hbarApprove(address spender, int256 amount) external returns (int64 responseCode)`                    | [`IHRC906AccountFacade.sol`](IHRC906AccountFacade.sol)   |
+| `setUnlimitedAutomaticAssociations` | `0xf5677e99`           | [0.56](https://docs.hedera.com/hedera/networks/release-notes/services#release-v0.56) | [HIP 904](https://hips.hedera.com/hip/hip-904) | `setUnlimitedAutomaticAssociations(bool enableAutoAssociations) external returns (int64 responseCode)` | [`IHRC904AccountFacade.sol`](IHRC904AccountFacade.sol)   |
+
+### Function Notes
+
+- **`hbarAllowance`** — Returns the amount of HBAR the `spender` has been authorized to spend on behalf of the `owner`.
+- **`hbarApprove`** — Authorizes `spender` to withdraw HBAR from the `owner` account up to `amount`. Calling it again overwrites the current allowance.
+- **`getEvmAddressAlias`** — Returns the EVM address alias for a given Hiero account-num alias.
+- **`getHederaAccountNumAlias`** — Returns the Hiero account-num alias for a given EVM address alias.
+- **`isValidAlias`** — Returns `true` if the address is a Hiero account-num alias or an EVM address alias.
+- **`isAuthorizedRaw`** — Verifies a signature for a message *hash* against an account. The signature must be a single ECDSA or ED25519 key, providing logic similar to `ECRECOVER`.
+- **`isAuthorized`** — Verifies a signature for a *message* against an account, supporting possibly complex (multi-key) account key structures via a protobuf-encoded signature blob.
+- **`setUnlimitedAutomaticAssociations`** — Enables or disables unlimited automatic token associations for the calling account.
+
+All functions return an `int64 responseCode` (`SUCCESS` is `22`) from [`HederaResponseCodes.sol`](../common/HederaResponseCodes.sol).
@@ -1,9 +1,11 @@
 ## Exchange Rate System Contract Functions
 
-The Exchange Rate System Contract is accessible at address `0x168` on the Hiero network. This contract interface provides methods for retrieving and managing exchange rates between HBAR and US dollars.
+The Exchange Rate System Contract is accessible at address `0x168` on the Hiero network. It exposes the network's active HBAR-to-USD exchange rate to the EVM, letting contracts convert between **tinycents** (1e-8 US cents) and **tinybars** (1e-8 HBAR). The rate is the same one the network uses to price transaction fees — read from system file `0.0.112` — so a "self-funding" contract can use it to compute how much HBAR a caller must send to cover fees. It is **not** a live price oracle and should not be treated as one.
+
+The interface is defined by [`IExchangeRate.sol`](IExchangeRate.sol).
 
 The table below outlines the available methods in the Exchange Rate System Contract:
 | Function Name | Function Selector Hash | Consensus Node Release Version | HIP | Method Interface |
-| --------------------- | ------------ | ---------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------ |
-| `tinycentsToTinybars` | `0x2e3cff6a` | [0.26](https://docs.hedera.com/hedera/networks/release-notes/services#v0.26) | [HIP 475](https://hips.hedera.com/hip/hip-475) | `tinycentsToTinybars(uint256)` |
-| `tinybarsToTinycents` | `0x43a88229` | [0.26](https://docs.hedera.com/hedera/networks/release-notes/services#v0.26) | [HIP 475](https://hips.hedera.com/hip/hip-475) | `tinybarsToTinycents(uint256)` |
+| --------------------- | ------------ | ---------------------------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
+| `tinycentsToTinybars` | `0x2e3cff6a` | [0.26](https://docs.hedera.com/hedera/networks/release-notes/services#v0.26) | [HIP 475](https://hips.hedera.com/hip/hip-475) | `tinycentsToTinybars(uint256 tinycents) external returns (uint256 tinybars)` |
+| `tinybarsToTinycents` | `0x43a88229` | [0.26](https://docs.hedera.com/hedera/networks/release-notes/services#v0.26) | [HIP 475](https://hips.hedera.com/hip/hip-475) | `tinybarsToTinycents(uint256 tinybars) external returns (uint256 tinycents)` |