> For the complete documentation index, see [llms.txt](https://docs.arcv.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.arcv.network/1.-overview-and-protocol-fundamentals/1.2-architecture.md). # 1.2 Architecture ## System boundaries and flow topology ARCV separates high-volume data processing from authorization-sensitive settlement. Prompts, response comparisons, telemetry, rubric evaluations, and storage uploads belong to the computation layer. Escrow balances, provenance commitments, replay reservations, and payout status belong to the settlement layer. The boundary is deliberate: a contract can enforce a finite state transition without executing an LLM, but it must trust the authorized actor that requests that transition. The diagram describes the intended end-to-end service. The repository implements selected frontend workflows and the registry; it does not establish that every depicted service is deployed. Capital is escrowed at campaign creation. It does not move through the ingestion gateway or the contributor's copilot. ``` ENTERPRISE LAB task specification + native USDC / \ / DATA \ CAPITAL v v +-------------------+ +---------------------------+ | Ingestion gateway | | Arc bounty registry | | schema + task IDs | | createBounty + msg.value | +---------+---------+ | escrow locked immediately | | +-------------+-------------+ v | +-------------------+ | funded capacity | Task queue | | | assignments | | +---------+---------+ | v | +----------------------------------+ | | Contributor workbench /annotate | | | prompt | output A | output B | | | rubric | rationale | correction | | +---------------+------------------+ | | | optional assistance | | | v | +-------------------+ | | BYO-key copilot | | | selected provider | | +-------------------+ | | human-reviewed submission | v | +----------------------------------+ | | Four-stage verification workflow | | | 1 Structure and sanitization | | | 2 Interaction evidence | | | 3 Rubric and consensus audit | | | 4 Archive and settlement handoff | | +---------------+------------------+ | v | +----------------------------------+ | | Canonical artifact + SHA-256 | | | Arweave-backed upload via Irys | | | receipt + retrieval verification | | +---------------+------------------+ | | digest, TxID, contributor | v v +-------------------------------------------------------+ | BUNDLER_ROLE: submitDataset -> Pending | | VALIDATOR_AGENT_ROLE: validateAndDisburse -> Paid | | Arc chain ID 5042: native USDC transferred to recipient | +--------------------------+----------------------------+ | record + archival reference v +-------------------------------------------------------+ | Versioned manifest -> edge cache -> verified shards | | PyTorch / Hugging Face loaders | +-------------------------------------------------------+ ``` The copilot branch is optional. Its generated text returns to human review, not directly to a settlement signer. The final stage is a coordinated workflow across storage and the EVM; there is no atomic transaction that spans an external gateway and Arc. ## Off-chain telemetry and computation layer ### Ingestion and assignment An ingestion service should validate transport size, file encoding, supported serialization, required task fields, and campaign ownership before placing tasks into a queue. Parsing JSON or CSV successfully does not establish that a task is complete or safe to distribute. The ingestion record must preserve the original upload identity, normalized task identifier, schema version, and any transformations applied before assignment. Assignments need a separate identity from raw rows. A single prompt may require multiple independent reviews, and a skipped assignment must not be confused with a completed annotation. A production queue should record lease expiry, attempt number, contributor eligibility, and the task revision shown to the contributor. Idempotency keys prevent transport retries from generating additional assignments or payable submissions. The current enterprise interface provides local payload parsing and configuration controls. Its deployment and queue integration remain distinct from a backend ingestion service. Financial accounting must use payable review units, even if the UI also displays unique task rows. ### Interaction evidence The intended telemetry layer can record sub-second event intervals using a monotonic browser clock, including prompt exposure, focus changes, selection changes, and revisions. This is a measurement design, not a measured sub-second service-level guarantee. Sampling frequency, batching, retention, and consent must be specified before operating the service. Client events are untrusted observations. A script can manufacture a long dwell time or move a slider. The server should bind events to a task session, enforce ordering and replay limits, and compare them with assignment and submission timestamps. Telemetry can route suspicious submissions to further review; it cannot independently certify personhood or comprehension. Only the evidence needed for evaluation should be retained. Keystroke contents, unrelated browsing activity, and credentials are not required to compute aggregate dwell intervals. Public archival of raw interaction logs would create a different privacy boundary from publishing an aggregate quality result. ### Sanitization and schema enforcement The structural gateway combines deterministic checks with heuristic detection. Schema validation rejects wrong types, missing fields, invalid enumerations, and exceeded size limits. Regex and contextual detectors identify likely contact details, network addresses, credential patterns, and other prohibited material. Detection must be followed by an explicit action: redact, reject, or quarantine for restricted review. Regex is not complete PII recognition. It can miss obfuscated identifiers and mistake valid technical content for private information. For code tasks, deleting a string can change program behavior. A redaction policy therefore needs versioned rules and a record of which transformation produced the final artifact. Raw rejected secrets must not be copied into application logs or permanent storage as debugging evidence. Final hashing occurs after accepted redaction and serialization. Hashing the original bytes and later uploading modified bytes produces a broken commitment, even when the modification was intended to improve privacy. ### Rubric evaluation and consensus Automated judges receive a constrained task containing the relevant prompt, candidate outputs, human decision, evidence, and rubric. Submitted text is data, not an instruction channel. Judges should not obtain treasury keys or unrestricted tools merely because a response asks them to execute an action. A consensus policy must specify reviewer independence, minimum coverage, abstention, disagreement handling, and hard acceptance gates. An average score can hide a critical failure: syntactically clean code that returns an incorrect result should not pass merely because readability scores are high. A factual claim without its required reference should fail a grounding gate even when most judges find it plausible. Human benchmark results and automated scores measure different things. Gold tasks can calibrate performance against known references; ambiguous preferences may require adjudication rather than a forced ground-truth label. Store evaluator versions and policy revisions so that a later audit can distinguish a model change from a change in the underlying submissions. ### Cache and retrieval The hot cache accelerates access to accepted immutable versions. Its key should incorporate the artifact digest and access policy, not only a mutable bounty label. Cache eviction should affect performance rather than identity: a retrieved archival fallback must resolve to the same committed bytes. Restricted enterprise content requires authenticated access at the cache and a separate decryption entitlement where encryption is used. An on-chain hash and a publicly visible transaction identifier are not decryption keys. Cache authorization must never be bypassed because a request contains a familiar dataset ID. ## On-chain cryptographic settlement layer ### Contract authority and accounting `ARCVDataBountyRegistry.sol` uses native-value escrow and OpenZeppelin roles. `DEFAULT_ADMIN_ROLE` governs role assignment and the external token reference. `BUNDLER_ROLE` registers payable dataset records. `VALIDATOR_AGENT_ROLE` accepts or rejects pending records. The constructor grants administrative authority; it does not automatically assign the operational roles. The contract is configured for Solidity 0.8.28 and Cancun. Its accounting is independent of the `$ARCV` price. For a bounty with target `N` and native-unit reward `r`, `createBounty` requires `msg.value == N × r`. Gas is separate. There is no additional contract fee, cancellation endpoint, expiry refund, or dynamic Golden Patch bonus in this version. The conceptual replay-protected hash registry is implemented as **`usedHashes(bytes32)`**. The name `registeredHashes` is not a callable function or mapping in the current ABI. `usedArweaveTxIds` separately reserves the Keccak-256 key of the supplied archival identifier. Both reservations are global to a registry deployment and remain set after rejection. ### What the EVM verifies | Contract-enforced condition | Evidence that remains off-chain | | --------------------------------------------------- | ------------------------------------------------- | | Exact campaign deposit and positive parameters | Whether the enterprise rubric is meaningful | | Bundler and validator authorization | Whether the authorized agent followed its policy | | Nonzero digest and valid transaction-ID shape | Whether archived bytes exist and match the digest | | Pending capacity below the funded target | Whether reviewers are independent people | | Pending-only payment and replay rejection | Whether a response is correct or legally usable | | Fixed native payout and rollback on failed transfer | Whether an LLM score is well calibrated | The recipient is selected at registration. The registry does not validate a contributor-signed claim or EIP-712 IP assignment. Those mechanisms require a separately implemented application and signature-verification design before they can be advertised as enforced protocol guarantees. ### Dataset state machine ``` None -- authorized registration --> Pending | +-----------------+----------------+ | | authorized acceptance authorized rejection | | v v Paid Rejected Failed native transfer: the entire acceptance transaction reverts to Pending. Paid and Rejected are terminal under the current interface. ``` For each bounty, `paidCount + pendingCount <= targetCount`. Remaining escrow equals `(targetCount - paidCount) × rewardPerSample`. Registration reserves capacity but does not consume escrow. Rejection releases pending capacity but does not refund the sponsor. Payment updates status and liability before its external native-value call; `ReentrancyGuard` and rollback behavior protect against selected callback and transfer-failure cases. ## Data lifecycle: one pairwise comparison ### 1. Specify and fund the payable work An enterprise defines a Python evaluation task, its rubric, and the requested number of reviews. The illustrative prompt asks for a high-performance Fibonacci implementation. Funding creates the bounty and locks escrow in the same transaction. An application must wait for the successful creation receipt and recover the actual bounty ID, rather than assume its locally predicted identifier is correct. ### 2. Normalize the task without losing its origin The gateway checks that the prompt and both candidate responses are present and that their encoding and lengths satisfy the campaign schema. It assigns a task identity, records the upload digest and row reference, and preserves the normalization version. Dataset rows and contributor assignments remain distinguishable throughout the process. ### 3. Present an assignment The workbench displays the prompt and two responses side by side. In the Fibonacci example, one candidate may use naive recursion while another uses iterative accumulation. The contributor must evaluate the supplied code, including its input contract and failure cases, rather than select an answer solely from a familiar complexity label. ### 4. Collect the decision and correction The contributor chooses a response, records the applicable rubric attributes, and supplies the required rationale. In an expert workflow, a Golden Patch can replace a defective answer with a tested correction. Copilot assistance is allowed only within the campaign's data-disclosure policy; sending a proprietary prompt to an external model is a separate disclosure from viewing it in the workbench. ### 5. Apply structural and interaction checks The gateway validates the submission schema, rejects transport duplicates, sanitizes prohibited content, and binds the submission to the assignment. Interaction checks examine timing and event consistency. A suspicious submission can be quarantined without representing a final semantic rejection. Review outcomes must be distinguishable from network or parser failures. ### 6. Evaluate against the campaign policy Deterministic code tests, independent human comparisons, and model-based judges contribute evidence according to the rubric. The candidate's behavior on negative inputs or boundary cases should be evaluated explicitly. Consensus disagreement can trigger another review. No universal score threshold is hard-coded by the settlement contract; thresholds belong to the versioned off-chain policy. ### 7. Serialize the accepted artifact The pipeline freezes accepted content, task and rubric identifiers, and the permitted evidence record. It computes SHA-256 over the exact serialized bytes. If the archive contains a manifest referencing several shards, each shard requires its own digest and size. A digest of a manifest is not automatically a digest of every object named within it. ### 8. Archive and independently retrieve The storage adapter uploads the artifact through the intended Arweave-backed integration and retains the receipt. It must distinguish gateway acceptance, bundle inclusion, and underlying storage settlement. A separate retrieval check recomputes the digest before the object is marked ready for registration. ### 9. Register one payable commitment The bundler submits the bounty ID, digest, transaction identifier, and contributor address. The resulting dataset ID represents one payable sample. A shard containing many contributors is not automatically a bulk-payment instruction. The one-record-per-payable-unit design also means one transaction identifier cannot be reused for several records in the same registry; any batch-payment redesign requires explicit contract changes. ### 10. Settle and reconcile The validator reads pending state, verifies its acceptance record, and requests `validateAndDisburse`. The backend records the successful receipt, the dataset ID, and the actual recipient. If a request times out after broadcast, it first reconciles chain state instead of blindly creating a new registration or payment request. ### 11. Deliver verified training inputs Consumers resolve a manifest version, authenticate if required, fetch the shard, verify its digest, and apply pinned transformations. Whole-file verification completes only after all bytes arrive. To avoid admitting unverified prefixes into training, verify bounded shards before yielding records or use a separately specified chunk-verification format. Derived tokenized datasets require their own artifact lineage. ## Failure recovery and release boundaries | Failure | Required recovery | | -------------------------------------------------- | --------------------------------------------------------------------------------- | | Upload succeeds, registration fails | Retain the upload receipt; inspect replay and capacity state before retrying | | Registration succeeds, gateway becomes unavailable | Retry an independent retrieval path; do not silently replace the committed object | | Validator decision is uncertain | Keep the item out of automatic acceptance and route to adjudication | | Payment recipient rejects native value | Preserve pending state after revert; investigate recipient compatibility | | Worker restarts after broadcast | Reconcile transaction receipt and dataset status using durable job identity | | Cache serves bytes with the wrong digest | Reject the artifact and invalidate the affected cache entry | Exactly-once processing across independent services is an operational objective, not a property conferred by an HTTP retry. Durable state, idempotency keys, transaction reconciliation, and immutable artifact identities are required together. The contract narrows the possible on-chain transitions; it cannot repair a lost off-chain task-to-artifact association. For implemented interfaces and test evidence, continue to [contract architecture](/5.-smart-contracts-and-arc-network-settlement/5.1-contract-architecture.md). For chain, storage, and routing configuration, use [network parameters](/1.-overview-and-protocol-fundamentals/1.3-network-parameters.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.arcv.network/1.-overview-and-protocol-fundamentals/1.2-architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.