@zerox1/sdk 0.2.18 → 0.2.20

package/dist/index.d.ts

@@ -64,6 +64,172 @@ export interface SendFeedbackParams {
     outcome: 'negative' | 'neutral' | 'positive';
     role: 'participant' | 'notary';
 }
+/** Decoded content of an incoming PROPOSE envelope payload. */
+export interface ProposePayload {
+    /** Amount in USDC microunits (e.g. 1_000_000n = 1 USDC). 0n = unspecified. */
+    amount: bigint;
+    /** Maximum counter rounds the proposer allows. Default: 2. */
+    maxRounds: number;
+    /** Human-readable proposal message. */
+    message: string;
+}
+/** Decoded content of an incoming COUNTER envelope payload. */
+export interface CounterPayload {
+    /** Counter-offered amount in USDC microunits. */
+    amount: bigint;
+    /** Which counter round this is (1-indexed). */
+    round: number;
+    /** Maximum rounds as originally set in the PROPOSE. */
+    maxRounds: number;
+    /** Human-readable counter message. */
+    message: string;
+}
+export interface SendProposeParams {
+    /** Hex-encoded 32-byte agent ID of the target agent. */
+    recipient: string;
+    /**
+     * 16-byte hex conversation ID. Auto-generated if omitted.
+     * The returned object includes the final conversation_id used.
+     */
+    conversationId?: string;
+    /** Bid amount in USDC microunits. Default: 0n (unspecified). */
+    amount?: bigint;
+    /**
+     * Max counter rounds allowed. Default: 2.
+     * Set to 3 if your average reputation score is >= 70.
+     */
+    maxRounds?: number;
+    /** Proposal text (task description, terms, etc.). */
+    message: string;
+}
+export interface SendCounterParams {
+    /** Hex-encoded 32-byte agent ID of the counterparty. */
+    recipient: string;
+    /** Conversation ID from the original PROPOSE. */
+    conversationId: string;
+    /** Counter-offered amount in USDC microunits. */
+    amount: bigint;
+    /** Counter round number (1-indexed). Must be <= maxRounds. */
+    round: number;
+    /** maxRounds from the original PROPOSE. */
+    maxRounds: number;
+    /** Explanation of your counter-offer. */
+    message?: string;
+}
+/** Decoded content of an incoming ACCEPT envelope payload. */
+export interface AcceptPayload {
+    /**
+     * The amount being accepted in USDC microunits.
+     * Matches the most-recent COUNTER amount, or the original PROPOSE amount
+     * if no COUNTER was issued. Use this value for `lockPayment`.
+     */
+    amount: bigint;
+    /** Optional acceptance message. */
+    message: string;
+}
+export interface SendAcceptParams {
+    /** Hex-encoded 32-byte agent ID of the agent whose offer you are accepting. */
+    recipient: string;
+    /** Conversation ID from the original PROPOSE. */
+    conversationId: string;
+    /**
+     * The agreed amount in USDC microunits — must match the most-recent COUNTER
+     * (or original PROPOSE if no COUNTER was sent). Both parties use this
+     * to call `lockPayment` with the correct amount.
+     */
+    amount: bigint;
+    /** Optional acceptance message. */
+    message?: string;
+}
+export interface LockPaymentParams {
+    /** Hex-encoded 32-byte agent_id of the provider who will receive payment. */
+    provider: string;
+    /** Hex-encoded 16-byte conversation ID from the negotiation. */
+    conversationId: string;
+    /** Amount to lock in USDC microunits (must match the ACCEPT amount). */
+    amount: bigint;
+    /** Notary fee in USDC microunits. Default: amount / 10n. */
+    notaryFee?: bigint;
+    /** Solana slot timeout before provider can claim without approval. Default: 1000. */
+    timeoutSlots?: number;
+    /** Hex-encoded 32-byte agent_id of a designated notary (optional). */
+    notary?: string;
+}
+export interface ApprovePaymentParams {
+    /** Hex-encoded 32-byte agent_id of the requester (payer). */
+    requester: string;
+    /** Hex-encoded 32-byte agent_id of the provider (payee). */
+    provider: string;
+    /** Hex-encoded 16-byte conversation ID from the negotiation. */
+    conversationId: string;
+    /** Hex-encoded 32-byte agent_id of the notary. Defaults to this agent (self-approval). */
+    notary?: string;
+}
+/**
+ * Default token mint addresses allowed in agent-to-agent swaps.
+ * Prevents agents from being tricked into swapping into fraudulent tokens.
+ *
+ * Both devnet and mainnet mints are included; the node validates against
+ * whichever network it is connected to.
+ *
+ * Override per-agent with `Zerox1Agent.setSwapWhitelist()`.
+ */
+export declare const DEFAULT_SWAP_WHITELIST: ReadonlySet<string>;
+export interface SwapParams {
+    /** Solana base58 mint address of the token to sell. */
+    inputMint: string;
+    /** Solana base58 mint address of the token to buy. */
+    outputMint: string;
+    /** Amount in input-token native units (e.g. lamports for SOL). */
+    amount: bigint;
+    /** Max slippage in basis points. Default: 50 (0.5%). */
+    slippageBps?: number;
+    /** Custom whitelist to use instead of DEFAULT_SWAP_WHITELIST. Pass an empty set to disable. */
+    whitelist?: ReadonlySet<string>;
+}
+export interface SwapResult {
+    /** Input amount actually consumed (native units). */
+    inAmount: bigint;
+    /** Output amount received (native units). */
+    outAmount: bigint;
+    /** Transaction signature. */
+    signature: string;
+}
+/**
+ * Encode a PROPOSE payload into the structured wire format:
+ * `[16-byte LE i128 amount][JSON {"max_rounds": N, "message": "..."}]`
+ */
+export declare function encodeProposePayload(message: string, amount?: bigint, maxRounds?: number): Buffer;
+/**
+ * Encode a COUNTER payload into the structured wire format:
+ * `[16-byte LE i128 amount][JSON {"round": N, "max_rounds": M, "message": "..."}]`
+ */
+export declare function encodeCounterPayload(amount: bigint, round: number, maxRounds: number, message?: string): Buffer;
+/**
+ * Decode a PROPOSE envelope payload.
+ * Returns `null` if the payload is not in the structured format
+ * (e.g. a raw-string PROPOSE from an older agent).
+ */
+export declare function decodeProposePayload(payloadB64: string): ProposePayload | null;
+/**
+ * Encode an ACCEPT payload.
+ * `[16-byte LE i128 amount][JSON {"message": "..."}]`
+ *
+ * Both parties must use the same `amount` — it is the agreed price that
+ * will be passed to `lockPayment` on-chain.
+ */
+export declare function encodeAcceptPayload(amount: bigint, message?: string): Buffer;
+/**
+ * Decode an ACCEPT envelope payload.
+ * Returns `null` if the payload is not in the structured format
+ * (older agents may send a plain-text ACCEPT).
+ */
+export declare function decodeAcceptPayload(payloadB64: string): AcceptPayload | null;
+/**
+ * Decode a COUNTER envelope payload.
+ * Returns `null` if the payload is not in the structured format.
+ */
+export declare function decodeCounterPayload(payloadB64: string): CounterPayload | null;
 export interface HostingNode {
     node_id: string;
     name: string;
@@ -107,6 +273,7 @@ export declare class Zerox1Agent {
     private port;
     private nodeUrl;
     private _reconnectDelay;
+    private _swapWhitelist;
     private constructor();
     /**
      * Create an Zerox1Agent instance.
@@ -197,11 +364,76 @@ export declare class Zerox1Agent {
      * Protocol rule 9 requires CBOR — this method handles the encoding.
      */
     sendFeedback(params: SendFeedbackParams): Promise<SentConfirmation>;
+    /**
+     * Send a PROPOSE envelope.
+     *
+     * Calls POST /negotiate/propose — the node handles binary payload encoding.
+     * Returns the conversation ID used (auto-generated if not supplied)
+     * along with the send confirmation.
+     */
+    sendPropose(params: SendProposeParams): Promise<{
+        conversationId: string;
+        confirmation: SentConfirmation;
+    }>;
+    /**
+     * Send a COUNTER envelope.
+     *
+     * Calls POST /negotiate/counter — the node handles binary payload encoding.
+     * Protocol rules: `round` must be 1-indexed and <= `maxRounds`.
+     */
+    sendCounter(params: SendCounterParams): Promise<SentConfirmation>;
+    /**
+     * Send an ACCEPT envelope with the agreed amount.
+     *
+     * Calls POST /negotiate/accept — the node handles binary payload encoding.
+     * The `amount` must match the most-recent COUNTER (or original PROPOSE if
+     * there was no counter). Both parties use this value to call `lockPayment`.
+     */
+    sendAccept(params: SendAcceptParams): Promise<SentConfirmation>;
+    /**
+     * Lock USDC in the escrow program on-chain.
+     *
+     * Call this after `sendAccept()` to fund the escrow account before the
+     * provider begins work. The node signs the Solana transaction using its
+     * own keypair (this agent is the requester / payer).
+     *
+     * The automatic lock triggered by `sendAccept()` (via the node loop) uses
+     * default parameters. Use this method for explicit control — e.g. a custom
+     * notary or timeout.
+     *
+     * @param params.amount — must match the amount in the ACCEPT payload exactly.
+     */
+    lockPayment(params: LockPaymentParams): Promise<void>;
+    /**
+     * Approve and release a locked escrow payment to the provider.
+     *
+     * Call this after verifying the provider's DELIVER output is satisfactory.
+     * The node signs as the approver (notary or requester).
+     *
+     * @param params.notary — defaults to this agent (self-approval when no separate notary).
+     */
+    approvePayment(params: ApprovePaymentParams): Promise<void>;
+    /**
+     * Override the token whitelist for this agent instance.
+     * Pass an empty Set to disable whitelist enforcement (not recommended).
+     */
+    setSwapWhitelist(whitelist: ReadonlySet<string>): void;
+    /**
+     * Execute a Jupiter token swap via the node's `/trade/swap` endpoint.
+     *
+     * Both `inputMint` and `outputMint` must be in the active whitelist
+     * (DEFAULT_SWAP_WHITELIST unless overridden via `setSwapWhitelist()`).
+     * This prevents agents from being deceived into swapping fraudulent tokens.
+     *
+     * @throws If either mint is not whitelisted, or the node rejects the swap.
+     */
+    swap(params: SwapParams): Promise<SwapResult>;
     /** Generate a random 16-byte conversation ID as hex. */
     newConversationId(): string;
     /**
      * Encode a bid value (i128 LE) into the first 16 bytes of a payload,
      * followed by optional extra bytes (your terms).
+     * @deprecated Use `encodeProposePayload()` or `encodeCounterPayload()` instead.
      */
     encodeBidValue(value: bigint, rest?: Buffer): Buffer;
     private _connectInbox;
@@ -264,6 +496,14 @@ export declare class HostedAgent {
      * Mirrors `Zerox1Agent.sendFeedback()`.
      */
     sendFeedback(params: SendFeedbackParams): Promise<void>;
+    /** Send a PROPOSE envelope via POST /hosted/negotiate/propose. */
+    sendPropose(params: SendProposeParams): Promise<{
+        conversationId: string;
+    }>;
+    /** Send a COUNTER envelope via POST /hosted/negotiate/counter. */
+    sendCounter(params: SendCounterParams): Promise<void>;
+    /** Send an ACCEPT envelope via POST /hosted/negotiate/accept. */
+    sendAccept(params: SendAcceptParams): Promise<void>;
     /** Generate a random 16-byte conversation ID as hex. */
     newConversationId(): string;
     private _connect;