run402-mcp
Version:
MCP server for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.
209 lines • 8.48 kB
TypeScript
/**
* `contracts` namespace — AWS KMS-backed Ethereum signers.
*
* Signers sign smart-contract write transactions. Private keys never leave
* KMS. Pricing: $0.04/day rental ($1.20/month) plus $0.000005 per sign.
* Non-custodial.
*
* NOTE: The contracts API surface is frozen — this namespace preserves the
* existing request/response shapes verbatim.
*/
import type { Client } from "../kernel.js";
export type EvmChain = "base-mainnet" | "base-sepolia";
export type SignerStatus = "active" | "suspended" | "deleted";
export type ContractCallStatus = "submitted" | "confirmed" | "failed";
export interface SignerSummary {
signer_id: string;
address: string;
chain: EvmChain;
status: SignerStatus;
balance_wei: string;
threshold_wei: string | null;
recovery_address: string | null;
created_at: string;
}
export interface ListSignersResult {
signers: SignerSummary[];
}
export interface ProvisionSignerResult {
signer_id: string;
address: string;
chain: EvmChain;
status?: SignerStatus;
balance_wei?: string;
threshold_wei?: string | null;
recovery_address?: string | null;
created_at?: string;
}
export interface ContractCallResult {
call_id: string;
status: ContractCallStatus;
tx_hash: string | null;
gas_used?: string | null;
gas_cost_usd_micros?: string | null;
receipt?: unknown;
}
export interface ContractReadResult {
result: unknown;
}
/** app-wallet: a gasless token transfer from a signer, settled through the platform's facilitator. */
export type SignerTransferStatus = "pending" | "settled" | "failed" | "unknown";
export type SignerTransferPhase = "precheck" | "sign" | "verify" | "settle";
export interface SignerTransfer {
transfer_id: string;
signer_id: string;
status: SignerTransferStatus;
tx_hash: string | null;
chain: EvmChain;
network: string;
asset: string;
asset_address: string;
to: string;
amount: string;
nonce: string | null;
failed_phase: SignerTransferPhase | null;
facilitator_reason: string | null;
created_at: string;
updated_at: string;
}
export interface ListSignerTransfersResult {
transfers: SignerTransfer[];
}
export interface SignerTransferOptions {
signerId: string;
chain: EvmChain;
/** The token to send; `usdc` (the default) today. */
asset?: string;
to: string;
/** The amount in the asset's base units (USDC: 6 decimals), as a decimal string. */
amount: string;
idempotencyKey?: string;
}
export interface DrainResult {
call_id: string;
status: ContractCallStatus;
tx_hash: string | null;
}
export interface DeleteSignerResult {
signer_id: string;
deleted_at?: string;
scheduled_deletion_at?: string;
}
export interface ProvisionSignerOptions {
chain: EvmChain;
recoveryAddress?: string;
}
export interface ContractCallOptions {
signerId: string;
chain: EvmChain;
contractAddress?: string;
to?: string;
abiFragment?: unknown[];
abi?: unknown[];
functionName?: string;
fn?: string;
args: unknown[];
value?: string;
idempotencyKey?: string;
}
export interface ContractDeployOptions {
/** The cwlt_… ID of the KMS signer that will sign + own the new contract. */
signerId: string;
/** The chain to deploy to. Must match the signer's chain. */
chain: EvmChain;
/**
* Full creation calldata as a 0x-prefixed hex string: creation bytecode
* concatenated with ABI-encoded constructor args (the caller does the
* encoding via viem/ethers etc.). Non-empty, even-length, ≤ 128 KB.
*
* run402 does NOT compile Solidity — bring your own bytecode.
*/
bytecode: string;
/** Optional native-token value to attach to the deploy tx (in wei). */
value?: string;
/** Optional idempotency key — same key + same payload returns the existing call. */
idempotencyKey?: string;
}
export interface ContractDeployResult extends ContractCallResult {
/**
* The deterministic CREATE address derived from `(signer.address, nonce)`.
* Returned synchronously — the caller knows where the new contract will
* live without waiting for confirmation. The reconciler verifies this
* matches the on-chain receipt's `contractAddress` on confirmation.
*/
contract_address: string;
}
export interface ContractReadOptions {
chain: EvmChain;
contractAddress?: string;
to?: string;
abiFragment?: unknown[];
abi?: unknown[];
functionName?: string;
fn?: string;
args: unknown[];
}
export declare class Contracts {
private readonly client;
readonly setAlert: (projectId: string, signerId: string, thresholdWei: string) => Promise<void>;
readonly delete: (projectId: string, signerId: string) => Promise<DeleteSignerResult>;
readonly status: (projectId: string, callId: string) => Promise<ContractCallResult>;
constructor(client: Client);
/** Provision a new KMS-backed signer. */
provisionSigner(projectId: string, opts: ProvisionSignerOptions): Promise<ProvisionSignerResult>;
/** Get a signer's metadata + live balance. */
getSigner(projectId: string, signerId: string): Promise<SignerSummary>;
/** List all signers owned by the project, including deleted ones. */
listSigners(projectId: string): Promise<ListSignersResult>;
/** Set or clear the recovery address used for auto-drain on day-90 deletion. */
setRecovery(projectId: string, signerId: string, recoveryAddress: string | null): Promise<void>;
/** Set the low-balance threshold (in wei) for email alerts. */
setLowBalanceAlert(projectId: string, signerId: string, thresholdWei: string): Promise<void>;
/** Submit a smart-contract write call. Idempotent on `idempotencyKey`. */
call(projectId: string, opts: ContractCallOptions): Promise<ContractCallResult>;
/**
* Deploy a contract from the signer (KMS-signs a contract-creation tx).
*
* The `bytecode` is the full creation calldata — creation bytecode
* concatenated with ABI-encoded constructor args (the caller does the
* encoding via viem/ethers etc.; run402 does NOT compile Solidity).
*
* Returns synchronously with the deterministic CREATE address derived
* from `(signer.address, nonce)` — no need to wait for confirmation
* to know where the contract will live. Reconciler verifies on receipt.
*
* Same pricing as `call`: chain gas at-cost + $0.000005 KMS sign fee.
* Idempotent on `idempotencyKey`.
*/
deploy(projectId: string, opts: ContractDeployOptions): Promise<ContractDeployResult>;
/** Read-only smart-contract call (view/pure). No auth, no gas, no billing. */
read(opts: ContractReadOptions): Promise<ContractReadResult>;
/** Look up a previously submitted call by id. */
/**
* Transfers a token from a signer with no gas on the signer: the gateway
* signs the token's EIP-3009 authorization with the signer's key and the
* platform's facilitator settles it and pays the gas. One signing fee, no
* gas. Idempotent on `idempotencyKey` like `call`: a transfer that failed
* before settlement re-executes under its key; one that died in settlement
* never does. `status: "unknown"` means the settle outcome never came back;
* poll `transferStatus` until the reconciler finishes it.
*/
transfer(projectId: string, opts: SignerTransferOptions): Promise<SignerTransfer>;
/** One transfer by id. */
transferStatus(projectId: string, signerId: string, transferId: string): Promise<SignerTransfer>;
/** The signer's transfers, newest first. */
listTransfers(projectId: string, signerId: string): Promise<ListSignerTransfersResult>;
callStatus(projectId: string, callId: string): Promise<ContractCallResult>;
/**
* Drain the signer's native-token balance to a destination address.
* Works on suspended signers. Requires `X-Confirm-Drain: <signer_id>`
* confirmation header (sent automatically by the SDK).
*/
drain(projectId: string, signerId: string, destinationAddress: string): Promise<DrainResult>;
/**
* Schedule the KMS key for deletion (7-day AWS minimum window). Refused
* if the signer has on-chain balance >= dust — drain first.
*/
deleteSigner(projectId: string, signerId: string): Promise<DeleteSignerResult>;
}
//# sourceMappingURL=contracts.d.ts.map