Reference implementation of xGAS, a wrapped native asset combining standard ERC-20 behavior with permit and authorization-based transfer extensions.

This repository contains the canonical Solidity implementation of xGAS and its supporting extension layers.

The implementation is designed to keep standard-shaped entrypoints explicit and place encoded-signature behavior in additive extension contracts. The goal is predictable integration behavior for wallets, DeFi protocols, relayers, and auditor workflows.

All extension behavior is explicitly additive and does not modify the semantics of standard entrypoints.

xGAS is designed as a minimal, immutable base asset.

• Standard entrypoints remain canonical and unmodified
• Extension functionality is strictly additive and isolated
• The contract does not embed assumptions about execution environments

The exposed primitives support off-chain authorization and third-party execution patterns (e.g. relayers or agent-based systems) without coupling to any specific framework or protocol.

xGAS combines three concerns in one composed token:

• Wrapped native asset behavior (deposit and withdraw)
• Standard permit and transfer authorization entrypoints
• Encoded-signature / ERC-1271-capable entrypoints

The architecture separates these responsibilities across base and extension contracts instead of mixing all logic into one monolith.

The architecture ensures that standard entrypoints remain unchanged while extension functionality is explicitly opt-in.

Inheritance in the final token composition:

XGAS
├── WrappedNative
│   └── ERC20Permit1271
│       └── ERC20Permit
└── TransferAuth
    └── EIP3009

Functional ownership:

• XGAS: final composition and token-movement hook wiring
• WrappedNative / ERC20Permit1271: token + permit path
• EIP3009 / TransferAuth: authorization-based transfer path

Standard vs extension boundaries:

• ERC20Permit keeps the classic ERC-2612 (v, r, s) permit path
• ERC20Permit1271 adds an encoded-signature permit path (additive extension)
• EIP3009 keeps the classic (v, r, s) authorization path
• TransferAuth adds encoded-signature authorization entrypoints (additive extension)

The final token composition uses a single EIP-712 domain provided by the permit path (ERC20Permit).

• ERC20Permit1271 reuses typed-data hashing from the inherited permit path
• EIP3009 and TransferAuth consume typed-data hashing through composition hooks and do not own a separate EIP-712 base

Token metadata:

• Name: Extended GAS
• Symbol: xGAS
• Decimals: 18

• docs/architecture.md — contract structure and composition details
• docs/audit.md — review order and audit checkpoints
• docs/security-considerations.md — integrator-facing security and operational guidance

src/
  extensions/
  interfaces/
  token/
test/
script/
  deploy/
ops/
  common/

Environment:

cp .env.example .env

Set RPC_URL and PRIVATE_KEY in .env. You can map RPC_URL to any local network-specific variable name.

Build:

forge build

Test:

forge test --offline

Format:

forge fmt

The deployment scripts use the network selected by RPC_URL and resolve the deployment configuration from block.chainid.

Neo X Mainnet and Neo X Testnet use configured salts and expected addresses. Other networks use a default deterministic salt for local development and ad-hoc testing, without an expected-address assertion.

Predict script (read-only):

• Computes the deterministic xGAS address for the selected network
• Uses the same chain-aware deployment configuration as the deploy script
• No private key required
• No state changes

forge script script/deploy/PredictXGAS.s.sol:PredictXGASScript \
  --rpc-url "$RPC_URL"

Deploy script (broadcast):

• Deploys xGAS for the selected network
• Requires a funded account and private key
• Reverts if the contract already exists at the predicted address
• On Neo X Mainnet and Neo X Testnet, reverts if the predicted address does not match the configured expected address

forge script script/deploy/DeployXGAS.s.sol:DeployXGASScript \
  --rpc-url "$RPC_URL" \
  --private-key "$PRIVATE_KEY" \
  --broadcast

Apache-2.0. See LICENSE.