ifr-sdk 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inferno Protocol contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# IFR SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Repository SDK for exact 9-decimal IFR access checks and signer-neutral Benefits checkout
+sessions. The package currently supports Ethereum Mainnet only.
+
+## Availability
+
+The SDK is not yet published to the npm registry. Publication is prepared: the first version is a
+one-time manual bootstrap by the project npm account; every later version is published by
+`.github/workflows/sdk-publish.yml`, dispatched manually on protected `main`, which checks the release
+gate, waits for owner approval, tests the package and publishes it with npm provenance through npm
+Trusted Publishing. Until then, build and pack the versioned artifact from the repository:
+
+```bash
+cd apps/sdk
+npm ci
+npm run build
+npm pack --ignore-scripts
+```
+
+Add the resulting `.tgz` path to the consuming application's `package.json` and committed
+lockfile, then use `npm ci`.
+
+## Contract Addresses
+
+`MAINNET_ADDRESSES` lists deployed contracts. `commitmentVault` is CommitmentVault V1: its
+price-conditioned tranches can never unlock, so applications must not create new locks there;
+existing time tranches stay unlockable through V1. `commitmentVaultV2` is CommitmentVault V2
+(TIME_ONLY); it accepts new time locks once Governance proposal #17 (its fee exemption) has executed.
+`lendingVault` is the retired LendingVault V1 with borrowing permanently disabled.
+
+The tarball exports CommonJS with tested ESM named-import interoperability and supports Node.js
+20 and 22. CI verifies the exact package contents, installs the locked tarball with `npm ci`, and
+runs fresh CommonJS, ESM-import and TypeScript consumers.
+
+The canonical REST API is:
+
+```text
+https://copilot-api.ifrunit.tech/api/ifr/check
+```
+
+## Benefit Tiers
+
+`DEFAULT_TIERS` is the project's default preset and matches the Benefits network: IFR **locked in
+IFRLock** only, Bronze 1,000 / Silver 2,500 / Gold 5,000 / Platinum 10,000.
+
+```js
+const { IFRClient, DEFAULT_TIERS, getBenefitTierFromRaw } = require("ifr-sdk");
+const client = new IFRClient();
+const tier = await client.getBenefitTier(wallet);            // default preset
+const own = await client.getBenefitTier(wallet, [            // your own model
+  { key: "fan", name: "Fan", minLocked: "100" },
+  { key: "vip", name: "VIP", minLocked: "2000" },
+]);
+```
+
+- The tiers are a **default preset and label set, not a rule**. In the Benefits network every partner
+  sets its own thresholds, minimum held IFR, lock source (IFRLock, CommitmentVault time locks or
+  either), discount and daily/monthly limits per benefit.
+- Any project may verify IFR permissionlessly with its own rule, for example a hold-based check with
+  its own discount, following the open verification profile `ifr-benefits-verify/1`.
+- Discounts are independent of partner rewards. PartnerVault rewards follow Lane 4 model B and are
+  available only to approved pilot partners; they are currently disabled.
+- `getBenefitTier` reads IFRLock only and fails closed: a failed read throws instead of reporting 0.
+- `TIER_THRESHOLDS`, `TIER_NAMES`, `getTier`, `getTierFromRaw` and the `tier` fields of `checkAccess` are
+  the deprecated legacy hold+lock access tiers (balance + locked, 500 / 2,000 / 10,000). They remain
+  for compatibility and are removed in 1.0.
+
+## Read Errors
+
+The SDK never turns a failed on-chain read into `0` or `false`. If a read fails, `checkAccess`, `getTier`,
+`getBenefitTier`, `getLockedBalance` and `isBuilder` reject with `IFRReadError` (its `read` field names the
+failed call, `cause` holds the original error). Treat it as "could not verify", not as "nothing locked" or
+"not a builder".
+
+## Benefits Checkout
+
+`IFRBenefitsClient.createCheckout()` requests a one-time `sessions:create` challenge bound to
+the business and benefit rule (the request carries no wallet; the backend recovers the seller from
+the signature), then creates the session.
+`IFRBenefitsClient.getCheckoutStatus(sessionId)` polls `GET /api/sessions/:id` and fail-closed
+validates the public status response (`PENDING`, `APPROVED`, `REJECTED`, `REDEEMED`, `EXPIRED`).
+`IFRBenefitsClient.redeemCheckout({ sessionId, walletAddress, signMessage })` requests a fresh
+one-time `sessions:redeem` challenge bound to the session ID and posts the signed redemption to
+`POST /api/sessions/:id/redeem`; it resolves only after the API confirms `REDEEMED`.
+
+Both signed flows validate action, business, scope, domain, chain, timestamp, nonce and the exact
+challenge message before any signature is requested.
+
+### Compatibility: wallet-free seller challenge (0.4.0)
+
+The Benefits backend no longer echoes `walletAddress` in `GET /api/seller/auth-message` (owner
+decision B: no wallet in the challenge URL, response or storage; a legacy `walletAddress` query
+parameter is ignored). Earlier `ifr-sdk` builds up to 0.3.0 (never published to npm; only repository
+tarballs) require `challenge.walletAddress` in that response and reject every challenge from the new backend ("mismatched seller authorization
+challenge"), so `createCheckout()` and `redeemCheckout()` break. Release order: publish and roll out
+`ifr-sdk` 0.4.0 (wallet-free) **before** the Benefits backend release that ships the
+wallet-free challenge, and tell integrators to upgrade first. Publishing is a separate release gate. The caller supplies a wallet-native `signMessage`
+callback; the SDK never accepts or stores private keys, seed phrases or persistent seller secrets.
+
+## Verification
+
+```bash
+cd apps/sdk
+npm ci
+npm test
+npm run test:package
+npm audit --audit-level=moderate
+npm pack --dry-run
+```
+
+Publication follows the release checklist in `docs/runbooks/IFR_SDK_NPM_RELEASE.md`.

package/dist/benefits.d.ts

@@ -0,0 +1,71 @@
+export declare const DEFAULT_BENEFITS_API = "https://shop.ifrunit.tech";
+export type SellerAuthorizationAction = "sessions:create" | "sessions:redeem";
+export interface SellerAuthorizationChallenge {
+    action: SellerAuthorizationAction;
+    businessId: string;
+    scope: string;
+    domain: string;
+    chainId: number;
+    timestamp: string;
+    issuedAt: string;
+    expiresAt: string;
+    message: string;
+    nonce: string;
+}
+export interface BenefitsCheckoutSession {
+    sessionId: string;
+    expiresAt: string;
+    qrUrl: string;
+    customerUrl: string;
+    benefitRuleId: string | null;
+    label: string | null;
+    category: string | null;
+    productName: string | null;
+    discountPercent: number;
+    requiredLockIFR: number;
+    dailyRedemptionLimit: number;
+    monthlyRedemptionLimit: number;
+    tierLabel: string | null;
+}
+export interface CreateBenefitsCheckoutParams {
+    businessId: string;
+    benefitRuleId?: string;
+    walletAddress: string;
+    signMessage: (message: string) => Promise<string>;
+}
+export interface RedeemBenefitsCheckoutParams {
+    sessionId: string;
+    walletAddress: string;
+    signMessage: (message: string) => Promise<string>;
+}
+export type BenefitsCheckoutStatusValue = "PENDING" | "APPROVED" | "REJECTED" | "REDEEMED" | "EXPIRED";
+export interface BenefitsCheckoutStatus {
+    status: BenefitsCheckoutStatusValue;
+    reason: string | null;
+    redeemedAt: string | null;
+    expiresAt: string;
+    attestAttempts: number;
+    businessId: string;
+    benefitRuleId: string | null;
+    presentation: "CUSTOMER_PASS" | "SELLER_QR";
+}
+export interface BenefitsCheckoutRedemption {
+    status: "REDEEMED";
+}
+export interface IFRBenefitsClientConfig {
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    /** Expected chain ID of the Benefits deployment; seller challenges for another chain are refused. */
+    chainId?: number;
+}
+export declare class IFRBenefitsClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly chainId?;
+    constructor(config?: IFRBenefitsClientConfig);
+    private requestSellerChallenge;
+    private signSellerChallenge;
+    createCheckout(params: CreateBenefitsCheckoutParams): Promise<BenefitsCheckoutSession>;
+    getCheckoutStatus(sessionId: string): Promise<BenefitsCheckoutStatus>;
+    redeemCheckout(params: RedeemBenefitsCheckoutParams): Promise<BenefitsCheckoutRedemption>;
+}

package/dist/benefits.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IFRBenefitsClient = exports.DEFAULT_BENEFITS_API = void 0;
+exports.DEFAULT_BENEFITS_API = "https://shop.ifrunit.tech";
+const SELLER_AUTH_TTL_MS = 10 * 60 * 1000;
+const MAX_FUTURE_SKEW_MS = 2 * 60 * 1000;
+const BENEFITS_CHECKOUT_STATUSES = [
+    "PENDING",
+    "APPROVED",
+    "REJECTED",
+    "REDEEMED",
+    "EXPIRED",
+];
+function safeAuthorizationField(value, label) {
+    if (!value || value.length > 200 || value !== value.trim() || /[\r\n]/.test(value)) {
+        throw new Error(`Invalid ${label}`);
+    }
+    return value;
+}
+function safeSessionPathSegment(value) {
+    if (!value ||
+        value.length > 200 ||
+        value !== value.trim() ||
+        /[\u0000-\u001f\u007f]/.test(value) ||
+        /[/?#\\]/.test(value) ||
+        value.includes("..")) {
+        throw new Error("Invalid checkout session ID");
+    }
+    return encodeURIComponent(value);
+}
+function normalizeBaseUrl(value) {
+    const url = new URL(value);
+    const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+        throw new Error("Benefits API must use HTTPS except on loopback test hosts");
+    }
+    if (url.username || url.password || (url.pathname !== "/" && url.pathname !== "") || url.search || url.hash) {
+        throw new Error("Benefits API must be an origin without credentials, path, query, or fragment");
+    }
+    url.pathname = "/";
+    return url;
+}
+function isAddress(value) {
+    return /^0x[0-9a-fA-F]{40}$/.test(value);
+}
+function isCanonicalIsoDate(value) {
+    if (typeof value !== "string")
+        return false;
+    const timestamp = Date.parse(value);
+    return !Number.isNaN(timestamp) && new Date(timestamp).toISOString() === value;
+}
+async function readJson(response) {
+    if (!response.ok)
+        throw new Error(`IFR Benefits API request failed (${response.status})`);
+    return response.json();
+}
+function buildSellerAuthorizationMessage(domain, chainId, action, businessId, timestamp, scope, nonce) {
+    return [
+        "IFR Benefits Network - Seller Authorization",
+        `Domain: ${domain}`,
+        `Chain ID: ${chainId}`,
+        `Action: ${action}`,
+        `Business: ${businessId}`,
+        `Scope: ${scope}`,
+        `Nonce: ${nonce}`,
+        `Timestamp: ${timestamp}`,
+        `Expires: ${new Date(Number(timestamp) + SELLER_AUTH_TTL_MS).toISOString()}`,
+        `Only sign this message inside ${domain}.`,
+    ].join("\n");
+}
+class IFRBenefitsClient {
+    constructor(config = {}) {
+        this.baseUrl = normalizeBaseUrl(config.baseUrl || exports.DEFAULT_BENEFITS_API);
+        this.fetchImpl = config.fetch || fetch;
+        if (config.chainId !== undefined && (!Number.isSafeInteger(config.chainId) || config.chainId <= 0)) {
+            throw new Error("Invalid Benefits chain ID");
+        }
+        this.chainId = config.chainId;
+    }
+    async requestSellerChallenge(action, businessId, scope) {
+        // The challenge request is wallet-free (no address in the URL): the signer is bound only by the
+        // signature over the returned message, which the backend recovers.
+        const challengeUrl = new URL("/api/seller/auth-message", this.baseUrl);
+        challengeUrl.search = new URLSearchParams({
+            action,
+            businessId,
+            scope,
+        }).toString();
+        const challenge = await readJson(await this.fetchImpl(challengeUrl.toString(), { method: "GET" }));
+        const timestampMs = Number(challenge.timestamp);
+        const issuedAtMs = Date.parse(challenge.issuedAt);
+        const expiresAtMs = Date.parse(challenge.expiresAt);
+        const now = Date.now();
+        if (challenge.action !== action ||
+            challenge.businessId !== businessId ||
+            challenge.scope !== scope ||
+            // The signed message must name the exact API origin host this client talks to.
+            challenge.domain !== this.baseUrl.host ||
+            !Number.isSafeInteger(challenge.chainId) ||
+            challenge.chainId <= 0 ||
+            (this.chainId !== undefined && challenge.chainId !== this.chainId) ||
+            !/^\d{10,16}$/.test(challenge.timestamp || "") ||
+            !Number.isSafeInteger(timestampMs) ||
+            issuedAtMs !== timestampMs ||
+            expiresAtMs !== timestampMs + SELLER_AUTH_TTL_MS ||
+            timestampMs < now - SELLER_AUTH_TTL_MS ||
+            timestampMs > now + MAX_FUTURE_SKEW_MS ||
+            expiresAtMs <= now ||
+            !/^[0-9a-f]{64}$/.test(challenge.nonce || "") ||
+            challenge.message !== buildSellerAuthorizationMessage(challenge.domain, challenge.chainId, action, businessId, challenge.timestamp, scope, challenge.nonce)) {
+            throw new Error("IFR Benefits API returned a mismatched seller authorization challenge");
+        }
+        return challenge;
+    }
+    async signSellerChallenge(challenge, signMessage) {
+        const signature = await signMessage(challenge.message);
+        if (!/^0x[0-9a-fA-F]{130}$/.test(signature)) {
+            throw new Error("Seller wallet returned an invalid signature");
+        }
+        return signature;
+    }
+    async createCheckout(params) {
+        const businessId = safeAuthorizationField(params.businessId, "business ID");
+        const scope = safeAuthorizationField(params.benefitRuleId || "default", "benefit rule ID");
+        if (!isAddress(params.walletAddress))
+            throw new Error("Invalid seller wallet address");
+        if (typeof params.signMessage !== "function")
+            throw new Error("Seller wallet signer is required");
+        const challenge = await this.requestSellerChallenge("sessions:create", businessId, scope);
+        const signature = await this.signSellerChallenge(challenge, params.signMessage);
+        const sessionUrl = new URL("/api/sessions", this.baseUrl);
+        const session = await readJson(await this.fetchImpl(sessionUrl.toString(), {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-ifr-wallet": params.walletAddress,
+                "x-ifr-signature": signature,
+                "x-ifr-timestamp": challenge.timestamp,
+                "x-ifr-nonce": challenge.nonce,
+            },
+            body: JSON.stringify({
+                businessId,
+                ...(params.benefitRuleId ? { benefitRuleId: params.benefitRuleId } : {}),
+            }),
+        }));
+        if (!session.sessionId || !session.qrUrl) {
+            throw new Error("IFR Benefits API returned an invalid checkout session");
+        }
+        const customerUrl = new URL(session.qrUrl, this.baseUrl);
+        if (customerUrl.origin !== this.baseUrl.origin ||
+            !/^\/r\/[^/]+$/.test(customerUrl.pathname) ||
+            customerUrl.search ||
+            customerUrl.hash) {
+            throw new Error("IFR Benefits API returned an invalid customer URL");
+        }
+        return {
+            ...session,
+            customerUrl: customerUrl.toString(),
+        };
+    }
+    async getCheckoutStatus(sessionId) {
+        const segment = safeSessionPathSegment(sessionId);
+        const statusUrl = new URL(`/api/sessions/${segment}`, this.baseUrl);
+        const session = await readJson(await this.fetchImpl(statusUrl.toString(), { method: "GET", cache: "no-store" }));
+        if (!session || typeof session !== "object") {
+            throw new Error("IFR Benefits API returned an invalid checkout status");
+        }
+        if (!BENEFITS_CHECKOUT_STATUSES.includes(session.status) ||
+            !(session.reason === null || typeof session.reason === "string") ||
+            !(session.redeemedAt === null || isCanonicalIsoDate(session.redeemedAt)) ||
+            !isCanonicalIsoDate(session.expiresAt) ||
+            !Number.isSafeInteger(session.attestAttempts) ||
+            session.attestAttempts < 0 ||
+            typeof session.businessId !== "string" ||
+            !session.businessId ||
+            !(session.benefitRuleId === null || typeof session.benefitRuleId === "string") ||
+            (session.presentation !== "CUSTOMER_PASS" && session.presentation !== "SELLER_QR")) {
+            throw new Error("IFR Benefits API returned an invalid checkout status");
+        }
+        return {
+            status: session.status,
+            reason: session.reason,
+            redeemedAt: session.redeemedAt,
+            expiresAt: session.expiresAt,
+            attestAttempts: session.attestAttempts,
+            businessId: session.businessId,
+            benefitRuleId: session.benefitRuleId,
+            presentation: session.presentation,
+        };
+    }
+    async redeemCheckout(params) {
+        const segment = safeSessionPathSegment(params.sessionId);
+        if (!isAddress(params.walletAddress))
+            throw new Error("Invalid seller wallet address");
+        if (typeof params.signMessage !== "function")
+            throw new Error("Seller wallet signer is required");
+        const challenge = await this.requestSellerChallenge("sessions:redeem", params.sessionId, params.sessionId);
+        const signature = await this.signSellerChallenge(challenge, params.signMessage);
+        const redeemUrl = new URL(`/api/sessions/${segment}/redeem`, this.baseUrl);
+        const result = await readJson(await this.fetchImpl(redeemUrl.toString(), {
+            method: "POST",
+            headers: {
+                "x-ifr-wallet": params.walletAddress,
+                "x-ifr-signature": signature,
+                "x-ifr-timestamp": challenge.timestamp,
+                "x-ifr-nonce": challenge.nonce,
+            },
+        }));
+        if (!result || result.status !== "REDEEMED") {
+            throw new Error("IFR Benefits API returned an invalid checkout redemption");
+        }
+        return { status: "REDEEMED" };
+    }
+}
+exports.IFRBenefitsClient = IFRBenefitsClient;

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+/**
+ * IFR SDK — Web3 Access Control for Builders
+ *
+ * Repository package: build and pack apps/sdk, then consume the locked tarball
+ *
+ * import { IFRClient } from "ifr-sdk"
+ * const ifr = new IFRClient({ network: "mainnet" })
+ * const access = await ifr.checkAccess({ wallet: "0x...", required: 1000 })
+ * if (access.hasAccess) enableAccess()
+ */
+import { type BigNumberish } from "ethers";
+export * from "./benefits";
+export declare const MAINNET_ADDRESSES: {
+    readonly ifrToken: "0x77e99917Eca8539c62F509ED1193ac36580A6e7B";
+    readonly ifrLock: "0x769928aBDfc949D0718d8766a1C2d7dBb63954Eb";
+    /** CommitmentVault V1: price tranches never unlock (CV-01); existing time tranches unlockable. Do not create new locks here. */
+    readonly commitmentVault: "0x0719d9eb28dF7f5e63F91fAc4Bbb2d579C4F73d3";
+    /** CommitmentVault V2: TIME_ONLY; new locks after Governance proposal #17 (fee exemption) executes. */
+    readonly commitmentVaultV2: "0x8efae0C85ad6d44C731cAEDA1cBC275904Fc7c8F";
+    /** LendingVault V1: retired, borrowing permanently disabled. */
+    readonly lendingVault: "0x974305Ab0EC905172e697271C3d7d385194EB9DF";
+    readonly builderRegistry: "0xdfe6636DA47F8949330697e1dC5391267CEf0EE3";
+    readonly governance: "0xc43d48E7FDA576C5022d0670B652A622E8caD041";
+};
+export declare const IFR_API = "https://copilot-api.ifrunit.tech";
+/** @deprecated Use IFR_API. */
+export declare const RAILWAY_API = "https://copilot-api.ifrunit.tech";
+export declare const IFR_DECIMALS = 9;
+export interface IFRClientConfig {
+    network?: "mainnet" | "sepolia";
+    rpcUrl?: string;
+    apiUrl?: string;
+}
+export interface AccessCheckParams {
+    wallet: string;
+    required: string | number;
+    checkLocked?: boolean;
+}
+export interface AccessResult {
+    hasAccess: boolean;
+    balance: number;
+    locked: number;
+    total: number;
+    required: number;
+    balanceRaw: string;
+    lockedRaw: string;
+    totalRaw: string;
+    requiredRaw: string;
+    tier: number;
+    tierName: string;
+}
+export interface TierResult {
+    tier: number;
+    tierName: string;
+    balance: number;
+    locked: number;
+    balanceRaw: string;
+    lockedRaw: string;
+    totalRaw: string;
+}
+export interface BenefitTier {
+    /** Stable key, e.g. "bronze". */
+    key: string;
+    /** Display name, e.g. "Bronze". */
+    name: string;
+    /** Minimum IFR locked in IFRLock, decimal string with at most 9 decimals. */
+    minLocked: string;
+}
+export declare const DEFAULT_TIERS: readonly BenefitTier[];
+export interface BenefitTierResult {
+    /** 0 = below the first tier, 1..n = index of the highest tier reached (1-based). */
+    level: number;
+    /** Tier key, or null below the first tier. */
+    key: string | null;
+    /** Tier name, or "None" below the first tier. */
+    name: string;
+    lockedRaw: string;
+}
+/** Validates a tier list: non-empty, unique keys, strictly ascending exact 9-decimal thresholds. */
+export declare function validateTiers(tiers: readonly BenefitTier[]): bigint[];
+/** Highest tier reached by an exact locked amount (9-decimal base units); no rounding. */
+export declare function getBenefitTierFromRaw(lockedRaw: BigNumberish, tiers?: readonly BenefitTier[]): BenefitTierResult;
+/**
+ * Thrown when an on-chain read fails. The SDK never turns a failed read into 0 or false,
+ * so a caller cannot mistake an RPC outage for "no IFR locked" or "not a builder".
+ */
+export declare class IFRReadError extends Error {
+    readonly read: string;
+    constructor(read: string, cause: unknown);
+}
+/**
+ * @deprecated Legacy hold+lock access tiers (wallet balance + locked, 500 / 2,000 / 10,000).
+ * Not the project's benefit preset. Use `DEFAULT_TIERS` with `getBenefitTierFromRaw`. Removed in 1.0.
+ */
+export declare const TIER_THRESHOLDS: {
+    readonly TIER1: 500;
+    readonly TIER2: 2000;
+    readonly TIER3: 10000;
+};
+/** @deprecated Legacy access tier names; use `DEFAULT_TIERS`. Removed in 1.0. */
+export declare const TIER_NAMES: readonly ["None", "Basic", "Premium", "Pro"];
+/** @deprecated Legacy hold+lock access tier; use `getBenefitTierFromRaw`. Removed in 1.0. */
+export declare function getTierFromAmount(amount: number): number;
+/** @deprecated Legacy access tier name; use `getBenefitTierFromRaw(...).name`. Removed in 1.0. */
+export declare function getTierName(tier: number): string;
+export declare function parseIFRAmount(value: string | number): bigint;
+/** @deprecated Legacy hold+lock access tier; use `getBenefitTierFromRaw`. Removed in 1.0. */
+export declare function getTierFromRaw(amount: BigNumberish): number;
+export declare function evaluateAccessRaw(balanceRaw: BigNumberish, lockedRaw: BigNumberish, requiredRaw: BigNumberish): {
+    hasAccess: boolean;
+    total: bigint;
+    tier: number;
+    tierName: string;
+};
+export declare class IFRClient {
+    private provider;
+    private token;
+    private lockContract;
+    private registry;
+    private apiUrl;
+    readonly TIER1: 500;
+    readonly TIER2: 2000;
+    readonly TIER3: 10000;
+    constructor(config?: IFRClientConfig);
+    /** Check if wallet has sufficient IFR (balance + locked) */
+    checkAccess(params: AccessCheckParams): Promise<AccessResult>;
+    /**
+     * Benefit tier from IFR locked in IFRLock only (default preset Bronze/Silver/Gold/Platinum, or your
+     * own `tiers`). Fails closed: a failed IFRLock read throws instead of reporting 0.
+     */
+    getBenefitTier(wallet: string, tiers?: readonly BenefitTier[]): Promise<BenefitTierResult>;
+    /**
+     * @deprecated Legacy hold+lock access tier (0=none, 1=basic, 2=premium, 3=pro; balance + locked,
+     * 500 / 2,000 / 10,000). Use `getBenefitTier`. Removed in 1.0.
+     */
+    getTier(wallet: string): Promise<TierResult>;
+    /** Get IFR wallet balance */
+    getBalance(wallet: string): Promise<number>;
+    /** Get locked IFR balance */
+    getLockedBalance(wallet: string): Promise<number>;
+    /** Check if address is a registered builder */
+    isBuilder(address: string): Promise<boolean>;
+    /** Get total IFR supply */
+    getTotalSupply(): Promise<number>;
+    /** REST API check — no ethers dependency needed on caller side */
+    static apiCheck(params: {
+        wallet: string;
+        required?: string | number;
+        apiUrl?: string;
+    }): Promise<{
+        hasAccess: boolean;
+        balance: string;
+        tier: number;
+        tierName: string;
+    }>;
+}
+export default IFRClient;

package/dist/index.js

@@ -0,0 +1,303 @@
+"use strict";
+/**
+ * IFR SDK — Web3 Access Control for Builders
+ *
+ * Repository package: build and pack apps/sdk, then consume the locked tarball
+ *
+ * import { IFRClient } from "ifr-sdk"
+ * const ifr = new IFRClient({ network: "mainnet" })
+ * const access = await ifr.checkAccess({ wallet: "0x...", required: 1000 })
+ * if (access.hasAccess) enableAccess()
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IFRClient = exports.TIER_NAMES = exports.TIER_THRESHOLDS = exports.IFRReadError = exports.DEFAULT_TIERS = exports.IFR_DECIMALS = exports.RAILWAY_API = exports.IFR_API = exports.MAINNET_ADDRESSES = void 0;
+exports.validateTiers = validateTiers;
+exports.getBenefitTierFromRaw = getBenefitTierFromRaw;
+exports.getTierFromAmount = getTierFromAmount;
+exports.getTierName = getTierName;
+exports.parseIFRAmount = parseIFRAmount;
+exports.getTierFromRaw = getTierFromRaw;
+exports.evaluateAccessRaw = evaluateAccessRaw;
+const ethers_1 = require("ethers");
+__exportStar(require("./benefits"), exports);
+// ─── Constants ───────────────────────────────────────────────────────
+exports.MAINNET_ADDRESSES = {
+    ifrToken: "0x77e99917Eca8539c62F509ED1193ac36580A6e7B",
+    ifrLock: "0x769928aBDfc949D0718d8766a1C2d7dBb63954Eb",
+    /** CommitmentVault V1: price tranches never unlock (CV-01); existing time tranches unlockable. Do not create new locks here. */
+    commitmentVault: "0x0719d9eb28dF7f5e63F91fAc4Bbb2d579C4F73d3",
+    /** CommitmentVault V2: TIME_ONLY; new locks after Governance proposal #17 (fee exemption) executes. */
+    commitmentVaultV2: "0x8efae0C85ad6d44C731cAEDA1cBC275904Fc7c8F",
+    /** LendingVault V1: retired, borrowing permanently disabled. */
+    lendingVault: "0x974305Ab0EC905172e697271C3d7d385194EB9DF",
+    builderRegistry: "0xdfe6636DA47F8949330697e1dC5391267CEf0EE3",
+    governance: "0xc43d48E7FDA576C5022d0670B652A622E8caD041",
+};
+exports.IFR_API = "https://copilot-api.ifrunit.tech";
+/** @deprecated Use IFR_API. */
+exports.RAILWAY_API = exports.IFR_API;
+const DEFAULT_RPC = "https://ethereum-rpc.publicnode.com";
+exports.IFR_DECIMALS = 9;
+const TOKEN_ABI = [
+    "function balanceOf(address) view returns (uint256)",
+    "function decimals() view returns (uint8)",
+    "function totalSupply() view returns (uint256)",
+];
+const LOCK_ABI = [
+    "function lockedBalance(address) view returns (uint256)",
+    "function isLocked(address, uint256) view returns (bool)",
+];
+const BUILDER_REGISTRY_ABI = [
+    "function isBuilder(address) view returns (bool)",
+    "function getBuilderCount() view returns (uint256)",
+];
+exports.DEFAULT_TIERS = Object.freeze([
+    Object.freeze({ key: "bronze", name: "Bronze", minLocked: "1000" }),
+    Object.freeze({ key: "silver", name: "Silver", minLocked: "2500" }),
+    Object.freeze({ key: "gold", name: "Gold", minLocked: "5000" }),
+    Object.freeze({ key: "platinum", name: "Platinum", minLocked: "10000" }),
+]);
+/** Validates a tier list: non-empty, unique keys, strictly ascending exact 9-decimal thresholds. */
+function validateTiers(tiers) {
+    if (!Array.isArray(tiers) || tiers.length === 0)
+        throw new Error("tiers must be a non-empty array");
+    const keys = new Set();
+    let previous = -1n;
+    return tiers.map((tier) => {
+        if (!tier || typeof tier.key !== "string" || !tier.key || typeof tier.name !== "string" || !tier.name) {
+            throw new Error("each tier needs a non-empty key and name");
+        }
+        if (keys.has(tier.key))
+            throw new Error(`duplicate tier key: ${tier.key}`);
+        keys.add(tier.key);
+        const min = parseIFRAmount(tier.minLocked);
+        if (min <= previous)
+            throw new Error("tier thresholds must be strictly ascending");
+        previous = min;
+        return min;
+    });
+}
+/** Highest tier reached by an exact locked amount (9-decimal base units); no rounding. */
+function getBenefitTierFromRaw(lockedRaw, tiers = exports.DEFAULT_TIERS) {
+    const locked = (0, ethers_1.getBigInt)(lockedRaw);
+    if (locked < 0n)
+        throw new Error("IFR raw amounts must be non-negative");
+    const mins = validateTiers(tiers);
+    let level = 0;
+    for (let i = 0; i < mins.length; i++)
+        if (locked >= mins[i])
+            level = i + 1;
+    const tier = level ? tiers[level - 1] : null;
+    return { level, key: tier ? tier.key : null, name: tier ? tier.name : "None", lockedRaw: locked.toString() };
+}
+// ─── Read errors ─────────────────────────────────────────────────────
+/**
+ * Thrown when an on-chain read fails. The SDK never turns a failed read into 0 or false,
+ * so a caller cannot mistake an RPC outage for "no IFR locked" or "not a builder".
+ */
+class IFRReadError extends Error {
+    constructor(read, cause) {
+        super(`IFR read failed: ${read}${cause instanceof Error && cause.message ? ` (${cause.message})` : ""}`);
+        this.name = "IFRReadError";
+        this.read = read;
+        this.cause = cause;
+    }
+}
+exports.IFRReadError = IFRReadError;
+async function readOrThrow(read, call) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        throw new IFRReadError(read, error);
+    }
+}
+// ─── Legacy access tiers (deprecated) ────────────────────────────────
+/**
+ * @deprecated Legacy hold+lock access tiers (wallet balance + locked, 500 / 2,000 / 10,000).
+ * Not the project's benefit preset. Use `DEFAULT_TIERS` with `getBenefitTierFromRaw`. Removed in 1.0.
+ */
+exports.TIER_THRESHOLDS = { TIER1: 500, TIER2: 2000, TIER3: 10000 };
+/** @deprecated Legacy access tier names; use `DEFAULT_TIERS`. Removed in 1.0. */
+exports.TIER_NAMES = ["None", "Basic", "Premium", "Pro"];
+/** @deprecated Legacy hold+lock access tier; use `getBenefitTierFromRaw`. Removed in 1.0. */
+function getTierFromAmount(amount) {
+    if (amount >= exports.TIER_THRESHOLDS.TIER3)
+        return 3;
+    if (amount >= exports.TIER_THRESHOLDS.TIER2)
+        return 2;
+    if (amount >= exports.TIER_THRESHOLDS.TIER1)
+        return 1;
+    return 0;
+}
+/** @deprecated Legacy access tier name; use `getBenefitTierFromRaw(...).name`. Removed in 1.0. */
+function getTierName(tier) {
+    return exports.TIER_NAMES[tier] || "None";
+}
+function parseIFRAmount(value) {
+    const normalized = String(value);
+    if (!/^(0|[1-9]\d*)(\.\d{1,9})?$/.test(normalized)) {
+        throw new Error("IFR amount must be a non-negative decimal with at most 9 decimal places");
+    }
+    return (0, ethers_1.parseUnits)(normalized, exports.IFR_DECIMALS);
+}
+/** @deprecated Legacy hold+lock access tier; use `getBenefitTierFromRaw`. Removed in 1.0. */
+function getTierFromRaw(amount) {
+    const raw = (0, ethers_1.getBigInt)(amount);
+    if (raw >= parseIFRAmount(exports.TIER_THRESHOLDS.TIER3))
+        return 3;
+    if (raw >= parseIFRAmount(exports.TIER_THRESHOLDS.TIER2))
+        return 2;
+    if (raw >= parseIFRAmount(exports.TIER_THRESHOLDS.TIER1))
+        return 1;
+    return 0;
+}
+function evaluateAccessRaw(balanceRaw, lockedRaw, requiredRaw) {
+    const balance = (0, ethers_1.getBigInt)(balanceRaw);
+    const locked = (0, ethers_1.getBigInt)(lockedRaw);
+    const required = (0, ethers_1.getBigInt)(requiredRaw);
+    if (balance < 0n || locked < 0n || required < 0n) {
+        throw new Error("IFR raw amounts must be non-negative");
+    }
+    const total = balance + locked;
+    const tier = getTierFromRaw(total);
+    return { hasAccess: total >= required, total, tier, tierName: getTierName(tier) };
+}
+// ─── IFRClient ───────────────────────────────────────────────────────
+class IFRClient {
+    constructor(config = {}) {
+        this.TIER1 = exports.TIER_THRESHOLDS.TIER1;
+        this.TIER2 = exports.TIER_THRESHOLDS.TIER2;
+        this.TIER3 = exports.TIER_THRESHOLDS.TIER3;
+        if (config.network && config.network !== "mainnet") {
+            throw new Error("Sepolia addresses are not configured; IFRClient currently supports Mainnet only");
+        }
+        const rpcUrl = config.rpcUrl || DEFAULT_RPC;
+        this.apiUrl = config.apiUrl || exports.IFR_API;
+        this.provider = new ethers_1.JsonRpcProvider(rpcUrl);
+        this.token = new ethers_1.Contract(exports.MAINNET_ADDRESSES.ifrToken, TOKEN_ABI, this.provider);
+        this.lockContract = new ethers_1.Contract(exports.MAINNET_ADDRESSES.ifrLock, LOCK_ABI, this.provider);
+        this.registry = new ethers_1.Contract(exports.MAINNET_ADDRESSES.builderRegistry, BUILDER_REGISTRY_ABI, this.provider);
+    }
+    /** Check if wallet has sufficient IFR (balance + locked) */
+    async checkAccess(params) {
+        const { wallet, required, checkLocked = true } = params;
+        if (!(0, ethers_1.isAddress)(wallet))
+            throw new Error("Invalid wallet address");
+        const requiredRaw = parseIFRAmount(required);
+        const [balanceRaw, lockedRaw] = await Promise.all([
+            this.token.balanceOf(wallet),
+            checkLocked
+                ? readOrThrow("IFRLock.lockedBalance", () => this.lockContract.lockedBalance(wallet))
+                : Promise.resolve(0n),
+        ]);
+        const evaluated = evaluateAccessRaw(balanceRaw, lockedRaw, requiredRaw);
+        const balance = Number((0, ethers_1.formatUnits)(balanceRaw, exports.IFR_DECIMALS));
+        const locked = Number((0, ethers_1.formatUnits)(lockedRaw, exports.IFR_DECIMALS));
+        const total = Number((0, ethers_1.formatUnits)(evaluated.total, exports.IFR_DECIMALS));
+        const requiredFormatted = Number((0, ethers_1.formatUnits)(requiredRaw, exports.IFR_DECIMALS));
+        return {
+            hasAccess: evaluated.hasAccess,
+            balance,
+            locked,
+            total,
+            required: requiredFormatted,
+            tier: evaluated.tier,
+            tierName: evaluated.tierName,
+            balanceRaw: balanceRaw.toString(),
+            lockedRaw: lockedRaw.toString(),
+            totalRaw: evaluated.total.toString(),
+            requiredRaw: requiredRaw.toString(),
+        };
+    }
+    /**
+     * Benefit tier from IFR locked in IFRLock only (default preset Bronze/Silver/Gold/Platinum, or your
+     * own `tiers`). Fails closed: a failed IFRLock read throws instead of reporting 0.
+     */
+    async getBenefitTier(wallet, tiers = exports.DEFAULT_TIERS) {
+        if (!(0, ethers_1.isAddress)(wallet))
+            throw new Error("Invalid wallet address");
+        validateTiers(tiers);
+        const lockedRaw = await this.lockContract.lockedBalance(wallet);
+        return getBenefitTierFromRaw(lockedRaw, tiers);
+    }
+    /**
+     * @deprecated Legacy hold+lock access tier (0=none, 1=basic, 2=premium, 3=pro; balance + locked,
+     * 500 / 2,000 / 10,000). Use `getBenefitTier`. Removed in 1.0.
+     */
+    async getTier(wallet) {
+        if (!(0, ethers_1.isAddress)(wallet))
+            throw new Error("Invalid wallet address");
+        const [balanceRaw, lockedRaw] = await Promise.all([
+            this.token.balanceOf(wallet),
+            readOrThrow("IFRLock.lockedBalance", () => this.lockContract.lockedBalance(wallet)),
+        ]);
+        const balance = Number((0, ethers_1.formatUnits)(balanceRaw, exports.IFR_DECIMALS));
+        const locked = Number((0, ethers_1.formatUnits)(lockedRaw, exports.IFR_DECIMALS));
+        const totalRaw = (0, ethers_1.getBigInt)(balanceRaw) + (0, ethers_1.getBigInt)(lockedRaw);
+        const tier = getTierFromRaw(totalRaw);
+        return {
+            tier,
+            tierName: getTierName(tier),
+            balance,
+            locked,
+            balanceRaw: balanceRaw.toString(),
+            lockedRaw: lockedRaw.toString(),
+            totalRaw: totalRaw.toString(),
+        };
+    }
+    /** Get IFR wallet balance */
+    async getBalance(wallet) {
+        if (!(0, ethers_1.isAddress)(wallet))
+            throw new Error("Invalid wallet address");
+        const raw = await this.token.balanceOf(wallet);
+        return Number((0, ethers_1.formatUnits)(raw, exports.IFR_DECIMALS));
+    }
+    /** Get locked IFR balance */
+    async getLockedBalance(wallet) {
+        if (!(0, ethers_1.isAddress)(wallet))
+            throw new Error("Invalid wallet address");
+        const raw = await readOrThrow("IFRLock.lockedBalance", () => this.lockContract.lockedBalance(wallet));
+        return Number((0, ethers_1.formatUnits)(raw, exports.IFR_DECIMALS));
+    }
+    /** Check if address is a registered builder */
+    async isBuilder(address) {
+        if (!(0, ethers_1.isAddress)(address))
+            throw new Error("Invalid address");
+        return readOrThrow("BuilderRegistry.isBuilder", () => this.registry.isBuilder(address));
+    }
+    /** Get total IFR supply */
+    async getTotalSupply() {
+        const raw = await this.token.totalSupply();
+        return Number((0, ethers_1.formatUnits)(raw, exports.IFR_DECIMALS));
+    }
+    /** REST API check — no ethers dependency needed on caller side */
+    static async apiCheck(params) {
+        if (!(0, ethers_1.isAddress)(params.wallet))
+            throw new Error("Invalid wallet address");
+        const required = params.required ?? 1000;
+        parseIFRAmount(required);
+        const url = new URL("/api/ifr/check", params.apiUrl || exports.IFR_API);
+        url.search = new URLSearchParams({ wallet: params.wallet, required: String(required) }).toString();
+        const resp = await fetch(url.toString());
+        if (!resp.ok)
+            throw new Error(`API error: ${resp.status}`);
+        return resp.json();
+    }
+}
+exports.IFRClient = IFRClient;
+exports.default = IFRClient;

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "ifr-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "IFR Protocol SDK - exact access checks and signer-neutral Benefits checkout",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20 <23"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node test/sdk.test.cjs",
+    "test:package": "npm run build && node test/package-consumer.cjs",
+    "prepublishOnly": "npm test && npm run test:package"
+  },
+  "keywords": [
+    "ifr",
+    "web3",
+    "access-control",
+    "lock",
+    "defi",
+    "ethereum"
+  ],
+  "license": "MIT",
+  "author": "Inferno Protocol contributors",
+  "homepage": "https://github.com/NeaBouli/inferno/tree/main/apps/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/NeaBouli/inferno/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NeaBouli/inferno.git",
+    "directory": "apps/sdk"
+  },
+  "dependencies": {
+    "ethers": "^6.15.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}