neuron-tai/docs/adr/0007-contract-boundary-before-real-solana-programs.md

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.