Protocol Reference

1 · Overview

Eternal Force is a non-custodial matrix protocol on BNB Smart Chain, written in Solidity ^0.8.20 (compiled with 0.8.24, optimizer 200 runs, EVM paris). It combines two board shapes across 12 price levels that double each step:

• S6 — a 2×2 board with 6 seats (levels 1, 2, 4, 5, 7, 8, 10, 11)
• S3 — a 1×3 board with 3 seats (levels 3, 6, 9, 12)

All values are denominated in USDT (BEP-20). Every payment is executed inside the same transaction that triggers it: the contract's USDT balance is always 0 between transactions. The only amount ever held is the auto-upgrade escrow of active users, and that balance is spent in the same transaction in which it is created whenever it reaches the next level's price.

The constructor registers msg.sender as User #1 with all 12 levels pre-activated and referrer = address(0). Any payment that cannot be routed to a valid recipient falls back to User #1, so funds can never become stranded.

2 · Addresses

Deployed addresses are printed by scripts/deploy.js and saved to deployments/<network>.json. Also paste them into site/js/config.js so the dApp knows where to look.

3 · Level schedule

Fixed on-chain — no owner function can change a price.

4 · Payout routing

When a participant pays for level L, the USDT transfer is split by the seat that the pay-er occupies in their own board of L:

S6 board (6 seats)

S3 board (3 seats)

All outbound transfers emit PaymentSent(payer, recipient, amount, level, position, reason) where reason ∈ {0: Placement, 1: AutoEscrow, 2: AutoPenalty, 3: Orphan, 4: EscrowRefund}.

5 · Placement & spillover

Placing a new member (or a downgraded matrix slot) follows depth-first spillover:

1. Try the referrer's own board at this level: first free seat row by row.
2. If full, descend into existing members' boards (row order), bounded by MAX_RECURSION_DEPTH = 20.
3. If the referrer chain is exhausted or invalid, walk up the pay-er's upline via findQualifiedUpline (also capped at 20 steps).
4. If nothing qualifies, the participant is attached to User #1 and the event is flagged orphan = true — the payment still succeeds.

Every placement emits Spillover(placedUser, level, matrixOwner, position, orphan).

6 · Auto-upgrade escrow

• autoUpgradeEnabled defaults to true and is stored per user (setAutoUpgrade(bool)).
• Designated escrow seats: S6 → seats 4–5, S3 → seats 1–2.
• While enabled, those seats credit autoUpgradeEscrow[level] instead of paying out.
• Whenever escrow[next] ≥ price(next) the next level is purchased automatically in the same transaction (the contract already holds the money), emitting Upgrade(..., autoTriggered = true).
• While disabled, designated seats pay the user immediately with a 25% protocol fee sent to productFund() — the user keeps 75%.
• Disabling never strands money: remaining escrow is refundable (EscrowRefund) via the contract's rescue path for the user's own balance.

7 · Recycle

When the final seat of a board fills, the recycle payment is made, then reinvestCount++, all seat arrays are cleared and currentReferrer is re-derived for the new cycle. Recycle(user, level, cycle) is emitted. The board is immediately ready for a fresh fill — loops never grow unbounded.

8 · Events

event Registration(address indexed user, address indexed referrer, uint256 indexed userId);
event Upgrade(address indexed user, uint8 indexed level, uint256 cost, bool autoTriggered);
event Recycle(address indexed user, uint8 indexed level, uint256 cycle);
event Spillover(address indexed placedUser, uint8 indexed level,
                address indexed matrixOwner, uint8 position, bool orphan);
event PaymentSent(address indexed payer, address indexed recipient, uint256 amount,
                  uint8 indexed level, uint8 position, uint8 reason);
event AutoUpgradeChanged(address indexed user, bool enabled);

9 · Functions

Write

Read

10 · Integration

Minimal ethers v6 example:

import { Contract, BrowserProvider } from "ethers";

const abi = [
  "function register(address referrer)",
  "function activateLevel(uint8 level)",
  "function setAutoUpgrade(bool enabled)",
  "function registered(address) view returns (bool)",
  "function getUser(address) view returns (uint256,address,uint256,bool)",
];

const provider = new BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const ef = new Contract(CONTRACT_ADDRESS, abi, signer);

await usdt.approve(CONTRACT_ADDRESS, price);   // once per amount
await ef.register(referrer);                   // level 1 = 20 USDT

A ready-made front-end exists in site/ (pure static files, ethers loaded from CDN, 6 languages) and can be dropped onto Vercel or Netlify as-is.

11 · Deploy & verify

npm install
npm.cmd run compile
npm.cmd run test              # 25/25 suite
npm.cmd run deploy:testnet    # BSC testnet
npm.cmd run deploy:mainnet    # BSC mainnet (requires .env PRIVATE_KEY)

Then verify on BscScan with the printed arguments, and paste the resulting address into site/js/config.js. See the project README.md for the full checklist (gas funding, .env, verification command).

12 · Security notes

• OpenZeppelin v5: SafeERC20, ReentrancyGuard, Ownable.
• Checks → effects → interactions ordering; state (seats, cycle counters) is updated before every external transfer.
• Bounded loops: placement recursion ≤ 20, upline walk ≤ 20 — predictable gas.
• $0 custody invariant: asserted by the test suite — contract balance is 0 after every scenario except mid-transaction escrow.
• No price/ownership migration: level prices are pure functions; the owner cannot alter user funds.
• Test suite: 25 tests covering registration, routing, spillover, orphan fallback, auto-upgrade on/off, penalties, recycle cycles and the $0 invariant.

Disclaimer: this documentation describes software provided as-is, without warranty. It is not financial advice. Matrix structures carry risk and may be regulated in your jurisdiction — participants are responsible for their own compliance and decisions.