popov/neuron-tai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify contract boundary

Browse Source
This commit is contained in:
Dobromir Popov
2026-06-29 02:01:49 +03:00
parent 3b7ef2743d
commit 8900990193
3 changed files with 40 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/adr/0002-dual-token-payment-model.md
View File

@@ -2,6 +2,8 @@
Clients pay in SOL or USDC — familiar, easy to buy, no new token required. Node operators stake and earn our native Solana L2 token, which creates speculative upside for early contributors and a staking mechanism for fraud prevention (slashing). The two are decoupled: client payments are auto-converted to partially fund token rewards; clients never need to hold or know about our token.
For the prototype contract boundary, settlement keeps three explicit ledgers: caller SOL/USDC balances by API key, node Token stake balances by wallet, and node Token reward balances by wallet. Every new caller receives configurable starting credit. Epoch settlement debits caller SOL/USDC balances for consumed compute and credits node Token rewards from taxes. Tax distribution is weighted by completed work and historical node speed so faster, larger nodes are economically incentivized. No AMM or real conversion is modeled yet.
Using SOL alone would give node operators no early-adopter upside ("why run my GPU for market-rate SOL?"), killing the viral growth mechanic. Launching a token-only system requires clients to acquire our token, adding friction that kills adoption. The dual model solves both.
## Considered Options

21
docs/adr/0007-contract-boundary-before-real-solana-programs.md Normal file
View File

@@ -0,0 +1,21 @@
# Contract boundary before real Solana programs
For the prototype implementation, `packages/contracts` defines the registry, payment, and settlement contract boundary as Python wrappers with deterministic local state. The gateway, tracker, validator, and SDK integrate through this boundary instead of depending directly on Anchor/Solana program internals.
Real Solana/Anchor programs are deferred until the boundary is exercised by the rest of the system. A later implementation can replace the local adapter with testnet/mainnet Solana adapters without changing gateway/tracker call sites.
## Considered Options
- **Build real Anchor/Solana programs now**: highest fidelity, but blocks the current loop on unavailable toolchains and early economic details that are still evolving.
- **Pure in-memory mocks with no Solana-shaped boundary**: fastest, but creates throwaway APIs and lets gateway/tracker integrate against the wrong abstraction.
- **Python contract boundary with deterministic local adapter now, real Solana adapter later**: chosen — keeps the architecture honest while preserving momentum.
## Consequences
- CI can run without `solana-test-validator`, Anchor, Rust, or live testnet access.
- `.env.testnet` documents the intended manual testnet configuration, but tests remain local and hermetic.
- Acceptance criteria that mention deployment to Solana testnet are interpreted as boundary/config readiness in this prototype, not a live deployment.
- Future Solana work must preserve the `packages/contracts` public interface or explicitly migrate consumers.
- Routing eligibility is not based on a compute node's token balance. Stake remains collateral for slashing; rewards/taxes are paid to nodes that actually performed inference work.
- Every new caller/API key receives configurable starting credit in the local contract boundary.
- Tax distribution is weighted by completed work and historical node speed, so faster nodes earn more for useful throughput.