@kehtus/proportion-sdk 0.5.0 → 1.2.0

package/dist/challenge/api.js

@@ -0,0 +1,173 @@
+/**
+ * Thin typed client for the challenge-service public HTTP API. Optional — activated by
+ * `challengeApiUrl` in SDKConfig. It only maps SDK types onto the service wire formats;
+ * pricing, admission, and submission policy live server-side.
+ *
+ * Endpoints: POST /quote (quote-signer), POST /intents/open, POST /intents/close (relayer),
+ * POST /purchase (gasless buyChallenge via a signed ForwardRequest).
+ */
+export class ChallengeApiClient {
+    fetchFn;
+    baseUrl;
+    constructor(baseUrl, fetchFn) {
+        this.fetchFn = fetchFn;
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+    }
+    async postRaw(path, body) {
+        const fetchFn = this.fetchFn ?? globalThis.fetch;
+        if (!fetchFn)
+            throw new Error("fetch is not available; pass fetchFn in SDKConfig");
+        const res = await fetchFn(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        const json = (await res.json().catch(() => ({})));
+        return { ok: res.ok, status: res.status, json };
+    }
+    static wireError(path, status, json) {
+        const error = typeof json.error === "string" ? json.error : `HTTP ${status}`;
+        const detail = typeof json.detail === "string" ? `: ${json.detail}` : "";
+        return new Error(`challenge-service ${path} failed (${status}) ${error}${detail}`);
+    }
+    async post(path, body) {
+        const { ok, status, json } = await this.postRaw(path, body);
+        if (!ok)
+            throw ChallengeApiClient.wireError(path, status, json);
+        return json;
+    }
+    /**
+     * Submit endpoints reply with meaningful terminal bodies on non-2xx codes too:
+     * 409 {"status":"cached"} (dedup replay of an already-submitted intent),
+     * 422 {"status":"reverted", tx_hash, phase, ...} (mined but reverted),
+     * 503 {"status":"queued"} (broadcast deferred to recovery). Any body carrying a
+     * `status` field is a submit outcome, not a transport error — only error-keyed
+     * bodies (e.g. 400 validation, 503 dedup_released) throw.
+     */
+    async postSubmit(path, body) {
+        const { ok, status, json } = await this.postRaw(path, body);
+        if (typeof json.status === "string")
+            return ChallengeApiClient.parseSubmitResponse(json);
+        if (!ok)
+            throw ChallengeApiClient.wireError(path, status, json);
+        return ChallengeApiClient.parseSubmitResponse(json);
+    }
+    // u64 wire fields are JSON numbers; guard the bigint → number conversion.
+    static toJsonNumber(value, field) {
+        if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < 0n) {
+            throw new Error(`${field} does not fit a JSON number: ${value}`);
+        }
+        return Number(value);
+    }
+    static parseSubmitResponse(raw) {
+        return {
+            status: raw.status,
+            txId: typeof raw.tx_id === "string" ? raw.tx_id : undefined,
+            txHash: typeof raw.tx_hash === "string" ? raw.tx_hash : undefined,
+            phase: typeof raw.phase === "number" ? raw.phase : undefined,
+            challengeFailed: typeof raw.challenge_failed === "boolean" ? raw.challenge_failed : undefined,
+        };
+    }
+    /**
+     * Request a builder-signed quote from the quote-signer. Verify the returned signature
+     * and fee (ChallengeFactoryModule.verifyQuote / previewQuote) before paying.
+     */
+    async requestQuote(req) {
+        const raw = await this.post("/quote", {
+            account_owner: req.accountOwner,
+            ...(req.payer ? { payer: req.payer } : {}),
+            allocation: req.allocation.toString(),
+            drawdown_bps: req.drawdownBps,
+            daily_drawdown_enabled: req.dailyDrawdownEnabled,
+            trading_days_enabled: req.tradingDaysEnabled,
+            challenge_type: req.challengeType,
+            final_target_profit_bps: req.finalTargetProfitBps,
+            price_multiplier_bps: req.priceMultiplierBps,
+        });
+        const q = raw.quote;
+        const quote = {
+            accountOwner: q.accountOwner,
+            payer: q.payer,
+            builder: q.builder,
+            referrer: q.referrer,
+            allocation: BigInt(q.allocation),
+            drawdownBps: Number(q.drawdownBps),
+            dailyDrawdownEnabled: q.dailyDrawdownEnabled,
+            tradingDaysEnabled: q.tradingDaysEnabled,
+            challengeType: Number(q.challengeType),
+            finalTargetProfitBps: Number(q.finalTargetProfitBps),
+            priceMultiplierBps: Number(q.priceMultiplierBps),
+            quotedChallengeFee: BigInt(q.quotedChallengeFee),
+            minBuilderVaultAmount: BigInt(q.minBuilderVaultAmount),
+            deadline: BigInt(q.deadline),
+            nonce: BigInt(q.nonce),
+            quoteConfigNonce: BigInt(q.quoteConfigNonce),
+            builderQuoteEpoch: BigInt(q.builderQuoteEpoch),
+        };
+        return {
+            quote,
+            builderSignature: raw.builderSignature,
+            quoteDigest: raw.quoteDigest,
+            maxChallengeFee: BigInt(raw.maxChallengeFee),
+            fees: {
+                challengeFee: BigInt(raw.fees.challengeFee),
+                builderAmount: BigInt(raw.fees.builderAmount),
+                protocolFee: BigInt(raw.fees.protocolFee),
+                referralFee: BigInt(raw.fees.referralFee),
+                maxNotional: BigInt(raw.fees.maxNotional),
+            },
+        };
+    }
+    /** Submit a signed open intent to the relayer (gasless; relayer pays gas). */
+    async submitOpenIntent(signed) {
+        const { intent, signature } = signed;
+        return this.postSubmit("/intents/open", {
+            owner: intent.owner,
+            account: intent.account,
+            market: intent.market,
+            is_long: intent.isLong,
+            margin: intent.margin.toString(),
+            notional: intent.notional.toString(),
+            max_price: ChallengeApiClient.toJsonNumber(intent.maxPrice, "maxPrice"),
+            min_price: ChallengeApiClient.toJsonNumber(intent.minPrice, "minPrice"),
+            nonce: intent.nonce.toString(),
+            deadline: ChallengeApiClient.toJsonNumber(intent.deadline, "deadline"),
+            signature,
+        });
+    }
+    /** Submit a signed close intent to the relayer (gasless; relayer pays gas). */
+    async submitCloseIntent(signed) {
+        const { intent, signature } = signed;
+        return this.postSubmit("/intents/close", {
+            owner: intent.owner,
+            account: intent.account,
+            position_id: ChallengeApiClient.toJsonNumber(intent.positionId, "positionId"),
+            max_price: ChallengeApiClient.toJsonNumber(intent.maxPrice, "maxPrice"),
+            min_price: ChallengeApiClient.toJsonNumber(intent.minPrice, "minPrice"),
+            nonce: intent.nonce.toString(),
+            deadline: ChallengeApiClient.toJsonNumber(intent.deadline, "deadline"),
+            signature,
+        });
+    }
+    /**
+     * Gasless challenge purchase: a ForwardRequest signed by the payer whose `data` MUST be
+     * buyChallengeWithPermit calldata targeting the factory — the service strictly decodes
+     * that selector and requires permitValue >= quotedChallengeFee; plain buyChallenge
+     * calldata is rejected with a validation error. Build the calldata with
+     * ChallengeFactoryModule.encodeBuyChallengeWithPermit, wrap it via
+     * ForwarderModule.signRequest({ to: factory, data }), and submit here. The service
+     * consumes its own builder quotes only.
+     */
+    async purchase(request) {
+        return this.postSubmit("/purchase", {
+            from: request.from,
+            to: request.to,
+            value: request.value.toString(),
+            gas: request.gas.toString(),
+            deadline: request.deadline,
+            data: request.data,
+            signature: request.signature,
+        });
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/challenge/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/challenge/api.ts"],"names":[],"mappings":"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"}

package/dist/challenge/factory.d.ts

@@ -0,0 +1,165 @@
+import { type Address, type Chain, type Hash, type Hex, type PublicClient, type WalletClient } from "viem";
+import type { ChallengeFeeBreakdown, ChallengePricingConfig, ChallengeQuote, ChallengeTerms, QuoteVerification } from "./types.js";
+export declare const CHALLENGE_QUOTE_TYPES: {
+    readonly ChallengeQuote: readonly [{
+        readonly name: "accountOwner";
+        readonly type: "address";
+    }, {
+        readonly name: "payer";
+        readonly type: "address";
+    }, {
+        readonly name: "builder";
+        readonly type: "address";
+    }, {
+        readonly name: "referrer";
+        readonly type: "address";
+    }, {
+        readonly name: "allocation";
+        readonly type: "uint96";
+    }, {
+        readonly name: "drawdownBps";
+        readonly type: "uint16";
+    }, {
+        readonly name: "dailyDrawdownEnabled";
+        readonly type: "bool";
+    }, {
+        readonly name: "tradingDaysEnabled";
+        readonly type: "bool";
+    }, {
+        readonly name: "challengeType";
+        readonly type: "uint8";
+    }, {
+        readonly name: "finalTargetProfitBps";
+        readonly type: "uint16";
+    }, {
+        readonly name: "priceMultiplierBps";
+        readonly type: "uint16";
+    }, {
+        readonly name: "quotedChallengeFee";
+        readonly type: "uint256";
+    }, {
+        readonly name: "minBuilderVaultAmount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint64";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "quoteConfigNonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "builderQuoteEpoch";
+        readonly type: "uint256";
+    }];
+};
+type AddressResolver = Address | (() => Promise<Address>);
+/**
+ * ChallengeFactory module — signed-quote purchases plus builder quote administration.
+ *
+ * Quotes are priced and signed by the builder's quote-signer service; the SDK's job is to
+ * verify them (verifyQuote / previewQuote) and spend them (buyChallenge). Owner pricing/risk
+ * config setters are multisig territory and intentionally not covered.
+ */
+export declare class ChallengeFactoryModule {
+    private publicClient;
+    private walletClient;
+    private chain;
+    private addressResolver;
+    /** builderRegistry is immutable on the factory — cached after the first delegate check. */
+    private builderRegistryCache;
+    private resolvedAddress;
+    private addressPromise;
+    constructor(publicClient: PublicClient, walletClient: WalletClient | undefined, chain: Chain, addressResolver: AddressResolver);
+    /**
+     * Resolved ChallengeFactory address, lazily fetched when constructed with a resolver
+     * function (e.g. from the indexer's ProtocolConfig). The in-flight promise is cached so
+     * concurrent callers share one lookup; a failed resolution clears the cache for retry.
+     * Once resolved, the address is memoized so the synchronous `address`/`quoteDigest`
+     * accessors below work without an extra round trip.
+     */
+    getAddress(): Promise<Address>;
+    /** Throws if constructed with a resolver and no async method has resolved it yet — see getAddress(). */
+    get address(): Address;
+    private requireWallet;
+    private write;
+    /** Factory wiring + quote freshness anchors (quoteConfigNonce invalidates all quotes on config change). */
+    getConfig(): Promise<{
+        vault: Address;
+        oracle: Address;
+        implementation: Address;
+        builderRegistry: Address;
+        owner: Address;
+        pendingOwner: Address;
+        quoteConfigNonce: bigint;
+        maxOpenPositions: number;
+        minHoldBlocks: bigint;
+        accountsCount: bigint;
+    }>;
+    getPricingConfig(): Promise<ChallengePricingConfig>;
+    /** Immutable terms a challenge account was minted with. */
+    getChallengeTerms(account: Address): Promise<ChallengeTerms>;
+    /**
+     * On-chain fee re-derivation for a quote. This is the authoritative pricing check —
+     * do NOT re-implement ChallengePricingLib math off-chain, it drifts on config changes.
+     */
+    previewQuote(quote: ChallengeQuote): Promise<ChallengeFeeBreakdown>;
+    /** Local EIP-712 digest of a quote (no RPC; matches challengeQuoteDigest on-chain). Requires the address to already be resolved — see getAddress(). */
+    quoteDigest(quote: ChallengeQuote): Hex;
+    private digestFor;
+    /**
+     * Verify a builder quote signature before paying for it. Recovers the ECDSA signer locally,
+     * accepts the builder EOA directly, and falls back to a MainVault.delegateBuilder registry
+     * check over RPC. ERC-1271 contract signatures cannot be recovered off-chain — those return
+     * valid=false and must be validated by on-chain simulation instead.
+     */
+    verifyQuote(quote: ChallengeQuote, signature: Hex): Promise<QuoteVerification>;
+    /** Deterministic clone address for the trader's next challenge with this builder. */
+    predictChallengeAccount(trader: Address, builder: Address): Promise<Address>;
+    getAccountAt(index: bigint): Promise<Address>;
+    /** Current per-builder epoch; bumping it (incrementBuilderQuoteEpoch) voids all prior quotes. */
+    getBuilderQuoteEpoch(builder: Address): Promise<bigint>;
+    isQuoteNonceUsed(builder: Address, nonce: bigint): Promise<boolean>;
+    /**
+     * Direct-gas purchase of a builder-signed quote. Requires prior USDC allowance from the
+     * payer to the ChallengeVault. `maxChallengeFee` defaults to the quoted fee (no slippage).
+     * For gasless UX submit through the challenge-service /purchase route instead.
+     */
+    buyChallenge(quote: ChallengeQuote, builderSignature: Hex, maxChallengeFee?: bigint): Promise<Hash>;
+    /**
+     * Calldata for buyChallengeWithPermit — the ONLY call shape the challenge-service
+     * gasless POST /purchase route accepts (it strictly decodes this selector and requires
+     * permitValue >= quotedChallengeFee). Wrap it in a ForwardRequest via
+     * ForwarderModule.signRequest({ to: factory, data }) and submit with
+     * ChallengeApiClient.purchase.
+     */
+    static encodeBuyChallengeWithPermit(p: {
+        quote: ChallengeQuote;
+        builderSignature: Hex;
+        maxChallengeFee?: bigint;
+        permitValue: bigint;
+        permitDeadline: bigint;
+        v: number;
+        r: Hex;
+        s: Hex;
+    }): Hex;
+    /** Purchase with an ERC-2612 permit (first-time users with no vault allowance). */
+    buyChallengeWithPermit(p: {
+        quote: ChallengeQuote;
+        builderSignature: Hex;
+        maxChallengeFee?: bigint;
+        permitValue: bigint;
+        permitDeadline: bigint;
+        v: number;
+        r: Hex;
+        s: Hex;
+    }): Promise<Hash>;
+    /** Void one outstanding quote nonce (builder or its delegate). */
+    cancelQuoteNonce(nonce: bigint): Promise<Hash>;
+    cancelQuoteNonces(nonces: bigint[]): Promise<Hash>;
+    /** Void ALL outstanding quotes of the calling builder at once. */
+    incrementBuilderQuoteEpoch(): Promise<Hash>;
+}
+export {};
+//# sourceMappingURL=factory.d.ts.map

package/dist/challenge/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/challenge/factory.ts"],"names":[],"mappings":"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"}