feat(pos): introduce ERC20 staking skeleton contracts, spec, scripts, and tests

[BioMark3r]

Motivation

• Provide on-chain PoS staking state and clear interfaces as a Milestone 1 foundation for a future PoS migration without touching consensus/node runtime.
• Deliver devnet-friendly, deterministic tooling and a simple ERC20 staking token for local/operator flows so validators can register, stake, unbond, withdraw, and snapshot active sets.
• Keep gas-heavy/consensus integration work off-chain or for later milestones while offering concrete contract hooks and a snapshot placeholder for clients to consume.

Description

• Add a concise PoS spec skeleton at docs/pos/erc20-pos-skeleton.md describing actors, state model, epochs, lifecycle, interfaces, events, and integration notes.
• Implement ERC20 staking contracts under contracts/pos/: QIKToken.sol (owner-mintable devnet ERC20), ValidatorRegistry.sol (operator metadata registration), StakeManager.sol (ERC20 staking, unbonding queue, withdraw with ReentrancyGuard), and EpochManager.sol (epoch helpers and owner-submitted active-set snapshots + hash).
• Add Foundry baseline foundry.toml, deployment and operation scripts under script/pos/ (DeployPos.s.sol, PosOps.s.sol) which output .data/pos/addresses.json, and parsing helpers for CSV operator lists.
• Extend Makefile with PoS targets (pos-deploy, pos-mint, pos-register, pos-stake, pos-unstake, pos-withdraw, pos-snapshot, pos-info) and update README.md quickstart; add minimal Foundry tests in test/pos/staking_epoch.t.sol covering stake/unstake/withdraw, registration guard, and snapshot hashing/storage.

Testing

• Ran make help to validate Makefile integration and target visibility, which succeeded and shows the new pos-* targets.
• Attempted to run forge test but it could not execute in this environment because forge is not installed (bash: command not found: forge), so the added Foundry unit tests were not executed here.
• Added deterministic Foundry unit tests under test/pos/ intended to be run with forge test in a Foundry-enabled environment; they exercise the stake/unstake/withdraw happy path and the epoch snapshot logic.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a8d85ce497

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Configure Foundry fs_permissions for JSON output

DeployPos.run() writes deployment metadata using vm.createDir and vm.writeJson, but this commit does not configure fs_permissions with write access in foundry.toml; under Foundry's filesystem sandbox, write cheatcodes are blocked by default, so make pos-deploy can fail before producing .data/pos/addresses.json, which then breaks the downstream pos-* Make targets that read that file.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Include required Foundry libraries in repository setup

The new Solidity code depends on @openzeppelin and forge-std remapped to lib/openzeppelin-contracts and lib/forge-std/src, but those paths are not present in this repository, so a clean checkout cannot compile the PoS contracts/tests/scripts introduced here until manual dependency installation is done; this makes the new workflow non-reproducible unless setup instructions or install automation are added.

Useful? React with 👍 / 👎.