XCN Decimal Handling

Detailed guidance for handling native XCN amounts correctly across Solidity, JSON-RPC, wallets, and frontend code.

Critical Difference

Native XCN does not use the same decimal scale everywhere.

• Inside Solidity and the EVM, native value uses 8 decimals in tinyxcn

• Across Ethereum-compatible JSON-RPC tooling, native value is exposed with 18-decimal scaling

• 1 tinyxcn = 10^10 RPC-scaled units

If you port code from Ethereum and keep 1 ether, 1e18, or "wei everywhere" assumptions for the native currency, you will introduce incorrect pricing, payment checks, and balance math.

At a Glance

Context	Unit / Scale	Decimals	Examples
Solidity / EVM execution	tinyxcn	8	msg.value, address(this).balance, transfer, send, call{value: ...}
JSON-RPC and wallets	18-decimal native amount	18	eth_getBalance, provider.getBalance, transaction value, gasPrice, maxFeePerGas
ERC-20 token balances	Token-defined	Usually 18, but not guaranteed	balanceOf, transfer, decimals()

The 8-vs-18 rule applies to the native currency only. Do not apply the 10^10 conversion factor to ERC-20 tokens.

Conversion Rule

For native XCN:

1 XCN      = 100,000,000 tinyxcn = 10^8 tinyxcn
1 XCN      = 1,000,000,000,000,000,000 RPC units = 10^18
1 tinyxcn  = 10,000,000,000 RPC units = 10^10

That gives you the two conversions you need:

rpcAmount   = tinyxcnAmount * 10^10
tinyxcn     = rpcAmount / 10^10

What This Means in Practice

Inside contracts: always think in tinyxcn

When Solidity code handles native value, the amount is always in tinyxcn:

• msg.value

• address(this).balance

• payable(addr).transfer(amount)

• payable(addr).send(amount)

• payable(addr).call{value: amount}("")

1 XCN inside a contract is:

uint256 constant ONE_XCN = 1e8;

Not:

uint256 constant ONE_XCN = 1e18; // Wrong for native XCN in Solidity

Outside contracts: JSON-RPC uses 18-decimal scaling

Wallets, libraries, and RPC endpoints expose native balances and transaction value in the familiar 18-decimal Ethereum format:

const oneXcnForRpc = ethers.parseEther("1");
// 1000000000000000000n

That value arrives inside the contract as:

msg.value == 100000000; // 1 XCN in tinyxcn

Your own function parameters are application-defined

If you write a function like deposit(uint256 amount) or quote(uint256 amount), the chain does not reinterpret that integer for you. You must choose the unit and document it.

For native-value APIs, the safest convention is:

• Accept native amounts in tinyxcn

• Name them clearly, for example amountTinyxcn

• Emit events with unit names in the field names

Solidity Patterns

Use explicit constants

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

contract XcnConstants {
    uint256 internal constant XCN_DECIMALS = 8;
    uint256 internal constant ONE_XCN = 10 ** XCN_DECIMALS; // 1e8
    uint256 internal constant HALF_XCN = ONE_XCN / 2;       // 0.5 XCN
    uint256 internal constant MIN_FEE = ONE_XCN / 100;      // 0.01 XCN
}

Do not use:

• 1 ether

• 0.1 ether

• 1e18

• any hardcoded "wei-style" native constants copied from Ethereum contracts

Payable checks

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

contract Vault {
    uint256 internal constant ONE_XCN = 1e8;
    uint256 internal constant MIN_DEPOSIT = ONE_XCN / 10; // 0.1 XCN

    mapping(address => uint256) public deposits;

    function deposit() external payable {
        require(msg.value >= MIN_DEPOSIT, "Minimum 0.1 XCN");
        deposits[msg.sender] += msg.value; // msg.value is tinyxcn
    }
}

Event naming should include units

event DepositRecorded(address indexed account, uint256 amountTinyxcn);
event WithdrawalRecorded(address indexed account, uint256 amountTinyxcn);

Avoid ambiguous fields like amount if the surrounding code also deals with 18-decimal RPC values off-chain.

Receiving XCN in Contracts

Solidity receive and fallback behavior works as EVM developers expect when the value transfer goes through the EVM path.

If native XCN is sent to a contract through an EVM contract call:

• receive() runs when calldata is empty

• fallback() runs when calldata does not match a function selector and the fallback is payable

Example:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

contract XcnReceiver {
    event XcnReceived(address indexed sender, uint256 amountTinyxcn);

    receive() external payable {
        emit XcnReceived(msg.sender, msg.value);
    }

    fallback() external payable {
        emit XcnReceived(msg.sender, msg.value);
    }
}

Directly crediting a contract account outside the EVM does not execute contract logic. If your application depends on receive(), fallback(), accounting updates, or access checks, users must send XCN through an EVM transaction that targets the contract.

This distinction matters for:

• deposit contracts that credit balances on receipt

• escrow contracts that must validate senders

• accounting contracts that emit events when funds arrive

• upgradeable systems that depend on payable entrypoints

If the business logic must run, expose an explicit payable function such as deposit() and route users there.

Sending XCN From Contracts

The usual Solidity mechanisms are supported:

• transfer()

• send()

• call{value: ...}("")

Example:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

contract XcnPayout {
    event Paid(address indexed to, uint256 amountTinyxcn);

    function payWithTransfer(address payable to, uint256 amountTinyxcn) external {
        to.transfer(amountTinyxcn);
        emit Paid(to, amountTinyxcn);
    }

    function payWithSend(address payable to, uint256 amountTinyxcn) external {
        bool ok = to.send(amountTinyxcn);
        require(ok, "XCN send failed");
        emit Paid(to, amountTinyxcn);
    }

    function payWithCall(address payable to, uint256 amountTinyxcn) external {
        (bool ok, ) = to.call{value: amountTinyxcn}("");
        require(ok, "XCN call failed");
        emit Paid(to, amountTinyxcn);
    }
}

For modern Solidity code, call is generally the most flexible choice. Whatever transfer mechanism you use, the amountTinyxcn parameter is still an 8-decimal native amount.

Frontend and RPC Guidance

Sending 1.5 XCN from a dApp

const value = ethers.parseEther("1.5");

await contract.deposit({
  value,
});

The transaction is submitted through RPC using 18-decimal scaling, but the contract receives:

msg.value == 150000000; // 1.5 XCN in tinyxcn

Reading balances

const rpcBalance = await provider.getBalance(contractAddress);
const xcn = ethers.formatEther(rpcBalance);
const tinyxcn = rpcBalance / 10n ** 10n;

• rpcBalance is the 18-decimal RPC value

• xcn is the human-readable XCN string

• tinyxcn matches what Solidity would see from address(contractAddress).balance

Recommended utility helpers

import { ethers } from "ethers";

const RPC_NATIVE_FACTOR = 10n ** 10n;

export function tinyxcnToRpcAmount(amountTinyxcn) {
  return BigInt(amountTinyxcn) * RPC_NATIVE_FACTOR;
}

export function rpcAmountToTinyxcn(rpcAmount) {
  return BigInt(rpcAmount) / RPC_NATIVE_FACTOR;
}

export function formatTinyxcn(amountTinyxcn) {
  return ethers.formatUnits(amountTinyxcn, 8);
}

export function parseXcnForRpc(xcn) {
  return ethers.parseEther(xcn);
}

Use BigInt, not JavaScript Number, for raw amounts.

Example: Same Balance, Two Representations

Assume an account holds 9,000,099.81460509 XCN.

Inside Solidity:

uint256 balanceTinyxcn = address(this).balance;
// 900009981460509

Via JSON-RPC:

const balanceRpc = await provider.getBalance(address);
// 9000099814605090000000000n

The ratio is exactly 10^10.

ERC-20 and Other Token Amounts

Do not generalize native XCN rules to token contracts.

• ERC-20 amounts use the token's own decimals() setting

• Many ERC-20 tokens use 18 decimals, but not all do

• NFT standards do not use this native-value conversion model

• The 10^10 factor is only for converting native XCN between Solidity/EVM and JSON-RPC representations

Testing Guidance

A good test should assert both views of the same transfer:

it("keeps RPC and contract views aligned", async function () {
  await vault.deposit({ value: ethers.parseEther("1") });

  const onChainBalanceTinyxcn = await vault.totalHeld();
  expect(onChainBalanceTinyxcn).to.equal(100_000_000n);

  const rpcBalance = await ethers.provider.getBalance(await vault.getAddress());
  expect(rpcBalance).to.equal(ethers.parseEther("1"));
});

Also search migrated contracts for:

• ether

• 1e18

• parseEther values compared directly against contract-side amounts

• event names that hide units

• comments claiming msg.value is 18 decimals

Migration Checklist

• Replace native ether constants with tinyxcn constants

• Audit every msg.value check

• Audit every address.balance comparison

• Standardize off-chain conversion helpers

• Name native-amount variables with Tinyxcn suffixes when possible

• Ensure payable flows go through an EVM contract call if contract logic must execute

• Add tests that compare RPC values and contract-side values for the same transfer

Summary

Use these rules and the decimal mismatch becomes manageable:

• Solidity native value is always tinyxcn with 8 decimals

• JSON-RPC native value is exposed with 18-decimal scaling

• 1 tinyxcn = 10^10 RPC units

• receive() and fallback() only run when value enters through the EVM path

• ERC-20 token decimals are separate from native XCN handling

Related Pages

• Deploying Contracts

• Lazy Account Creation (Gas Requirements)

• Getting Started

• EVM JSON-RPC API