LockItIn Technical Docs

Complete technical reference for integrating with the LockItIn Protocol (v1.0) commitment system. This documentation covers smart contract functions, integration patterns, and the oracle system.

Architecture Overview

LockItIn is a peer-to-peer commitment protocol where two parties commit USDC on a natural language statement and let an AI oracle (VERO (The Oracle) via Chainlink Functions) determine the outcome and settle on-chain.

┌─────────────┐     ┌─────────────┐     ┌─────────────────────┐
│   Party A   │────▶│  LockItIn   │◀────│       Party B       │
│  (Creator)  │     │  Contract   │     │     (Acceptor)      │
└─────────────┘     └──────┬──────┘     └─────────────────────┘
                           │
                           │ resolveWager()
                           ▼
                   ┌───────────────┐
                   │   Chainlink   │
                   │   Functions   │
                   │     (DON)     │
                   └───────┬───────┘
                           │
                           ▼
                   ┌───────────────┐
                   │ AI Provider   │
                   │     API       │
                   └───────┬───────┘
                           │
                           │ YES / NO / VOID
                           ▼
                   ┌───────────────┐
                   │ fulfillRequest│
                   │   (callback)  │
                   └───────────────┘

Key Components

• LockItIn Protocol — Core protocol contract holding commitment funds and settlement logic
• USDC — Settlement currency (Circle's stablecoin on Base)
• Chainlink Functions — Decentralized oracle network executing off-chain computation
• VERO (The Oracle) — AI oracle system providing resolution outcomes
• LOCKIT Token — Governance token for protocol parameters

Contract Addresses (Base Mainnet)

Commitment Lifecycle

Every commitment moves through a defined state machine:

  OPEN ──────▶ LOCKED ──────▶ RESOLUTION_REQUESTED ──────▶ SETTLED
    │            │
    ▼            ▼
 CANCELLED   CANCELLED

Flow at a Glance

1. Creator commits USDC and posts a statement (may set targetAcceptor for a private commitment).
2. Counterparty accepts terms and commits the required USDC (must match target if set).
3. After resolveAfter, anyone calls requestResolution(); Chainlink → the oracle returns YES/NO/VOID.
4. On callback, the contract distributes settlement automatically; VOID refunds both (minus the resolution fee).

Core Functions

createCommitment

Create a new commitment. Caller becomes Party A (YES side).

createCommitmentWithPermit

Same as createCommitment but uses EIP-2612 permit for single-transaction approval.

acceptTerms

Accept an open commitment. Caller becomes Party B (NO side).

Requires USDC approval for amountB (the counterparty commitment).

acceptTermsWithPermit

Accept with an EIP-2612 permit signature (single transaction).

requestResolution

Request oracle resolution. Can only be called after resolveAfter.

Anyone can call this. It sends a request to Chainlink Functions, which calls an AI provider API and settles on callback.

cancelCommitment

Cancel an open commitment (only creator, only before acceptance).

requestMutualExit

Request a mutual exit (both parties must call while Locked to receive refunds).

emergencyVoid

Void a stuck commitment 7 days after resolution was requested but no callback was received.

timeoutVoid

Void a locked commitment 30 days after resolveAfter if resolution was never requested.

View Functions

getCommitment

Get complete commitment data.

commitmentCount

Total number of commitments created (use for iteration).

Derive Ratio (Off-chain)

There is no on-chain ratio helper. Compute it from amountA and amountB for display:

const amounts = await contract.getCommitmentAmounts(commitmentId);
const a = Number(ethers.formatUnits(amounts.amountA, 6));
const b = Number(ethers.formatUnits(amounts.amountB, 6));
const ratio = a === b ? '1:1' : (a > b ? `${(a/b).toFixed(2)}:1` : `1:${(b/a).toFixed(2)}`);

Fees, Discounts, Oracle Params

Current cost-recovery parameters and discount inputs are available via public getters:

Events

Enums & States

CommitmentState

enum CommitmentState {
    Open,                // 0 - Awaiting Party B
    Locked,              // 1 - Both parties committed
    ResolutionRequested, // 2 - Oracle query sent
    Settled,             // 3 - Settlement distributed (or refunds on VOID)
    Cancelled            // 4 - Cancelled / exited with refunds
}

Outcome

enum Outcome {
    Void,  // 0 - Ambiguous/error, refunds minus resolution fee
    Yes,   // 1 - Statement true, Party A favored
    No     // 2 - Statement false, Party B favored
}

Integration Quickstart

1. Setup

import { ethers } from 'ethers';

const LOCKITIN_ADDRESS = '0x6481788503af7408a4229725803c053576566fd2';
const USDC_ADDRESS = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';

const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

const contract = new ethers.Contract(LOCKITIN_ADDRESS, LOCKITIN_ABI, signer);
const usdc = new ethers.Contract(USDC_ADDRESS, USDC_ABI, signer);

2. Create a Commitment

// Amounts in USDC (6 decimals)
const amountA = ethers.parseUnits('50', 6);  // $50
const amountB = ethers.parseUnits('50', 6);  // $50 (symmetric)

// Calculate required approval
const creationFee = await contract.creationFee();
const deposit = amountA + creationFee;

// Approve USDC
await usdc.approve(LOCKITIN_ADDRESS, deposit);

// Create commitment
const resolveAfter = Math.floor(Date.now() / 1000) + (7 * 24 * 60 * 60);  // 7 days
const tx = await contract.createCommitment(
    "Bitcoin will exceed $150,000 by December 31, 2025.",
    resolveAfter,
    amountA,
    amountB,
    "",              // Use default model
    ethers.ZeroAddress, // Public commitment
    ethers.ZeroAddress  // No referrer
);

const receipt = await tx.wait();
const parsed = receipt.logs.map(l => { try { return contract.interface.parseLog(l); } catch { return null; } }).find(p => p && p.name === 'CommitmentCreated');
const commitmentId = parsed ? parsed.args.commitmentId : null;

ethers.js Examples

Accept Terms

const commitmentId = 42;
const amounts = await contract.getCommitmentAmounts(commitmentId);
const amountB = amounts.amountB;  // Required commitment for acceptor

await usdc.approve(LOCKITIN_ADDRESS, amountB);
await contract.acceptTerms(commitmentId, ethers.ZeroAddress);

Request Resolution

const commitmentId = 42;
const tx = await contract.requestResolution(commitmentId);
await tx.wait();
// Settlement happens automatically on the oracle callback (SettlementDistributed / CommitmentVoided)

Settlement Events

There is no user-initiated withdrawal step. Listen for settlement/refund events:

contract.on('SettlementDistributed', (commitmentId, favoredParty, amount) => {
  console.log(commitmentId.toString(), favoredParty, amount.toString());
});
contract.on('CommitmentVoided', (commitmentId, refundA, refundB) => {
  console.log(commitmentId.toString(), refundA.toString(), refundB.toString());
});

Fetch All Open Commitments

const count = await contract.commitmentCount();
const openCommitments = [];

for (let i = 0; i < count; i++) {
    const status = await contract.getCommitmentStatus(i);
    if (status.state === 0n) {  // state === Open
        openCommitments.push(i);
    }
}

EIP-2612 Permit (Gasless Approval)

USDC on Base supports EIP-2612 permits, allowing approval via signature instead of a separate transaction.

async function createCommitmentWithPermit(statement, resolveAfter, amountA, amountB) {
    const creationFee = await contract.creationFee();
    const deposit = amountA + creationFee;
    const nonce = await usdc.nonces(signer.address);
    const deadline = Math.floor(Date.now() / 1000) + 3600;  // 1 hour

    // EIP-712 domain for USDC on Base
    const domain = {
        name: 'USD Coin',
        version: '2',
        chainId: 8453,
        verifyingContract: USDC_ADDRESS
    };

    const types = {
        Permit: [
            { name: 'owner', type: 'address' },
            { name: 'spender', type: 'address' },
            { name: 'value', type: 'uint256' },
            { name: 'nonce', type: 'uint256' },
            { name: 'deadline', type: 'uint256' }
        ]
    };

    const value = {
        owner: signer.address,
        spender: LOCKITIN_ADDRESS,
        value: deposit,
        nonce: nonce,
        deadline: deadline
    };

    const signature = await signer.signTypedData(domain, types, value);
    const { v, r, s } = ethers.Signature.from(signature);

    return contract.createCommitmentWithPermit(
        statement,
        resolveAfter,
        amountA,
        amountB,
        "",
        ethers.ZeroAddress, // targetAcceptor (public)
        ethers.ZeroAddress, // creatorReferrer
        { deadline, v, r, s }
    );
}

Reading Commitments

Commitment Data Structure

The protocol uses stack-safe chunked getters (to avoid returning a giant struct). Fetch and assemble the fields you need:

const [parties, amounts, timing, status, statement, modelName] = await Promise.all([
    contract.getCommitmentParties(commitmentId),
    contract.getCommitmentAmounts(commitmentId),
    contract.getCommitmentTiming(commitmentId),
    contract.getCommitmentStatus(commitmentId),
    contract.getCommitmentStatement(commitmentId),
    contract.getCommitmentModel(commitmentId)
]);

const commitment = {
    partyA: parties.partyA,
    partyB: parties.partyB,
    targetAcceptor: parties.targetAcceptor,
    creatorReferrer: parties.creatorReferrer,
    acceptorReferrer: parties.acceptorReferrer,
    amountA: amounts.amountA,           // BigInt, USDC 6 decimals
    amountB: amounts.amountB,           // BigInt, USDC 6 decimals
    statement,
    modelName,
    createdAt: Number(timing.createdAt),
    resolveAfter: Number(timing.resolveAfter),
    resolutionRequestedAt: Number(timing.resolutionRequestedAt),
    state: Number(status.state),       // CommitmentState enum
    outcome: Number(status.outcome)    // Outcome enum
};

Format USDC Amounts

const formatUSDC = (amount) => {
    return (Number(amount) / 1_000_000).toFixed(2);
};

console.log(`Stake: $${formatUSDC(commitment.amountA)}`);

Oracle System

Two-Step Oracle Pipeline

The current VERO implementation uses a two-step pipeline designed to stay within oracle execution limits while minimizing prompt injection risk: (1) a search step retrieves evidence, then (2) an evaluation step produces a single-word verdict based only on that evidence.

Oracle Prompt (Timelocked)

The oracle evaluation prompt is part of the oracle configuration. It is readable from the contract and governance-controlled with timelocks:

Oracle Response Mapping

Oracle Configuration

Readable via contract state:

const systemPrompt = await contract.systemPrompt();
const defaultModel = await contract.defaultModel();
const apiEndpoint = await contract.apiEndpoint();
const veroSource = await contract.veroSource();
const veroTemperature = await contract.veroTemperature();

Current default model (as deployed): read from defaultModel(). Governance can schedule VERO updates to change model/endpoint/source/prompt/temperature. Once VERO timelock is activated, updates require 30-day notice on-chain.

Fee Structure

Read Current Fees

const creationFee = await contract.creationFee();    // USDC, 6 decimals
const resolutionFee = await contract.resolutionFee();  // USDC, 6 decimals
const daoFeeBps = await contract.daoFeeBps();        // Basis points
const txBuilderFeeBps = await contract.txBuilderFeeBps(); // Basis points

Timelocks

Protocol parameters are controlled by governance (Governor + Timelock). Oracle behavior changes also include an internal 30-day timelock inside the protocol contract.

Transparency: oracle updates are publicly scheduled on-chain before taking effect. Commitments resolve under the oracle configuration elected by governance.

Governance

LOCKIT Token

The governance token enables:

• Voting on fee parameter changes (within hardcoded bounds)
• Oracle configuration (providers, endpoints, models, prompt)
• Treasury allocation decisions
• Fee discounts for token holders

Current Discount System

const LOCKIT_TOKEN_ADDRESS = '0x309456d4F1e321dCdf9a8f9245bC660bBA3f30A0';
const lockitToken = new ethers.Contract(LOCKIT_TOKEN_ADDRESS, ERC20_ABI, signer);

const threshold = await contract.discountThreshold();
const discountBps = await contract.discountBps();
const balance = await lockitToken.balanceOf(userAddress);
const qualified = threshold > 0n && discountBps > 0n && balance >= threshold;

// If qualified, fees are reduced by discountBps
// e.g., discountBps = 2500 means 25% off fees

Current threshold: 0 (discounts not yet active)

Max discount: 50% (5000 bps)