@telaro/sacp 1.0.0

package/dist/runtime.d.ts

@@ -0,0 +1,244 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import { type FetchedJob, type FetchedVerdict } from "./job.js";
+import { listOfferings, type FetchedOffering, type RegisterOfferingParams, type UpdateOfferingParams } from "./offering.js";
+import { type FetchedNegotiation } from "./negotiation.js";
+import { type FetchedSacpConfig } from "./take_rate.js";
+import type { VerdictWinner } from "./types.js";
+import type { SacpSigner } from "./signer.js";
+/**
+ * v0.8 — high-level runtime layer.
+ *
+ * Wraps the low-level instruction builders in an `SacpClient` +
+ * `JobSession` pair so the typical consumer writes intent ("this
+ * client is accepting the work") rather than account derivations,
+ * Treasury ATA bootstraps, and explicit `sendAndConfirmTransaction`
+ * boilerplate.
+ *
+ * Low-level builders stay exported. The runtime is purely additive.
+ */
+/** Per-role keys for a Job that the client needs to drive end-to-end. */
+export interface JobActors {
+    client: SacpSigner;
+    provider?: SacpSigner;
+    /** Evaluator signer is optional — only needed when this runtime
+     * instance plays the evaluator role. */
+    evaluator?: SacpSigner;
+}
+/** Cached on-chain state for a Job + derived ATAs the runtime needs. */
+export interface JobSnapshot {
+    job: FetchedJob;
+    config: FetchedSacpConfig;
+    clientAta: PublicKey;
+    providerAta: PublicKey;
+    evaluatorAta: PublicKey;
+    treasuryAta: PublicKey;
+}
+/** What a given role can do right now, given the Job's state. */
+export type JobAction = "fund" | "submit_work" | "accept" | "dispute" | "submit_verdict" | "reclaim" | "record_verdict" | "publish_settlement";
+export interface SacpClientConfig {
+    connection: Connection;
+    /**
+     * Optional fee payer for any helper that pre-creates an ATA on
+     * behalf of a role (e.g. ensuring the Treasury ATA before settle).
+     * Falls back to whichever signer drives the relevant action.
+     */
+    payer?: SacpSigner;
+}
+/**
+ * Top-level entry point. One instance per RPC connection; spin up new
+ * `JobSession`s for each Job you create or attach to.
+ */
+export declare class SacpClient {
+    readonly connection: Connection;
+    readonly payer: SacpSigner | undefined;
+    constructor(config: SacpClientConfig);
+    /**
+     * Create a new Job and return a session you can drive through its
+     * lifecycle. Combines `create_job` + the first `fund_job` into the
+     * caller's hands — the session begins in the `Open` state, and the
+     * client funds it via `session.fund()`.
+     */
+    createJob(params: {
+        jobId: bigint;
+        actors: JobActors;
+        bondMint: PublicKey;
+        amount: bigint;
+        workUri: string;
+        submitWindowSecs?: bigint;
+    }): Promise<JobSession>;
+    /**
+     * Attach to an existing Job. Use this on the provider/evaluator side
+     * after they receive a Job ID off-band (webhook, queue, watcher).
+     */
+    openJob(args: {
+        jobId: bigint;
+        actors: JobActors;
+        bondMint?: PublicKey;
+    }): Promise<JobSession>;
+    /** v0.9 — Offering registry namespace. Provider operations
+     * (register / update / close) plus buyer-side discovery (browse /
+     * createJobFromOffering). */
+    get offering(): OfferingNamespace;
+    /** v1.0 Phase 8 — Negotiation namespace. propose / counter /
+     * accept / materialize / cancel + session helper. */
+    get negotiation(): NegotiationNamespace;
+    /**
+     * Ensure the protocol Treasury ATA exists for `bondMint`. Idempotent.
+     * Pre-v0.6 there was nothing to do; v0.6+ every settlement reads
+     * this account, so call once per mint before the first settle.
+     *
+     * Works with any `SacpSigner` (`LocalSigner`, `RemoteSigner`,
+     * `WalletAdapterSigner`) — builds the create-ATA instruction and
+     * delegates the send to the signer. Skips the network call entirely
+     * when the ATA already exists.
+     */
+    ensureTreasuryAta(bondMint: PublicKey, payer?: SacpSigner): Promise<PublicKey>;
+}
+/**
+ * Stateful handle to one Job. Tracks role keys, derived ATAs, and
+ * fetches the current on-chain state on demand. Each lifecycle action
+ * (fund, submitWork, accept, dispute, submitVerdict, reclaim) is a
+ * single SDK call.
+ */
+export declare class JobSession {
+    readonly client: SacpClient;
+    readonly jobId: bigint;
+    readonly bondMint: PublicKey;
+    readonly actors: JobActors;
+    readonly clientAta: PublicKey;
+    readonly providerAta: PublicKey;
+    readonly evaluatorAta: PublicKey;
+    readonly treasuryAta: PublicKey;
+    private cached;
+    private constructor();
+    static attach(client: SacpClient, args: {
+        jobId: bigint;
+        actors: JobActors;
+        bondMint: PublicKey;
+    }): JobSession;
+    /** Force-refresh the on-chain Job state + Config (take rate may
+     * have shifted between settlement calls). */
+    refresh(): Promise<JobSnapshot>;
+    /** Most recently fetched Job snapshot, or `null` if `refresh()`
+     * hasn't been called yet. */
+    get snapshot(): JobSnapshot | null;
+    /**
+     * What this session's actors can do right now. Returns one entry
+     * per (role, action) pair so a UI can drive the right button per
+     * connected wallet.
+     */
+    availableActions(): Promise<Array<{
+        role: "client" | "provider" | "evaluator" | "anyone";
+        action: JobAction;
+    }>>;
+    fund(amount?: bigint): Promise<string>;
+    submitWork(submissionUri: string): Promise<string>;
+    accept(): Promise<string>;
+    dispute(reasonHash: Uint8Array): Promise<string>;
+    submitVerdict(winner: VerdictWinner, options?: {
+        evidenceUri?: string;
+    }): Promise<string>;
+    reclaim(): Promise<string>;
+    fetchVerdict(): Promise<FetchedVerdict | null>;
+}
+/**
+ * v0.9 — Offering helpers grouped behind `sacp.offering.*`. Each
+ * method is a one-shot thin wrapper around the low-level builders so
+ * providers register a catalog entry, browse / discover other
+ * providers, and buyers turn an Offering into a `JobSession` in a
+ * single call.
+ */
+export declare class OfferingNamespace {
+    private readonly client;
+    constructor(client: SacpClient);
+    /** Register a new Offering as the provider. Returns the offering
+     * PDA + the signed tx signature. */
+    register(provider: SacpSigner, params: Omit<RegisterOfferingParams, "provider">): Promise<{
+        pda: PublicKey;
+        signature: string;
+    }>;
+    update(provider: SacpSigner, params: Omit<UpdateOfferingParams, "provider">): Promise<string>;
+    close(provider: SacpSigner, slotId: number): Promise<string>;
+    fetch(provider: PublicKey, slotId: number): Promise<FetchedOffering | null>;
+    browse(filter?: Parameters<typeof listOfferings>[1]): Promise<FetchedOffering[]>;
+    /**
+     * Turn an Offering into a Job in one call. Pulls bond_mint and
+     * default_evaluator from the Offering, lets the buyer override the
+     * evaluator and supply work_uri + amount. Validates amount falls
+     * within the Offering's min/max band.
+     *
+     * The returned `JobSession` is already in the `Open` state — call
+     * `.fund()` immediately to lock the escrow.
+     */
+    createJobFrom(offering: FetchedOffering, args: {
+        jobId: bigint;
+        client: SacpSigner;
+        provider: SacpSigner;
+        /** Override the Offering's default evaluator. The override
+         * needs to be a real signer (the runtime stubs the rest). */
+        evaluator: SacpSigner;
+        amount: bigint;
+        workUri: string;
+        submitWindowSecs?: bigint;
+    }): Promise<JobSession>;
+}
+/**
+ * v1.0 Phase 8 — Negotiation namespace + NegotiationSession.
+ *
+ * `sacp.negotiation.propose(...)` opens a Negotiation. The returned
+ * session exposes counter / accept / cancel / materialize, plus
+ * `availableActions()` so a UI knows whose turn it is.
+ */
+export declare class NegotiationNamespace {
+    private readonly client;
+    constructor(client: SacpClient);
+    propose(buyer: SacpSigner, args: {
+        provider: PublicKey;
+        evaluator: PublicKey;
+        bondMint: PublicKey;
+        negotiationId: bigint;
+        amount: bigint;
+        workUri: string;
+        submitWindowSecs: bigint;
+    }): Promise<NegotiationSession>;
+    attach(args: {
+        buyer: PublicKey;
+        negotiationId: bigint;
+    }): NegotiationSession;
+    fetch(buyer: PublicKey, negotiationId: bigint): Promise<FetchedNegotiation | null>;
+}
+export interface NegotiationSessionAction {
+    role: "buyer" | "provider";
+    action: "counter" | "accept" | "cancel" | "materialize";
+}
+export declare class NegotiationSession {
+    readonly client: SacpClient;
+    readonly buyer: PublicKey;
+    readonly negotiationId: bigint;
+    constructor(args: {
+        client: SacpClient;
+        buyer: PublicKey;
+        negotiationId: bigint;
+    });
+    refresh(): Promise<FetchedNegotiation>;
+    counter(signer: SacpSigner, terms: {
+        amount: bigint;
+        workUri: string;
+        submitWindowSecs: bigint;
+    }): Promise<string>;
+    accept(signer: SacpSigner): Promise<string>;
+    cancel(signer: SacpSigner): Promise<string>;
+    /**
+     * Buyer-only. After the negotiation is Accepted, mint the Job +
+     * escrow vault. Returns the created jobId so callers can attach a
+     * `JobSession` immediately.
+     */
+    materialize(buyer: SacpSigner, args: {
+        jobId: bigint;
+        bondMint: PublicKey;
+    }): Promise<bigint>;
+    /** Returns which side(s) can act, given the current state + last
+     * proposer. UIs use this to enable / disable buttons. */
+    availableActions(): Promise<NegotiationSessionAction[]>;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,SAAS,EACV,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EAWL,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAKL,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAOL,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAY,aAAa,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;GAUG;AAEH,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB;4CACwC;IACxC,SAAS,CAAC,EAAE,UAAU,CAAC;CACxB;AAED,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,SAAS,CAAC;IACrB,WAAW,EAAE,SAAS,CAAC;IACvB,YAAY,EAAE,SAAS,CAAC;IACxB,WAAW,EAAE,SAAS,CAAC;CACxB;AAED,iEAAiE;AACjE,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,aAAa,GACb,QAAQ,GACR,SAAS,GACT,gBAAgB,GAChB,SAAS,GACT,gBAAgB,GAChB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,UAAU,CAAC;IACvB;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,UAAU;IACrB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;gBAE3B,MAAM,EAAE,gBAAgB;IAKpC;;;;;OAKG;IACG,SAAS,CAAC,MAAM,EAAE;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,SAAS,CAAC;QAClB,QAAQ,EAAE,SAAS,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,GAAG,OAAO,CAAC,UAAU,CAAC;IAmCvB;;;OAGG;IACG,OAAO,CAAC,IAAI,EAAE;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,SAAS,CAAC;QAClB,QAAQ,CAAC,EAAE,SAAS,CAAC;KACtB,GAAG,OAAO,CAAC,UAAU,CAAC;IAYvB;;iCAE6B;IAC7B,IAAI,QAAQ,IAAI,iBAAiB,CAEhC;IAED;yDACqD;IACrD,IAAI,WAAW,IAAI,oBAAoB,CAEtC;IAED;;;;;;;;;OASG;IACG,iBAAiB,CACrB,QAAQ,EAAE,SAAS,EACnB,KAAK,CAAC,EAAE,UAAU,GACjB,OAAO,CAAC,SAAS,CAAC;CAsBtB;AAED;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC;IAChC,OAAO,CAAC,MAAM,CAA+D;IAE7E,OAAO;IAoCP,MAAM,CAAC,MAAM,CACX,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,CAAC;QAAC,QAAQ,EAAE,SAAS,CAAA;KAAE,GAC9D,UAAU;IASb;iDAC6C;IACvC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC;IAmBrC;iCAC6B;IAC7B,IAAI,QAAQ,IAAI,WAAW,GAAG,IAAI,CAUjC;IAED;;;;OAIG;IACG,gBAAgB,IAAI,OAAO,CAC/B,KAAK,CAAC;QAAE,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;QAAC,MAAM,EAAE,SAAS,CAAA;KAAE,CAAC,CACnF;IAgCK,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAWtC,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYlD,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAczB,OAAO,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAShD,aAAa,CACjB,MAAM,EAAE,aAAa,EACrB,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GACjC,OAAO,CAAC,MAAM,CAAC;IA8BZ,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAS1B,YAAY,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;CAGrD;AAED;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,UAAU;IAE/C;wCACoC;IAC9B,QAAQ,CACZ,QAAQ,EAAE,UAAU,EACpB,MAAM,EAAE,IAAI,CAAC,sBAAsB,EAAE,UAAU,CAAC,GAC/C,OAAO,CAAC;QAAE,GAAG,EAAE,SAAS,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAS3C,MAAM,CACV,QAAQ,EAAE,UAAU,EACpB,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,UAAU,CAAC,GAC7C,OAAO,CAAC,MAAM,CAAC;IAQZ,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ5D,KAAK,CACT,QAAQ,EAAE,SAAS,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAI5B,MAAM,CACV,MAAM,CAAC,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,GAC3C,OAAO,CAAC,eAAe,EAAE,CAAC;IAI7B;;;;;;;;OAQG;IACG,aAAa,CACjB,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,UAAU,CAAC;QACnB,QAAQ,EAAE,UAAU,CAAC;QACrB;qEAC6D;QAC7D,SAAS,EAAE,UAAU,CAAC;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,GACA,OAAO,CAAC,UAAU,CAAC;CA8BvB;AAED;;;;;;GAMG;AACH,qBAAa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,UAAU;IAEzC,OAAO,CACX,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE;QACJ,QAAQ,EAAE,SAAS,CAAC;QACpB,SAAS,EAAE,SAAS,CAAC;QACrB,QAAQ,EAAE,SAAS,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,GACA,OAAO,CAAC,kBAAkB,CAAC;IAmB9B,MAAM,CAAC,IAAI,EAAE;QACX,KAAK,EAAE,SAAS,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,kBAAkB;IAQhB,KAAK,CACT,KAAK,EAAE,SAAS,EAChB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;CAGtC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC;IAC3B,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAC;CACzD;AAED,qBAAa,kBAAkB;IAC7B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBAEnB,IAAI,EAAE;QAChB,MAAM,EAAE,UAAU,CAAC;QACnB,KAAK,EAAE,SAAS,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;KACvB;IAMK,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC;IActC,OAAO,CACX,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE;QACL,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,GACA,OAAO,CAAC,MAAM,CAAC;IAYZ,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAS3C,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IASjD;;;;OAIG;IACG,WAAW,CACf,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,SAAS,CAAA;KAAE,GAC3C,OAAO,CAAC,MAAM,CAAC;IAclB;6DACyD;IACnD,gBAAgB,IAAI,OAAO,CAAC,wBAAwB,EAAE,CAAC;CAe9D"}