@perkos/agent-sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,204 @@
+import type { ClarityValue, ContractIdString, PostCondition, PostConditionModeName } from "@stacks/transactions";
+export type PerkOSNetwork = "mainnet" | "testnet";
+export type PaymentAsset = "sbtc" | "stx";
+export type ContractId = ContractIdString;
+export type Amount = bigint;
+export type AmountLike = bigint | number | string;
+export interface PerkOSContracts {
+    readonly agentRegistry: ContractId;
+    readonly stxCommerce: ContractId;
+    readonly sbtcCommerce: ContractId;
+    readonly reputationRegistry: ContractId;
+    readonly sbtcToken: ContractId;
+    readonly sbtcAssetName: string;
+}
+export interface PerkOSConfig {
+    readonly network: PerkOSNetwork;
+    readonly apiUrl?: string;
+    readonly contracts?: Partial<PerkOSContracts>;
+    readonly signer?: PerkOSSigner;
+    readonly spendingPolicy?: SpendingPolicyInput;
+    readonly readOnlyTransport?: ReadOnlyTransport;
+    readonly transactionTracker?: TransactionTrackerLike;
+}
+export interface ResolvedPerkOSConfig {
+    readonly network: PerkOSNetwork;
+    readonly apiUrl?: string;
+    readonly contracts: PerkOSContracts;
+}
+export interface AgentEndpoint {
+    readonly name: string;
+    readonly url: string;
+}
+export interface AgentRecord {
+    readonly id: bigint;
+    readonly name: string;
+    readonly description: string;
+    readonly creator: string;
+    readonly wallet: string;
+    readonly active: boolean;
+    readonly endpoints: readonly AgentEndpoint[];
+}
+export type JobStatus = "open" | "funded" | "submitted" | "completed" | "rejected" | "expired";
+export interface JobRecord {
+    readonly id: bigint;
+    readonly asset: PaymentAsset;
+    readonly client: string;
+    readonly provider?: string;
+    readonly evaluator: string;
+    readonly description: string;
+    readonly budget: bigint;
+    readonly expiredAt: bigint;
+    readonly status: JobStatus;
+    readonly statusCode: bigint;
+    readonly deliverable?: string;
+}
+export interface ReputationRecord {
+    readonly agent: string;
+    readonly totalScore: bigint;
+    readonly ratingCount: bigint;
+    readonly averageScoreX100: bigint;
+    readonly completedJobs: bigint;
+    readonly disputedJobs: bigint;
+}
+export type PerkOSOperation = "register-agent" | "update-agent" | "deactivate-agent" | "create-job" | "set-budget" | "fund-job" | "assign-provider" | "submit-work" | "complete-job" | "reject-job" | "expire-job" | "rate-provider";
+export interface TransactionIntent {
+    readonly operation: PerkOSOperation;
+    readonly asset?: PaymentAsset;
+    readonly amount?: bigint;
+    readonly jobId?: bigint;
+    readonly sender?: string;
+    readonly recipient?: string;
+}
+export interface ContractCallPlan {
+    readonly type: "contract-call";
+    readonly network: PerkOSNetwork;
+    readonly contract: ContractId;
+    readonly functionName: string;
+    readonly functionArgs: readonly ClarityValue[];
+    readonly postConditions: readonly PostCondition[];
+    readonly postConditionMode: PostConditionModeName;
+    readonly intent: TransactionIntent;
+}
+export interface SignerResult {
+    readonly txid: string;
+    readonly raw?: unknown;
+}
+export interface PerkOSSigner {
+    getAddress(): Promise<string>;
+    signAndBroadcast(plan: ContractCallPlan): Promise<SignerResult>;
+}
+export interface TransactionReceipt {
+    readonly txid: string;
+    readonly status: "broadcast";
+    readonly network: PerkOSNetwork;
+    readonly contract: ContractId;
+    readonly operation: PerkOSOperation;
+    readonly asset?: PaymentAsset;
+    readonly amount?: bigint;
+    readonly jobId?: bigint;
+    readonly explorerUrl: string;
+    readonly raw?: unknown;
+}
+export type TransactionConfirmationStatus = "pending" | "success" | "abort" | "dropped" | "timeout";
+export interface TransactionResultValue {
+    readonly hex?: string;
+    readonly repr?: string;
+}
+export interface TransactionConfirmation {
+    readonly txid: string;
+    readonly network: PerkOSNetwork;
+    readonly status: TransactionConfirmationStatus;
+    readonly observedAt: string;
+    readonly blockHeight?: number;
+    readonly blockHash?: string;
+    readonly result?: TransactionResultValue;
+    readonly raw?: unknown;
+}
+export interface ConfirmationOptions {
+    readonly pollIntervalMs?: number;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly onStatus?: (confirmation: TransactionConfirmation) => void | Promise<void>;
+}
+export interface TransactionTrackerLike {
+    getStatus(txid: string): Promise<TransactionConfirmation>;
+    waitForConfirmation(txid: string, options?: ConfirmationOptions): Promise<TransactionConfirmation>;
+}
+export interface ConfirmedTransactionReceipt {
+    readonly broadcast: TransactionReceipt;
+    readonly confirmation: TransactionConfirmation;
+}
+export interface ReadOnlyCall {
+    readonly network: PerkOSNetwork;
+    readonly apiUrl?: string;
+    readonly contract: ContractId;
+    readonly functionName: string;
+    readonly functionArgs: readonly ClarityValue[];
+    readonly senderAddress: string;
+}
+export type ReadOnlyTransport = (call: ReadOnlyCall) => Promise<ClarityValue>;
+export interface SpendingPolicyInput {
+    readonly allowedNetworks?: readonly PerkOSNetwork[];
+    readonly allowedContracts?: readonly ContractId[];
+    readonly allowedAssets?: readonly PaymentAsset[];
+    readonly maxPerTransaction?: Partial<Record<PaymentAsset, AmountLike>>;
+    readonly maxPerSession?: Partial<Record<PaymentAsset, AmountLike>>;
+}
+export interface SpendingApproval {
+    readonly operation: PerkOSOperation;
+    readonly asset?: PaymentAsset;
+    readonly amount?: bigint;
+    readonly spentThisSession?: bigint;
+    readonly remainingThisSession?: bigint;
+}
+export interface RegisterAgentInput {
+    readonly name: string;
+    readonly description: string;
+    readonly wallet: string;
+    readonly endpoints?: readonly AgentEndpoint[];
+}
+export interface UpdateAgentInput {
+    readonly agentId: AmountLike;
+    readonly name?: string;
+    readonly description?: string;
+    readonly wallet?: string;
+}
+export interface CreateJobInput {
+    readonly asset: PaymentAsset;
+    readonly provider?: string;
+    readonly evaluator: string;
+    readonly expiredAt: AmountLike;
+    readonly description: string;
+}
+export interface JobAmountInput {
+    readonly asset: PaymentAsset;
+    readonly jobId: AmountLike;
+    readonly amount: AmountLike;
+}
+export interface FundJobInput extends JobAmountInput {
+    readonly sender?: string;
+}
+export interface AssignProviderInput {
+    readonly asset: PaymentAsset;
+    readonly jobId: AmountLike;
+    readonly provider: string;
+}
+export interface SubmitWorkInput {
+    readonly asset: PaymentAsset;
+    readonly jobId: AmountLike;
+    readonly deliverable: string | Uint8Array;
+}
+export interface SettleJobInput {
+    readonly asset: PaymentAsset;
+    readonly jobId: AmountLike;
+    readonly amount: AmountLike;
+    readonly recipient: string;
+}
+export interface RateProviderInput {
+    readonly asset: PaymentAsset;
+    readonly jobId: AmountLike;
+    readonly score: AmountLike;
+    readonly comment: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/validation.d.ts

@@ -0,0 +1,17 @@
+import type { AmountLike, ContractId, PerkOSContracts, PerkOSNetwork, ResolvedPerkOSConfig } from "./types.js";
+export declare function toUint(value: AmountLike, field: string, allowZero?: boolean): bigint;
+export declare function assertAscii(value: string, field: string, maxBytes: number, allowEmpty?: boolean): void;
+export declare function assertPrincipal(principal: string, field: string, network?: PerkOSNetwork): void;
+export declare function parseContractId(contract: string, field: string, network?: PerkOSNetwork): {
+    address: string;
+    name: string;
+};
+export declare function principalMatchesNetwork(principal: string, network: PerkOSNetwork): boolean;
+export declare function normalizeApiUrl(value: string, field?: string): string;
+export declare function resolveConfig(input: {
+    network: PerkOSNetwork;
+    apiUrl?: string;
+    contracts?: Partial<PerkOSContracts>;
+}): ResolvedPerkOSConfig;
+export declare function asContractId(value: string): ContractId;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,eAAe,EACf,aAAa,EACb,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAKpB,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,MAAM,CAyBlF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,UAAQ,GAAG,IAAI,CAepG;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,IAAI,CAcN;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAuBnC;AAED,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAI1F;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAW,GAAG,MAAM,CAcvE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;CACtC,GAAG,oBAAoB,CA4BvB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAEtD"}

package/dist/validation.js

@@ -0,0 +1,124 @@
+import { validateStacksAddress } from "@stacks/transactions";
+import { PerkOSError } from "./errors.js";
+import { DEFAULT_DEPLOYMENTS } from "./constants.js";
+const CONTRACT_NAME = /^[a-z][a-z0-9-]{0,39}$/;
+export function toUint(value, field, allowZero = false) {
+    let parsed;
+    try {
+        if (typeof value === "number" && (!Number.isSafeInteger(value) || value < 0)) {
+            throw new Error("number must be a non-negative safe integer");
+        }
+        if (typeof value === "string" && !/^\d+$/.test(value)) {
+            throw new Error("string must contain only decimal digits");
+        }
+        parsed = BigInt(value);
+    }
+    catch (cause) {
+        throw new PerkOSError("INPUT_INVALID", `${field} must be an unsigned integer.`, {
+            field,
+            value,
+            cause,
+        });
+    }
+    if (parsed < 0n || (!allowZero && parsed === 0n)) {
+        throw new PerkOSError("INPUT_INVALID", `${field} must be ${allowZero ? "zero or greater" : "greater than zero"}.`, { field, value });
+    }
+    return parsed;
+}
+export function assertAscii(value, field, maxBytes, allowEmpty = false) {
+    if ((!allowEmpty && value.length === 0) || value.length > maxBytes) {
+        throw new PerkOSError("INPUT_INVALID", `${field} must be ${allowEmpty ? "at most" : "between 1 and"} ${maxBytes} ASCII bytes.`, { field, maxBytes });
+    }
+    for (const character of value) {
+        if (character.codePointAt(0) > 0x7f) {
+            throw new PerkOSError("INPUT_INVALID", `${field} must contain ASCII characters only.`, {
+                field,
+            });
+        }
+    }
+}
+export function assertPrincipal(principal, field, network) {
+    if (!validateStacksAddress(principal)) {
+        throw new PerkOSError("INPUT_INVALID", `${field} is not a valid Stacks principal.`, {
+            field,
+            principal,
+        });
+    }
+    if (network && !principalMatchesNetwork(principal, network)) {
+        throw new PerkOSError("INPUT_INVALID", `${field} does not belong to Stacks ${network}.`, { field, principal, network });
+    }
+}
+export function parseContractId(contract, field, network) {
+    const pieces = contract.split(".");
+    if (pieces.length !== 2) {
+        throw new PerkOSError("CONFIG_INVALID", `${field} must use <address>.<contract-name>.`, {
+            field,
+            contract,
+        });
+    }
+    const [address, name] = pieces;
+    if (!address || !name || !validateStacksAddress(address) || !CONTRACT_NAME.test(name)) {
+        throw new PerkOSError("CONFIG_INVALID", `${field} is not a valid contract identifier.`, {
+            field,
+            contract,
+        });
+    }
+    if (network && !principalMatchesNetwork(address, network)) {
+        throw new PerkOSError("CONFIG_INVALID", `${field} does not belong to Stacks ${network}.`, {
+            field,
+            contract,
+            network,
+        });
+    }
+    return { address, name };
+}
+export function principalMatchesNetwork(principal, network) {
+    return network === "mainnet"
+        ? principal.startsWith("SP") || principal.startsWith("SM")
+        : principal.startsWith("ST") || principal.startsWith("SN");
+}
+export function normalizeApiUrl(value, field = "apiUrl") {
+    const normalized = value.trim();
+    let parsed;
+    try {
+        parsed = new URL(normalized);
+    }
+    catch (cause) {
+        throw new PerkOSError("CONFIG_INVALID", `${field} must be a valid URL.`, {
+            cause,
+        });
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new PerkOSError("CONFIG_INVALID", `${field} must use HTTP or HTTPS.`);
+    }
+    return normalized.replace(/\/+$/, "");
+}
+export function resolveConfig(input) {
+    if (input.network !== "mainnet" && input.network !== "testnet") {
+        throw new PerkOSError("CONFIG_INVALID", 'network must be "mainnet" or "testnet".');
+    }
+    const apiUrl = input.apiUrl ? normalizeApiUrl(input.apiUrl) : undefined;
+    const contracts = {
+        ...DEFAULT_DEPLOYMENTS[input.network],
+        ...input.contracts,
+    };
+    for (const field of [
+        "agentRegistry",
+        "stxCommerce",
+        "sbtcCommerce",
+        "reputationRegistry",
+        "sbtcToken",
+    ]) {
+        parseContractId(contracts[field], `contracts.${field}`, input.network);
+    }
+    assertAscii(contracts.sbtcAssetName, "contracts.sbtcAssetName", 128);
+    return {
+        network: input.network,
+        ...(apiUrl ? { apiUrl } : {}),
+        contracts,
+    };
+}
+export function asContractId(value) {
+    return value;
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

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

package/docs/ARCHITECTURE.md

@@ -0,0 +1,111 @@
+# Architecture
+
+## Scope
+
+The SDK is a typed boundary between agent frameworks and the existing PerkOS contracts. The core
+package contains no LLM, HTTP-paywall, MCP server, wallet extension, or private-key store. Those
+systems integrate through explicit interfaces so that transaction policy remains reusable and
+auditable.
+
+## Flow
+
+```text
+Agent or application
+        |
+        v
+PerkOSClient ---- read-only transport ---- Stacks API
+        |
+        +---- PerkOSTransactionBuilder
+        |          |
+        |          v
+        |    ContractCallPlan
+        |          |
+        +---- SpendingPolicy
+        |          |
+        |          v
+        |    StacksConnectSigner ---- browser wallet
+        |          or
+        |      HeadlessSigner ------ external key provider
+        |          |
+        |          v
+        |    Stacks transaction broadcast
+        |
+        +---- TransactionTracker ---- Stacks API v3
+                   |
+                   v
+           normalized confirmation
+```
+
+## Read path
+
+`PerkOSClient` resolves a known deployment or validated override and invokes a replaceable
+read-only transport. Responses are decoded from Clarity values into records that use `bigint` for
+all on-chain integers. Known missing-record errors return `null`; malformed responses and other
+contract errors remain explicit.
+
+## Write path
+
+Builders produce a `ContractCallPlan` containing:
+
+- the selected network and exact contract ID;
+- function name and serialized Clarity arguments;
+- post-condition mode and post-conditions;
+- semantic intent such as operation, asset, job ID, sender, recipient, and amount.
+
+Plans are inert. `execute` checks the plan against `SpendingPolicy` before invoking the signer.
+The SDK only records session spend after the signer returns a valid Stacks transaction ID.
+The high-level `fundJob` helper also validates its amount and funding limits before requesting a
+signer address, so a denied spend does not cause headless key-provider access.
+
+## Signer adapters
+
+`StacksConnectSigner` is an injected adapter around the Stacks Connect `stx_callContract` request.
+The host application owns wallet discovery, account selection, and the user approval surface. The
+adapter forwards the contract, function, arguments, network, and post-conditions without receiving
+a private key.
+
+`HeadlessSigner` uses `makeContractCall` and `broadcastTransaction`. It obtains key material from an
+application callback at the last responsible moment, caches only the public address, and clears its
+local `Uint8Array` copy after use. The callback is the integration point for a secret manager, HSM,
+KMS, or isolated signing service. It is intentionally not an environment-variable loader or key
+store.
+
+Both adapters reject plans from a network other than the network fixed at construction.
+
+## Confirmation path
+
+`TransactionTracker` queries the Hiro Stacks API v3 transaction endpoint and maps API states into
+`pending`, `success`, `abort`, `dropped`, or `timeout`. A not-yet-indexed transaction is pending,
+not failed. Waiting is bounded, cancellable, and emits status observations through an optional
+callback. Because the v3 endpoint may return `result: null` for successful contract calls, terminal
+receipts make a best-effort transaction-detail lookup to hydrate the Clarity result without
+replacing v3 as the status and block-metadata source.
+
+`PerkOSClient.executeAndConfirm` keeps broadcast information and confirmation evidence separate in
+one receipt. API-reported success is evidence of transaction execution, but applications may still
+require additional confirmations before treating high-value settlement as irreversible.
+
+## Asset adapters
+
+STX and sBTC share the same public job lifecycle but have different contract signatures and
+post-conditions:
+
+- STX funding calls `fund-job(job-id)` and constrains micro-STX.
+- sBTC funding calls `fund-job(job-id, token)` and constrains the canonical SIP-010 asset.
+- sBTC settlement functions also receive the configured token trait argument.
+
+This difference stays inside the builder so frameworks do not duplicate asset-specific Clarity
+logic.
+
+## Settlement safety
+
+Completion, rejection, and expiry may transfer funds held by the escrow contract rather than by
+the transaction origin. High-level client methods read the current job and escrow balance before
+building the plan. The resulting post-condition identifies the escrow contract principal and the
+exact amount expected to leave it.
+
+## Future adapters
+
+- x402 v2 resource-server and client adapters.
+- MCP tools with typed inputs, allowlists, and the same spending policy.
+- Optional framework-specific integrations and higher-confirmation settlement policies.

package/examples/quickstart.ts

@@ -0,0 +1,19 @@
+import { PerkOSClient } from "@perkos/agent-sdk";
+
+const network = process.env.PERKOS_NETWORK === "testnet" ? "testnet" : "mainnet";
+const client = new PerkOSClient({ network });
+
+const [agents, stxJobs, sbtcJobs, configuredSbtc] = await Promise.all([
+  client.getAgentCount(),
+  client.getJobCount("stx"),
+  client.getJobCount("sbtc"),
+  client.getConfiguredSbtcToken(),
+]);
+
+console.log({
+  network,
+  agents: agents.toString(),
+  stxJobs: stxJobs.toString(),
+  sbtcJobs: sbtcJobs.toString(),
+  configuredSbtc,
+});

package/examples/testnet-api.ts

@@ -0,0 +1,23 @@
+export type ExampleFetch = (
+  input: string | URL | Request,
+  init?: RequestInit
+) => Promise<Response>;
+
+export async function fetchChainTip(
+  apiUrl: string,
+  fetchImpl: ExampleFetch = globalThis.fetch.bind(globalThis)
+): Promise<bigint> {
+  const response = await fetchImpl(`${apiUrl.replace(/\/+$/, "")}/v2/info`, {
+    headers: { accept: "application/json" },
+  });
+  if (!response.ok) throw new Error(`Stacks API returned HTTP ${response.status}.`);
+  const body: unknown = await response.json();
+  if (!body || typeof body !== "object") {
+    throw new Error("Invalid Stacks API info response.");
+  }
+  const height = (body as Record<string, unknown>).stacks_tip_height;
+  if (typeof height !== "number" || !Number.isSafeInteger(height) || height < 0) {
+    throw new Error("Stacks API did not return a valid stacks_tip_height.");
+  }
+  return BigInt(height);
+}