Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions typescript/.changeset/add-tereno-action-provider.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@coinbase/agentkit": minor
---

Added Tereno action provider for sub-second, pre-action token launch exit simulation, holder concentration & cabal cluster analysis, contract verification, token metadata, chain gas snapshots, and prediction evidence on Base over x402.
45 changes: 45 additions & 0 deletions typescript/agentkit/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -609,6 +609,51 @@ const agent = createAgent({
</table>
</details>
<details>
<summary><strong>Tereno</strong></summary>
<table width="100%">
<tr>
<td width="200"><code>tereno_check_token_launch</code></td>
<td width="768">Simulates buy/sell exit via eth_call, inspects DEX LP reserve depth, liquidity lock/burn status, and owner powers on Base.</td>
</tr>
<tr>
<td width="200"><code>tereno_check_token_holders</code></td>
<td width="768">Analyzes top-10 holder concentration, ETH funding-origin graph, and deployer-funded Sybil clusters on Base.</td>
</tr>
<tr>
<td width="200"><code>tereno_check_contract</code></td>
<td width="768">Pre-action smart contract risk and safety verification on Base (bytecode, proxy implementation, pause status, verdict).</td>
</tr>
<tr>
<td width="200"><code>tereno_get_token_metadata</code></td>
<td width="768">Fetches block-fresh, verified ERC-20 token metadata (name, symbol, decimals, total supply) on Base.</td>
</tr>
<tr>
<td width="200"><code>tereno_get_chain_snapshot</code></td>
<td width="768">Fetches latest block, timestamp, base fee, and gas recommendations on Base.</td>
</tr>
<tr>
<td width="200"><code>tereno_get_prediction_evidence</code></td>
<td width="768">Fetches machine-readable evidence and proposition verification for prediction markets.</td>
</tr>
<tr>
<td width="200"><code>tereno_quote_contract_guard</code></td>
<td width="768">Quotes invocation cost for contract verification, including available reuse dividend credits and cash price.</td>
</tr>
<tr>
<td width="200"><code>tereno_list_capabilities</code></td>
<td width="768">Lists active Tereno capabilities, schemas, pricing, and operational validity windows.</td>
</tr>
<tr>
<td width="200"><code>tereno_list_bounties</code></td>
<td width="768">Lists available open verification bounties and dividend opportunities on Base.</td>
</tr>
<tr>
<td width="200"><code>tereno_publish_contract_fingerprint</code></td>
<td width="768">Publishes a verified contract fingerprint to the Tereno network to seed the cache and earn reuse dividends.</td>
</tr>
</table>
</details>
<details>
<summary><strong>Twitter</strong></summary>
<table width="100%">
<tr>
Expand Down
1 change: 1 addition & 0 deletions typescript/agentkit/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,7 @@
"opensea-js": "^7.1.18",
"reflect-metadata": "^0.2.2",
"sushi": "6.2.1",
"tereno-client": "^0.4.0",
"twitter-api-v2": "^1.18.2",
"viem": "2.47.4",
"zod": "^4.3.6"
Expand Down
1 change: 1 addition & 0 deletions typescript/agentkit/src/action-providers/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,3 +41,4 @@ export * from "./zerion";
export * from "./zerodev";
export * from "./zeroX";
export * from "./zora";
export * from "./tereno";
58 changes: 58 additions & 0 deletions typescript/agentkit/src/action-providers/tereno/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Tereno Action Provider

This directory contains the **TerenoActionProvider** implementation, which provides pre-action onchain verification, token launch exit simulation, holder concentration analysis, contract bytecode auditing, and prediction market evidence on Base over **x402** micropayments.

## Directory Structure

```
tereno/
├── terenoActionProvider.ts # Main provider with Tereno capabilities
├── terenoActionProvider.test.ts # Unit tests
├── schemas.ts # Zod input schemas
├── index.ts # Exports
└── README.md # This file
```

## Configuration

The `TerenoActionProvider` accepts an optional configuration object when initialized:

```typescript
import { terenoActionProvider } from "@coinbase/agentkit";

const provider = terenoActionProvider({
// Base URL of the Tereno API (defaults to "https://www.tereno.xyz")
baseUrl: "https://www.tereno.xyz",

// Maximum price in USDC per capability invocation (defaults to 0.10 USDC)
maxPriceUsd: 0.1,

// Optional custom Base RPC URL for local bytecode fingerprinting
rpcUrl: "https://mainnet.base.org",

// Optional Base Builder Code (ERC-8021 attribution)
builderCode: "bc_...",
});
```

## Actions

### Paid Verification Actions (x402 v2 on Base)

- `check_token_launch` (`token.launch.guard`): Simulates buy/sell exit via `eth_call`, checks DEX LP reserve depth, liquidity lock/burn status, and owner privileges on Base (`$0.02` cache hit / `$0.04–$0.07` fresh).
- `check_token_holders` (`token.holders.guard`): Inspects top-10 holder concentration, ETH funding-origin graph, and deployer-funded Sybil clusters on Base (`$0.01` cache hit / `$0.02–$0.04` fresh).
- `check_contract` (`contract.guard`): Audits executable runtime bytecode, EIP-1967 proxy implementation slots, pause status, and static selector flags on Base (`$0.01` cache hit / `$0.02–$0.03` fresh).
- `get_token_metadata` (`token.metadata`): Retrieves verified ERC-20 `name`, `symbol`, `decimals`, and block-fresh `totalSupply` on Base (`$0.01` cache hit / `$0.02–$0.03` fresh).
- `get_chain_snapshot` (`chain.snapshot`): Returns latest Base block number, timestamp, base fee, and suggested gas parameters (`$0.01` cache hit / `$0.02` fresh).
- `get_prediction_evidence` (`prediction.evidence`): Audits prediction market resolution rules, oracle dispute risk, and sourced evidence (`$0.01` cache hit / `$0.02–$0.05` fresh).

### Free Discovery & Cooperative Seeding Actions

- `quote_contract_guard`: Quotes the current USDC price and cache status for a contract check before spending USDC.
- `list_capabilities`: Lists active Tereno capabilities, schemas, pricing tiers, and validity windows (TTLs).
- `list_bounties`: Lists open unseeded demand bounties on Base (`misses >= 2`).
- `publish_contract_fingerprint`: Publishes a verified contract bytecode fingerprint via EIP-712 signature to claim the seeder slot and earn 20% lifetime reuse dividends in non-transferable discount credits.

## Network Support

The Tereno provider supports **Base Mainnet** (`8453` / `eip155:8453`) and **Base Sepolia** (`84532` / `eip155:84532`) with any `EvmWalletProvider`.
2 changes: 2 additions & 0 deletions typescript/agentkit/src/action-providers/tereno/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
export * from "./terenoActionProvider";
export * from "./schemas";
141 changes: 141 additions & 0 deletions typescript/agentkit/src/action-providers/tereno/schemas.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
import { z } from "zod";

const addressSchema = z
.string()
.regex(/^0x[a-fA-F0-9]{40}$/, "Invalid EVM address format")
.describe("The 0x-prefixed 40-character hexadecimal EVM address to inspect on Base");

/**
* Input schema for Tereno contract guard check.
*/
export const TerenoCheckContractSchema = z
.object({
address: addressSchema.describe(
"Target smart contract address on Base to verify before execution",
),
})
.strict();

/**
* Input schema for Tereno token launch guard check (exit simulation & LP depth).
*/
export const TerenoCheckTokenLaunchSchema = z
.object({
address: addressSchema.describe(
"Base ERC-20 token address to simulate buy/sell exit, LP reserve depth, and owner powers",
),
})
.strict();

/**
* Input schema for Tereno token holders guard check (top-10 concentration & deployer funding clusters).
*/
export const TerenoCheckTokenHoldersSchema = z
.object({
address: addressSchema.describe(
"Base ERC-20 token address to inspect for top-10 holder concentration and deployer-funded Sybil clusters",
),
})
.strict();

/**
* Input schema for Tereno token metadata query.
*/
export const TerenoGetTokenMetadataSchema = z
.object({
address: addressSchema.describe(
"Base ERC-20 token address to inspect for verified metadata and total supply",
),
})
.strict();

/**
* Input schema for Tereno chain snapshot query.
*/
export const TerenoGetChainSnapshotSchema = z.object({}).strict();

/**
* Input schema for Tereno prediction evidence query.
*/
export const TerenoGetPredictionEvidenceSchema = z
.object({
question: z
.string()
.min(5)
.max(2000)
.describe("Prediction market question or proposition to fetch machine-readable evidence for"),
market: z
.string()
.optional()
.describe(
"Optional prediction market venue identifier (e.g., 'polymarket', 'kalshi', 'omen')",
),
marketUrl: z
.string()
.url()
.optional()
.describe("Optional URL of the market proposition for resolution rule extraction"),
})
.strict();

/**
* Input schema for Tereno quote capability action.
*/
export const TerenoQuoteContractGuardSchema = z
.object({
address: addressSchema.describe("Target contract address to get a preflight cost quote for"),
})
.strict();

/**
* Input schema for Tereno list capabilities action.
*/
export const TerenoListCapabilitiesSchema = z.object({}).strict();

/**
* Input schema for Tereno list bounties action.
*/
export const TerenoListBountiesSchema = z
.object({
limit: z
.number()
.int()
.min(1)
.max(100)
.default(20)
.describe("Maximum number of open unseeded demand bounties to return (default 20)"),
})
.strict();

/**
* Input schema for Tereno publish contract fingerprint action.
*/
export const TerenoPublishContractFingerprintSchema = z
.object({
address: addressSchema.describe("Contract address whose fingerprint was computed"),
bytecodeHash: z
.string()
.regex(/^0x[a-fA-F0-9]{64}$/, "Must be a 32-byte hex hash")
.nullable()
.describe("SHA-256 or keccak hash of the bytecode, or null if unverified"),
bytecodeBytes: z
.number()
.int()
.nonnegative()
.describe("Size of the compiled bytecode in bytes"),
computedAtBlock: z
.number()
.int()
.positive()
.describe("Block number at which the bytecode fingerprint was verified"),
agentId: z
.string()
.regex(/^\d+$/)
.optional()
.describe("Optional canonical ERC-8004 agent ID of the publishing agent"),
registerIfMissing: z
.boolean()
.optional()
.describe("Whether to register an ERC-8004 identity if not yet registered"),
})
.strict();
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
import {
TerenoCheckContractSchema,
TerenoCheckTokenLaunchSchema,
TerenoCheckTokenHoldersSchema,
TerenoGetTokenMetadataSchema,
TerenoGetPredictionEvidenceSchema,
TerenoListBountiesSchema,
} from "./schemas";
import { terenoActionProvider, TerenoActionProvider } from "./terenoActionProvider";
import { Network } from "../../network";

jest.mock(
"tereno-client",
() => ({
createTerenoClient: jest.fn(() => ({
checkContract: jest.fn(),
getTokenMetadata: jest.fn(),
getPredictionEvidence: jest.fn(),
listBounties: jest.fn(),
})),
}),
{ virtual: true },
);

const MOCK_CONTRACT = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";

describe("TerenoActionProvider Schemas", () => {
describe("TerenoCheckContractSchema", () => {
it("should successfully parse a valid Base EVM address", () => {
const validInput = { address: MOCK_CONTRACT };
const result = TerenoCheckContractSchema.safeParse(validInput);
expect(result.success).toBe(true);
expect(result.data).toEqual(validInput);
});

it("should reject an invalid address format", () => {
const invalidInput = { address: "0xinvalidaddress" };
const result = TerenoCheckContractSchema.safeParse(invalidInput);
expect(result.success).toBe(false);
});
});

describe("TerenoGetTokenMetadataSchema", () => {
it("should parse valid token address", () => {
const validInput = { address: MOCK_CONTRACT };
const result = TerenoGetTokenMetadataSchema.safeParse(validInput);
expect(result.success).toBe(true);
});
});

describe("TerenoCheckTokenLaunchSchema", () => {
it("should parse valid token launch address", () => {
const validInput = { address: MOCK_CONTRACT };
const result = TerenoCheckTokenLaunchSchema.safeParse(validInput);
expect(result.success).toBe(true);
});
});

describe("TerenoCheckTokenHoldersSchema", () => {
it("should parse valid token holders address", () => {
const validInput = { address: MOCK_CONTRACT };
const result = TerenoCheckTokenHoldersSchema.safeParse(validInput);
expect(result.success).toBe(true);
});
});

describe("TerenoGetPredictionEvidenceSchema", () => {
it("should parse a valid prediction question", () => {
const validInput = {
question: "Will Ethereum Pectra upgrade activate before Q4 2026?",
market: "polymarket",
};
const result = TerenoGetPredictionEvidenceSchema.safeParse(validInput);
expect(result.success).toBe(true);
});

it("should reject too short question", () => {
const invalidInput = { question: "No?" };
const result = TerenoGetPredictionEvidenceSchema.safeParse(invalidInput);
expect(result.success).toBe(false);
});
});

describe("TerenoListBountiesSchema", () => {
it("should apply default limit of 20", () => {
const result = TerenoListBountiesSchema.safeParse({});
expect(result.success).toBe(true);
expect(result.data?.limit).toBe(20);
});
});
});

describe("TerenoActionProvider", () => {
const provider = terenoActionProvider();

it("should be an instance of TerenoActionProvider", () => {
expect(provider).toBeInstanceOf(TerenoActionProvider);
});

it("should support Base mainnet and Base Sepolia", () => {
const baseMainnet: Network = {
protocolFamily: "evm",
chainId: "8453",
networkId: "base-mainnet",
};
const baseSepolia: Network = {
protocolFamily: "evm",
chainId: "84532",
networkId: "base-sepolia",
};
const ethereumMainnet: Network = {
protocolFamily: "evm",
chainId: "1",
networkId: "ethereum",
};

expect(provider.supportsNetwork(baseMainnet)).toBe(true);
expect(provider.supportsNetwork(baseSepolia)).toBe(true);
expect(provider.supportsNetwork(ethereumMainnet)).toBe(false);
});
});
Loading
Loading