@avow-finance/sdk 0.0.0-stage → 0.2.0

package/dist/agent.d.ts

@@ -0,0 +1,261 @@
+import { type Approval, type AvowDomain, type ChainedTerms, type CheckedDependency, type Mandate, type RailToken, type ReasonCode, type RefusalLayer, type Signed, type SignedAgreement, type StartReceipt, type SupplierProfile, type Terms, type TermsAgreement, type TermsProfile } from '@avow-finance/spec';
+import { type DependencyDeps, type DependencyRefusal, type LockedBacking } from '@avow-finance/verifier';
+import { type Address, type Chain, type Client, type Hex, type Transport } from 'viem';
+import type { Account as TempoAccount } from 'viem/tempo';
+import type { AvowApi, AvowRecords } from './avow-api.js';
+import { type Call } from './lock.js';
+import { type SendLimits } from './send.js';
+import type { SupplierConnection } from './supplier.js';
+/** An agent's access key on its business account, as Tempo signs with it. */
+export type AgentKey = TempoAccount.AccessKeyAccount;
+/** Where the transaction that funded a reserve landed. */
+export interface Landed {
+    transactionHash: Hex;
+    blockNumber: bigint;
+}
+export interface AgentConfig<A extends AvowApi = AvowApi> {
+    /** A client for the chain the business's lock is on, with the chain's fee token set. */
+    client: Client<Transport, Chain>;
+    /**
+     * The agent's access key on the business account. Its own address is the mandate's agent key.
+     * It signs transactions for the account, and Avow's messages with its bare signature.
+     */
+    key: AgentKey;
+    /** The mandate the business's administrator signed for this agent. It names the chain and lock. */
+    mandate: Signed<Mandate>;
+    /** The token the business's lock holds reserves in, on the mandate's chain. */
+    token: RailToken;
+    /** The rules the terms have to meet, the profile Avow and the supplier check them under. */
+    profile: TermsProfile;
+    /**
+     * Avow's side of the commitments. The agent has `cancel` and `start` only when it has `records`,
+     * which `httpAvowApi` serves.
+     */
+    avow: A;
+    /** How long, in seconds, an offer stays open for the supplier and Avow. Ten minutes by default. */
+    offerValidity?: bigint;
+    /**
+     * The longest, in seconds, Avow's approval may stay valid. A failed funding is settled once the
+     * approval stops working, so a long one would leave it unsettled. Five minutes by default.
+     */
+    maxApprovalValidity?: bigint;
+    /** The clock, in unix seconds. The system clock by default. */
+    now?: () => bigint;
+    /**
+     * Sends the transaction that funds a reserve and returns where it landed. By default the key
+     * signs it and Avow's relay pays its fee, through `sendSponsored`. An agent whose wallet pays
+     * its own fees, or a test, passes its own, and throws a `SendError` when it fails.
+     */
+    send?: (calls: Call[]) => Promise<Landed>;
+    limits?: SendLimits;
+    /**
+     * The chain and factory pairs whose locks a booking relied on may sit in, each with its reader,
+     * such as `tempoLockReader`. `commitToQuote` refuses version 3 terms with
+     * `dependency.lock_unknown` when this is left out.
+     */
+    dependencies?: DependencyDeps;
+}
+/** One booking the agent makes with one supplier. */
+export interface Booking {
+    supplier: SupplierConnection;
+    /**
+     * The commitment's version 2 terms, built with the template the booking falls under, such as
+     * `gpuReservationTerms` for a GPU reservation. The agent checks them against their template's
+     * rules and the profile before anyone sees them.
+     */
+    terms: Terms;
+    /** The mandate category the booking falls under, such as `compute`. */
+    category: string;
+}
+/** Terms a commitment can be made under: version 2, or version 3 through `commitToQuote`. */
+export type CommittedTerms = Terms | ChainedTerms;
+/** A commitment the agent agreed and Avow approved, before any money moved. */
+export interface ApprovedCommitment<T extends CommittedTerms = Terms> {
+    commitmentId: Hex;
+    supplier: SupplierProfile;
+    terms: T;
+    /**
+     * The commitment's salt, which keeps the terms hash from revealing standard terms. Keep it
+     * private, since showing a section of the terms or checking the commitment later needs it.
+     */
+    salt: Hex;
+    termsHash: Hex;
+    agreement: SignedAgreement;
+    approval: Signed<Approval>;
+}
+/** A commitment the agent made and funded. */
+export interface Commitment<T extends CommittedTerms = Terms> extends ApprovedCommitment<T> {
+    /**
+     * The transaction that funded the reserve. It's null when the reserve landed in a transaction
+     * the agent didn't send, or when the receipt of the agent's own couldn't be read.
+     */
+    reservedIn: Hex | null;
+}
+/**
+ * What the lock says about an approved commitment once Avow's approval can no longer land:
+ * `funded` when it holds the reserve under the approval, `failed` when it doesn't, and `unknown`
+ * when the chain didn't show it in time.
+ */
+export type Reconciled = {
+    outcome: 'funded';
+    reservedIn: Hex | null;
+} | {
+    outcome: 'failed' | 'unknown';
+};
+/** A booking's outcome. A refusal carries the reason code, and Avow's decision id once it decided. */
+export type BookResult<T extends CommittedTerms = Terms> = {
+    ok: true;
+    commitment: Commitment<T>;
+} | {
+    ok: false;
+    reason: ReasonCode;
+    decisionId?: string;
+};
+/**
+ * Who refused a quote: `avow` is Avow's API declining to approve the reserve, and `sdk` is the
+ * agent's own check, before Avow is asked or of what Avow approved. Either way no money moved.
+ */
+export type QuoteRefusalLayer = Extract<RefusalLayer, 'sdk' | 'avow'>;
+/**
+ * A quote's outcome. Once funded it lists each booking version 3 terms rely on with the block the
+ * agent read it at, just before it funded. A refusal names who refused, and a refusal by that check
+ * says which booking failed and the block it was read at.
+ */
+export type QuoteResult = {
+    ok: true;
+    commitment: Commitment<CommittedTerms>;
+    dependencies: readonly CheckedDependency[];
+} | {
+    ok: false;
+    reason: ReasonCode;
+    layer: QuoteRefusalLayer;
+    decisionId?: string;
+} | (DependencyRefusal & {
+    layer: 'sdk';
+    decisionId?: string;
+});
+/** A quote a supplier already signed, which the agent commits to as the buyer. */
+export interface SignedQuote {
+    /** The supplier as Avow registered it. Its signing key has to have signed the agreement. */
+    supplier: SupplierProfile;
+    /** Version 2 terms, or version 3 terms in full. */
+    terms: CommittedTerms;
+    salt: Hex;
+    /**
+     * The terms agreement the supplier signed. It names this agent's business as the buyer, the
+     * agent's mandate, the supplier and the terms hash of these terms under this salt.
+     */
+    agreement: TermsAgreement;
+    supplierSignature: Hex;
+    /**
+     * For version 3 terms, the section of each booking they rely on that the supplier shows, as
+     * JSON, in the terms' order.
+     */
+    disclosed?: readonly unknown[];
+}
+/**
+ * A booking whose funding failed after Avow approved it. The agent has already read the lock
+ * after the approval stopped working, so `failed` means no reserve was funded and none can be.
+ * `unknown` means the chain didn't show the outcome in time. It carries the commitment and every
+ * transaction hash sent, so the agent can `reconcile` this booking later instead of making
+ * another one.
+ */
+export declare class BookingError extends Error {
+    readonly outcome: 'failed' | 'unknown';
+    /** The commitment, whose terms are version 3 only when `commitToQuote` made it. */
+    readonly commitment: ApprovedCommitment<CommittedTerms>;
+    readonly hashes: readonly Hex[];
+    constructor(message: string, outcome: 'failed' | 'unknown', commitment: ApprovedCommitment<CommittedTerms>, hashes: readonly Hex[], options?: {
+        cause?: unknown;
+    });
+}
+/** What every agent does, whatever its `AvowApi` serves. */
+export interface AgentCalls {
+    /** The business account the agent acts for. */
+    account: Address;
+    /** The business's lock, where its reserves sit. */
+    lock: Address;
+    /** The chain and the business's lock, which every message the agent signs is signed under. */
+    domain: AvowDomain;
+    /** The mandate's hash under the business's lock. */
+    mandateHash: Hex;
+    /**
+     * Books with a supplier under the booking's terms and funds the reserve. Before any money
+     * moves it refuses, with a reason code, terms of another version than 2, terms or a booking
+     * the mandate doesn't allow, a reserve the mandate sends to the administrator, a supplier
+     * signature from another key, Avow's refusal, and an approval that differs from the terms or
+     * the mandate or that the lock would refuse as late. Once the reserve is funded it checks the
+     * lock holds it under Avow's approval. When funding fails it reads the lock after the approval
+     * stops working, and returns the commitment if the reserve landed anyway. Otherwise it throws
+     * a `BookingError`.
+     */
+    book(b: Booking): Promise<BookResult>;
+    /**
+     * Commits as the buyer to a quote the supplier already signed, and funds the reserve. Before
+     * anything is signed it refuses terms that don't hash to the agreement's terms hash, an
+     * agreement naming another buyer, mandate or supplier, or one expired or valid too long, and a
+     * supplier signature from another key. Version 2 terms then go through the mandate check, as
+     * `book` runs it. It signs as the buyer, asks Avow, and checks the approval as `book` does. For
+     * version 3 terms it then checks every booking they rely on with `verifyDependencies`, taking
+     * the owner from Avow's approval, and runs the mandate check on the checked terms. Only then does
+     * it fund, settling a failed funding as `book` does.
+     *
+     * So for version 3 terms Avow is asked before the agent's own mandate check runs. Avow's API runs
+     * the same check first, so a version 3 quote over the mandate's caps comes back as Avow's refusal,
+     * with the layer `avow`. Every other refusal is the SDK's, and no money moves before any of them.
+     */
+    commitToQuote(q: SignedQuote): Promise<QuoteResult>;
+    /**
+     * Reads the lock for a commitment `book` or `commitToQuote` approved but couldn't settle, once
+     * Avow's approval can no longer land, so the agent learns whether that same booking was funded.
+     * It takes what a `BookingError` carries.
+     */
+    reconcile(approved: ApprovedCommitment<CommittedTerms>, hashes?: readonly Hex[]): Promise<Reconciled>;
+    /** What the lock holds for one of the business's commitments, or null when it holds nothing. */
+    commitment(commitmentId: Hex): Promise<LockedBacking | null>;
+}
+/** What an agent does once its `AvowApi` serves Avow's records of cancellations and job starts. */
+export interface AgentRecordCalls {
+    /**
+     * Tells Avow the business cancels a commitment, which Avow timestamps. Before free
+     * cancellation ends the reserve can go back in full, and after it a late cancellation charge
+     * can apply.
+     */
+    cancel(commitmentId: Hex): Promise<{
+        ok: true;
+        cancelledAt: bigint;
+    } | {
+        ok: false;
+        reason: ReasonCode;
+    }>;
+    /**
+     * Starts the job with the supplier. The lock has to hold the commitment with this supplier's
+     * signing key. Avow timestamps the request, the supplier returns its signed start receipt,
+     * which the agent checks answers the request and comes from that key, and Avow records the
+     * start the kept booking rests on.
+     */
+    start(commitmentId: Hex, supplier: SupplierConnection): Promise<{
+        ok: true;
+        receipt: Signed<StartReceipt>;
+    } | {
+        ok: false;
+        reason: ReasonCode;
+    }>;
+}
+/**
+ * An agent that makes commitments under its mandate, as `createAgent` returns it for an `AvowApi`
+ * of type `A`. It has `cancel` and `start` only when `A` has `records`, Avow's records of
+ * cancellations and job starts, so code that calls one on an `AvowApi` without them doesn't
+ * compile. An agent made with `httpAvowApi` has both.
+ */
+export type Agent<A extends AvowApi = AvowApi> = AgentCalls & (A extends {
+    records: AvowRecords;
+} ? AgentRecordCalls : unknown);
+/**
+ * An agent that makes commitments under its mandate. It agrees terms with a supplier, asks Avow to
+ * approve the reserve, checks Avow's approval against the terms and the mandate before any money
+ * moves, and funds the reserve from the business's account with its own key while Avow's relay
+ * pays the fee. It cancels and starts jobs only through an `AvowApi` that has `records`.
+ */
+export declare function createAgent<A extends AvowApi>(config: AgentConfig<A>): Agent<A>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

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