docs: clarify contract boundary

CONTEXT.md

@@ -39,9 +39,21 @@ _Avoid_: reputation, rating, rank
 ### Payments & fraud
 
 **Stake**:
-Tokens a node locks as collateral before it can serve paid inference. Slashed on fraud.
+Tokens a node locks as collateral that can be slashed for fraud. Stake protects the network economically, but route selection is not based on a node's token balance.
 _Avoid_: deposit, bond, escrow
 
+**Tax**:
+The share of caller payments distributed to compute nodes as rewards. Taxes are weighted by completed work and historical node speed so faster, larger nodes earn proportionally more.
+_Avoid_: fee, toll, commission
+
+**Caller Credit**:
+Free starting balance granted to a new caller/API key so they can try the network before topping up.
+_Avoid_: signup bonus, faucet, airdrop
+
+**Free Compute Job**:
+Work a compute node performs without earning immediate rewards, usually during probation or bootstrap phases.
+_Avoid_: unpaid labor, warmup request
+
 **Slash**:
 The act of reducing a node's stake as a penalty for a proven fraud incident.
 _Avoid_: penalize, burn, fine
@@ -62,6 +74,10 @@ _Avoid_: trial period, warmup, grace period
 Our native Solana L2 token. Used by nodes for staking and received as inference rewards. Clients never need to hold it.
 _Avoid_: coin, reward token, native token
 
+**Contract Boundary**:
+The Python interface in `packages/contracts` that represents registry, payment, and settlement behavior. During the prototype it is implemented by deterministic local wrappers; later the same boundary is backed by real Solana programs.
+_Avoid_: mock contract, fake chain, temporary hack
+
 **Validator**:
 A trusted node (or the tracker itself) that re-runs a sample of inference requests to detect fraud.
 _Avoid_: auditor, checker, referee

docs/adr/0002-dual-token-payment-model.md

@@ -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

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

@@ -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.