Institutional Settlement Specification

Design Philosophy

SkillRail is an institutional-grade settlement standard designed to eliminate the 'Trust Tax' in labor markets. It uses a Clean Architecture pattern, isolating pure business rules (Domain) from platform-specific infrastructure.

Key Principles

• Deterministic Finality: On-chain state transitions govern the entire job lifecycle.
• Universal Agnosticism: Behavioral parity across Docker, Mac, and Linux environments.
• Non-Custodial Security: PDAs act as sovereign vaults, ensuring assets are protected by cryptographic logic.

System Integrity

• Instruction-Logic Separation: lib.rs delegates to logic.rs for pure rule validation.
• Isolated Vaults: Each job uses a program-controlled vault for asset separation.
• Strict Account Checks: Deterministic PDA verification for every mutation.

Lifecycle Transitions

The protocol enforces a strict directional flow to ensure contract compliance.

Invariant Rules

• Jobs must be 'Funded' before work submission.
• Payouts are atomic and requires requester acceptance.
• Refunds only trigger after deadline + Funded status.

ProviderProfile (253 Bytes)

Stores technical identity and reputation markers.

Job (547 Bytes)

The authoritative record of a work settlement contract.

Sizing Strategy

All string fields are strictly bounded to ensuring predictable account rent costs. Metadata URIs (metadata, terms, result) are limited to 200 characters each.

register_provider

Initializes a provider profile. Precondition: metadata_uri.len() <= 200 bytes.

create_job

Initializes a Job PDA. Requires: valid assigned provider profile, amount > 0, and future deadline.

fund_job

Escrows assets from Requester to Job Vault. Atomic CPI transfer ensures status only moves to 'Funded' on success.

submit_result

Provider commits work. Valid only if Funded and before deadline.

accept_result

Requester finalizes the job. Triggers atomic payout from Vault to Provider.

refund_job

Recovery path. Valid only if Funded and Clock > deadline_at.

Technical Table

SkillRailClient

The high-level entry point for all frontends and services. Encapsulates RPC complexity, PDA derivation, and transaction building.

Domain Entities

Rich objects like 'JobEntity' provide off-chain utility methods (isFunded, canRequesterRefund) ensuring business logic remains consistent.

Code Snippet

const client = new SkillRailClient(program); const job = await client.getJob(address);

Transition Matrix

Strict Security Checks

The protocol centralizes security logic into dedicated validation modules to prevent bypass attacks.

• ACCOUNT_OWNERSHIP: Verified via Anchor's #[account] macros.
• SIGNATURE_AUTHORITY: Every mutation requires a multi-signer proof.
• TOKEN_MINT_ENFORCEMENT: Only authorized settlement assets are accepted.
• PDA_CANONICAL_CHECK: Bumps are validated to prevent account spoofing.

Monorepo Structure

SkillRail follows a unified monorepo pattern for behavioral parity across layers.

• /contracts: Authoritative Rust source of truth.
• /sdk: TypeScript bridge for RPC orchestration.
• /web: Next.js operator dashboard.
• /tests: High-assurance protocol test suite.

High-Assurance Integrity

SkillRail enforces security through deterministic isolation.

• Isolated Vaults: Each job uses a unique PDA-controlled ATA.
• Canonical Verification: Forced bump validation prevents spoofing.
• Signer Constraints: Multi-party verification for every state jump.

Architectural Philosophy

Built on Domain-Driven Design (DDD) to isolate business invariants from blockchain infrastructure.

• Pure Domain Logic: Rust modules for pure transition rules.
• Agnostic SDK: Repository patterns for RPC orchestration.
• Operator Dashboard: Feature-sliced presentation layer.

Program Exceptions

Authoritative reference for on-chain error codes.