aavegotchi-cli 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.2.0 - 2026-02-27
+
+### Added
+
+- Generic subgraph command family:
+  - `ag subgraph list`
+  - `ag subgraph check --source core-base|gbm-base [--raw]`
+  - `ag subgraph query --source <alias> ...`
+- Baazaar subgraph wrappers:
+  - `ag baazaar listing get --kind erc721|erc1155 --id <listingId> [--verify-onchain]`
+  - `ag baazaar listing active --kind erc721|erc1155 [--first] [--skip]`
+  - `ag baazaar listing mine --kind erc721|erc1155 --seller <0x...> [--first] [--skip]`
+- GBM subgraph wrappers:
+  - `ag auction get --id <auctionId> [--verify-onchain]`
+  - `ag auction active [--first] [--skip] [--at-time <unix>]`
+  - `ag auction mine --seller <0x...> [--first] [--skip]`
+  - `ag auction bids --auction-id <id> [--first] [--skip]`
+  - `ag auction bids-mine --bidder <0x...> [--first] [--skip]`
+- Optional `--raw` GraphQL payload passthrough while preserving typed projections.
+- New docs under `docs/subgraph/` for endpoint policy and query matrix.
+
+### Security and policy
+
+- Strict endpoint allowlist by default for canonical sources only.
+- Custom endpoint override requires both `--subgraph-url` and `--allow-untrusted-subgraph`.
+- Non-HTTPS custom subgraph endpoints are rejected.
+
+### Notes
+
+- Existing `onchain`, `tx`, mapped write aliases, and `baazaar read` onchain call behavior are preserved.

package/README.md

@@ -32,7 +32,7 @@ For read-only automation:
 npm run ag -- bootstrap --mode agent --profile prod --chain base --signer readonly --json
 ```
 
-## Command surface (current)
+## Command surface (v0.2.0)
 
 - `bootstrap`
 - `profile list|show|use|export`
@@ -43,6 +43,9 @@ npm run ag -- bootstrap --mode agent --profile prod --chain base --signer readon
 - `tx send|status|resume|watch`
 - `batch run --file plan.yaml`
 - `onchain call|send`
+- `subgraph list|check|query`
+- `baazaar listing get|active|mine` (subgraph-first read wrappers)
+- `auction get|active|mine|bids|bids-mine` (subgraph-first read wrappers)
 - `<domain> read` (routes to generic onchain call for that domain)
 
 Planned domain namespaces are stubbed for parity tracking:
@@ -52,6 +55,71 @@ Planned domain namespaces are stubbed for parity tracking:
 Many Base-era write flows are already executable as mapped aliases in those namespaces (internally routed through `onchain send`).
 Example: `ag lending create --abi-file ./abis/GotchiLendingFacet.json --address 0x... --args-json '[...]' --json`
 
+## Subgraph sources and endpoint policy
+
+Canonical source aliases:
+
+- `core-base` -> `https://api.goldsky.com/api/public/project_cmh3flagm0001r4p25foufjtt/subgraphs/aavegotchi-core-base/prod/gn`
+- `gbm-base` -> `https://api.goldsky.com/api/public/project_cmh3flagm0001r4p25foufjtt/subgraphs/aavegotchi-gbm-baazaar-base/prod/gn`
+
+Default policy is strict allowlist:
+
+- Non-canonical subgraph URLs are blocked by default (`SUBGRAPH_ENDPOINT_BLOCKED`)
+- Override is explicit and per-command only: pass both `--subgraph-url <https-url>` and `--allow-untrusted-subgraph`
+- Non-HTTPS custom URLs are rejected
+
+Auth:
+
+- Public Goldsky endpoints work without auth
+- If `GOLDSKY_API_KEY` is set, CLI injects `Authorization: Bearer <token>`
+- Override env var name per command with `--auth-env-var <ENV>`
+
+## Subgraph command examples
+
+List configured canonical sources:
+
+```bash
+npm run ag -- subgraph list --json
+```
+
+Check source reachability/introspection:
+
+```bash
+npm run ag -- subgraph check --source core-base --json
+```
+
+Run custom GraphQL query:
+
+```bash
+npm run ag -- subgraph query \
+  --source gbm-base \
+  --query 'query($first:Int!){ auctions(first:$first){ id } }' \
+  --variables-json '{"first":5}' \
+  --json
+```
+
+Baazaar wrappers:
+
+```bash
+npm run ag -- baazaar listing active --kind erc721 --first 20 --skip 0 --json
+npm run ag -- baazaar listing mine --kind erc1155 --seller 0x... --json
+npm run ag -- baazaar listing get --kind erc721 --id 123 --verify-onchain --json
+```
+
+GBM wrappers:
+
+```bash
+npm run ag -- auction active --first 20 --json
+npm run ag -- auction bids --auction-id 123 --json
+npm run ag -- auction get --id 123 --verify-onchain --json
+```
+
+Raw GraphQL passthrough (typed projection remains included):
+
+```bash
+npm run ag -- auction active --first 5 --raw --json
+```
+
 ## Signer backends
 
 - `readonly` (read-only mode)
@@ -106,6 +174,8 @@ All successful/error responses use a stable envelope:
 
 - Method inventory: [`docs/parity/base-method-inventory.md`](docs/parity/base-method-inventory.md)
 - Command mapping: [`docs/parity/base-command-matrix.md`](docs/parity/base-command-matrix.md)
+- Subgraph endpoints/policy: [`docs/subgraph/endpoints-and-policy.md`](docs/subgraph/endpoints-and-policy.md)
+- Subgraph query matrix: [`docs/subgraph/query-matrix.md`](docs/subgraph/query-matrix.md)
 
 Raffle/ticket flows are intentionally excluded for Base-era scope.
 

package/dist/command-runner.js

@@ -7,11 +7,14 @@ const batch_1 = require("./commands/batch");
 const bootstrap_1 = require("./commands/bootstrap");
 const mapped_1 = require("./commands/mapped");
 const onchain_1 = require("./commands/onchain");
+const auction_subgraph_1 = require("./commands/auction-subgraph");
+const baazaar_subgraph_1 = require("./commands/baazaar-subgraph");
 const policy_1 = require("./commands/policy");
 const profile_1 = require("./commands/profile");
 const rpc_1 = require("./commands/rpc");
 const signer_1 = require("./commands/signer");
 const stubs_1 = require("./commands/stubs");
+const subgraph_1 = require("./commands/subgraph");
 const tx_1 = require("./commands/tx");
 function normalizeCommandPath(positionals) {
     if (positionals.length === 0 || positionals[0] === "help") {
@@ -156,6 +159,43 @@ async function executeCommand(ctx) {
             };
         }
     }
+    if (root === "subgraph") {
+        if (!sub || sub === "list") {
+            return {
+                commandName: "subgraph list",
+                data: await (0, subgraph_1.runSubgraphListCommand)(),
+            };
+        }
+        if (sub === "check") {
+            return {
+                commandName: "subgraph check",
+                data: await (0, subgraph_1.runSubgraphCheckCommand)(ctx),
+            };
+        }
+        if (sub === "query") {
+            return {
+                commandName: "subgraph query",
+                data: await (0, subgraph_1.runSubgraphQueryCommand)(ctx),
+            };
+        }
+    }
+    if (root === "baazaar" && sub === "listing") {
+        const action = ctx.commandPath[2];
+        if (action === "get" || action === "active" || action === "mine") {
+            return {
+                commandName: ctx.commandPath.join(" "),
+                data: await (0, baazaar_subgraph_1.runBaazaarListingSubgraphCommand)(ctx),
+            };
+        }
+    }
+    if (root === "auction") {
+        if (sub === "get" || sub === "active" || sub === "mine" || sub === "bids" || sub === "bids-mine") {
+            return {
+                commandName: ctx.commandPath.join(" "),
+                data: await (0, auction_subgraph_1.runAuctionSubgraphCommand)(ctx),
+            };
+        }
+    }
     if (root === "batch" && (!sub || sub === "run")) {
         return {
             commandName: "batch run",

package/dist/commands/auction-subgraph.js

@@ -0,0 +1,400 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuctionGetSubgraphCommand = runAuctionGetSubgraphCommand;
+exports.runAuctionActiveSubgraphCommand = runAuctionActiveSubgraphCommand;
+exports.runAuctionMineSubgraphCommand = runAuctionMineSubgraphCommand;
+exports.runAuctionBidsSubgraphCommand = runAuctionBidsSubgraphCommand;
+exports.runAuctionBidsMineSubgraphCommand = runAuctionBidsMineSubgraphCommand;
+exports.runAuctionSubgraphCommand = runAuctionSubgraphCommand;
+const viem_1 = require("viem");
+const args_1 = require("../args");
+const chains_1 = require("../chains");
+const config_1 = require("../config");
+const errors_1 = require("../errors");
+const rpc_1 = require("../rpc");
+const normalize_1 = require("../subgraph/normalize");
+const queries_1 = require("../subgraph/queries");
+const sources_1 = require("../subgraph/sources");
+const client_1 = require("../subgraph/client");
+const DEFAULT_FIRST = 20;
+const MAX_FIRST = 200;
+const DEFAULT_SKIP = 0;
+const MAX_SKIP = 100000;
+const GBM_VERIFY_ABI = (0, viem_1.parseAbi)([
+    "function getAuctionHighestBid(uint256 _auctionId) view returns (uint256)",
+    "function getContractAddress(uint256 _auctionId) view returns (address)",
+    "function getTokenId(uint256 _auctionId) view returns (uint256)",
+    "function getAuctionStartTime(uint256 _auctionId) view returns (uint256)",
+    "function getAuctionEndTime(uint256 _auctionId) view returns (uint256)",
+]);
+function parseRawFlag(ctx) {
+    return (0, args_1.getFlagBoolean)(ctx.args.flags, "raw");
+}
+function parseTimeoutMs(value) {
+    if (!value) {
+        return undefined;
+    }
+    const timeout = Number(value);
+    if (!Number.isInteger(timeout) || timeout <= 0) {
+        throw new errors_1.CliError("INVALID_ARGUMENT", "--timeout-ms must be a positive integer.", 2, {
+            value,
+        });
+    }
+    return timeout;
+}
+function parseBoundedIntFlag(value, flagName, fallback, min, max) {
+    if (!value) {
+        return fallback;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+        throw new errors_1.CliError("INVALID_ARGUMENT", `${flagName} must be an integer between ${min} and ${max}.`, 2, {
+            value,
+        });
+    }
+    return parsed;
+}
+function parsePagination(ctx) {
+    const first = parseBoundedIntFlag((0, args_1.getFlagString)(ctx.args.flags, "first"), "--first", DEFAULT_FIRST, 1, MAX_FIRST);
+    const skip = parseBoundedIntFlag((0, args_1.getFlagString)(ctx.args.flags, "skip"), "--skip", DEFAULT_SKIP, 0, MAX_SKIP);
+    return {
+        first,
+        skip,
+    };
+}
+function parseAddress(value, flagName) {
+    if (!value || !/^0x[a-fA-F0-9]{40}$/.test(value)) {
+        throw new errors_1.CliError("INVALID_ARGUMENT", `${flagName} must be an EVM address.`, 2, {
+            value,
+        });
+    }
+    return (0, normalize_1.toLowercaseAddress)(value);
+}
+function parseAuctionId(value, flagName) {
+    if (!value) {
+        throw new errors_1.CliError("MISSING_ARGUMENT", `${flagName} is required.`, 2);
+    }
+    if (!/^\d+$/.test(value)) {
+        throw new errors_1.CliError("INVALID_ARGUMENT", `${flagName} must be an unsigned integer string.`, 2, {
+            value,
+        });
+    }
+    return value;
+}
+function parseActiveTime(ctx) {
+    const atTime = (0, args_1.getFlagString)(ctx.args.flags, "at-time");
+    if (!atTime) {
+        return Math.floor(Date.now() / 1000).toString();
+    }
+    if (!/^\d+$/.test(atTime)) {
+        throw new errors_1.CliError("INVALID_ARGUMENT", "--at-time must be a unix timestamp (seconds).", 2, {
+            value: atTime,
+        });
+    }
+    return atTime;
+}
+function parseCommonSubgraphOptions(ctx) {
+    const subgraphUrl = (0, args_1.getFlagString)(ctx.args.flags, "subgraph-url");
+    const allowUntrustedSubgraph = (0, args_1.getFlagBoolean)(ctx.args.flags, "allow-untrusted-subgraph");
+    if (allowUntrustedSubgraph && !subgraphUrl) {
+        throw new errors_1.CliError("INVALID_ARGUMENT", "--allow-untrusted-subgraph requires --subgraph-url.", 2);
+    }
+    return {
+        source: "gbm-base",
+        timeoutMs: parseTimeoutMs((0, args_1.getFlagString)(ctx.args.flags, "timeout-ms")),
+        authEnvVar: (0, args_1.getFlagString)(ctx.args.flags, "auth-env-var"),
+        subgraphUrl,
+        allowUntrustedSubgraph,
+    };
+}
+function parseVerifyOnchainFlag(ctx) {
+    return (0, args_1.getFlagBoolean)(ctx.args.flags, "verify-onchain");
+}
+function resolveReadRpcUrl(ctx) {
+    const explicitRpc = (0, args_1.getFlagString)(ctx.args.flags, "rpc-url");
+    if (explicitRpc) {
+        return explicitRpc;
+    }
+    const profileName = (0, args_1.getFlagString)(ctx.args.flags, "profile") || ctx.globals.profile;
+    if (profileName) {
+        const config = (0, config_1.loadConfig)();
+        const profile = (0, config_1.getProfileOrThrow)(config, profileName);
+        return profile.rpcUrl;
+    }
+    return (0, chains_1.resolveRpcUrl)((0, chains_1.resolveChain)("base"), undefined);
+}
+function createMismatchDiff(keys, subgraph, onchain) {
+    const diff = {};
+    for (const key of keys) {
+        if (subgraph[key] !== onchain[key]) {
+            diff[key] = {
+                subgraph: subgraph[key],
+                onchain: onchain[key],
+            };
+        }
+    }
+    return diff;
+}
+function withNormalizeContext(response, normalize) {
+    try {
+        return normalize();
+    }
+    catch (error) {
+        if (error instanceof errors_1.CliError && error.code === "SUBGRAPH_INVALID_RESPONSE") {
+            const extraDetails = error.details && typeof error.details === "object" ? error.details : {};
+            throw new errors_1.CliError(error.code, error.message, error.exitCode, {
+                source: response.source,
+                endpoint: response.endpoint,
+                queryName: response.queryName,
+                ...extraDetails,
+            });
+        }
+        throw error;
+    }
+}
+async function verifyAuctionOnchain(ctx, auction) {
+    const chain = (0, chains_1.resolveChain)("base");
+    const rpcUrl = resolveReadRpcUrl(ctx);
+    const preflight = await (0, rpc_1.runRpcPreflight)(chain, rpcUrl);
+    const auctionId = BigInt(auction.id);
+    const [highestBid, contractAddress, tokenId, startsAt, endsAt] = await Promise.all([
+        preflight.client.readContract({
+            address: sources_1.BASE_GBM_DIAMOND,
+            abi: GBM_VERIFY_ABI,
+            functionName: "getAuctionHighestBid",
+            args: [auctionId],
+        }),
+        preflight.client.readContract({
+            address: sources_1.BASE_GBM_DIAMOND,
+            abi: GBM_VERIFY_ABI,
+            functionName: "getContractAddress",
+            args: [auctionId],
+        }),
+        preflight.client.readContract({
+            address: sources_1.BASE_GBM_DIAMOND,
+            abi: GBM_VERIFY_ABI,
+            functionName: "getTokenId",
+            args: [auctionId],
+        }),
+        preflight.client.readContract({
+            address: sources_1.BASE_GBM_DIAMOND,
+            abi: GBM_VERIFY_ABI,
+            functionName: "getAuctionStartTime",
+            args: [auctionId],
+        }),
+        preflight.client.readContract({
+            address: sources_1.BASE_GBM_DIAMOND,
+            abi: GBM_VERIFY_ABI,
+            functionName: "getAuctionEndTime",
+            args: [auctionId],
+        }),
+    ]);
+    const onchainProjection = {
+        highestBid: highestBid.toString(),
+        contractAddress: (0, normalize_1.toLowercaseAddress)(contractAddress),
+        tokenId: tokenId.toString(),
+        startsAt: startsAt.toString(),
+        endsAt: endsAt.toString(),
+    };
+    const subgraphProjection = {
+        highestBid: auction.highestBid,
+        contractAddress: auction.contractAddress,
+        tokenId: auction.tokenId,
+        startsAt: auction.startsAt,
+        endsAt: auction.endsAt,
+    };
+    const diff = createMismatchDiff(["highestBid", "contractAddress", "tokenId", "startsAt", "endsAt"], subgraphProjection, onchainProjection);
+    if (Object.keys(diff).length > 0) {
+        throw new errors_1.CliError("SUBGRAPH_VERIFY_MISMATCH", "Subgraph auction does not match onchain snapshot.", 2, {
+            source: "gbm-base",
+            endpoint: "onchain-verify",
+            queryName: "auction.get",
+            auctionId: auction.id,
+            rpcUrl,
+            contractAddress: sources_1.BASE_GBM_DIAMOND,
+            diff,
+        });
+    }
+    return {
+        verified: true,
+        rpcUrl,
+        chainId: preflight.chainId,
+        contractAddress: sources_1.BASE_GBM_DIAMOND,
+    };
+}
+async function runAuctionGetSubgraphCommand(ctx) {
+    const id = parseAuctionId((0, args_1.getFlagString)(ctx.args.flags, "id"), "--id");
+    const raw = parseRawFlag(ctx);
+    const verifyOnchain = parseVerifyOnchainFlag(ctx);
+    const common = parseCommonSubgraphOptions(ctx);
+    const response = await (0, client_1.executeSubgraphQuery)({
+        ...common,
+        queryName: "auction.get",
+        query: queries_1.GBM_AUCTION_BY_ID_QUERY,
+        variables: { id },
+        raw,
+    });
+    const auction = response.data.auction
+        ? withNormalizeContext(response, () => (0, normalize_1.normalizeGbmAuction)(response.data.auction))
+        : null;
+    const verification = verifyOnchain && auction ? await verifyAuctionOnchain(ctx, auction) : undefined;
+    return {
+        source: response.source,
+        endpoint: response.endpoint,
+        queryName: response.queryName,
+        auction,
+        ...(verification ? { verification } : {}),
+        ...(raw ? { raw: response.raw } : {}),
+    };
+}
+async function runAuctionActiveSubgraphCommand(ctx) {
+    const pagination = parsePagination(ctx);
+    const now = parseActiveTime(ctx);
+    const raw = parseRawFlag(ctx);
+    const common = parseCommonSubgraphOptions(ctx);
+    const response = await (0, client_1.executeSubgraphQuery)({
+        ...common,
+        queryName: "auction.active",
+        query: queries_1.GBM_ACTIVE_AUCTIONS_QUERY,
+        variables: {
+            now,
+            ...pagination,
+        },
+        raw,
+    });
+    if (!Array.isArray(response.data.auctions)) {
+        throw new errors_1.CliError("SUBGRAPH_INVALID_RESPONSE", "Expected auctions to be an array.", 2, {
+            source: response.source,
+            endpoint: response.endpoint,
+            queryName: response.queryName,
+        });
+    }
+    const auctions = response.data.auctions;
+    return {
+        source: response.source,
+        endpoint: response.endpoint,
+        queryName: response.queryName,
+        atTime: now,
+        pagination,
+        auctions: withNormalizeContext(response, () => (0, normalize_1.normalizeGbmAuctions)(auctions)),
+        ...(raw ? { raw: response.raw } : {}),
+    };
+}
+async function runAuctionMineSubgraphCommand(ctx) {
+    const seller = parseAddress((0, args_1.getFlagString)(ctx.args.flags, "seller"), "--seller");
+    const pagination = parsePagination(ctx);
+    const raw = parseRawFlag(ctx);
+    const common = parseCommonSubgraphOptions(ctx);
+    const response = await (0, client_1.executeSubgraphQuery)({
+        ...common,
+        queryName: "auction.mine",
+        query: queries_1.GBM_MINE_AUCTIONS_QUERY,
+        variables: {
+            seller,
+            ...pagination,
+        },
+        raw,
+    });
+    if (!Array.isArray(response.data.auctions)) {
+        throw new errors_1.CliError("SUBGRAPH_INVALID_RESPONSE", "Expected auctions to be an array.", 2, {
+            source: response.source,
+            endpoint: response.endpoint,
+            queryName: response.queryName,
+        });
+    }
+    const auctions = response.data.auctions;
+    return {
+        source: response.source,
+        endpoint: response.endpoint,
+        queryName: response.queryName,
+        seller,
+        pagination,
+        auctions: withNormalizeContext(response, () => (0, normalize_1.normalizeGbmAuctions)(auctions)),
+        ...(raw ? { raw: response.raw } : {}),
+    };
+}
+async function runAuctionBidsSubgraphCommand(ctx) {
+    const auctionId = parseAuctionId((0, args_1.getFlagString)(ctx.args.flags, "auction-id"), "--auction-id");
+    const pagination = parsePagination(ctx);
+    const raw = parseRawFlag(ctx);
+    const common = parseCommonSubgraphOptions(ctx);
+    const response = await (0, client_1.executeSubgraphQuery)({
+        ...common,
+        queryName: "auction.bids",
+        query: queries_1.GBM_BIDS_BY_AUCTION_QUERY,
+        variables: {
+            auctionId,
+            ...pagination,
+        },
+        raw,
+    });
+    if (!Array.isArray(response.data.bids)) {
+        throw new errors_1.CliError("SUBGRAPH_INVALID_RESPONSE", "Expected bids to be an array.", 2, {
+            source: response.source,
+            endpoint: response.endpoint,
+            queryName: response.queryName,
+        });
+    }
+    const bids = response.data.bids;
+    return {
+        source: response.source,
+        endpoint: response.endpoint,
+        queryName: response.queryName,
+        auctionId,
+        pagination,
+        bids: withNormalizeContext(response, () => (0, normalize_1.normalizeGbmBids)(bids)),
+        ...(raw ? { raw: response.raw } : {}),
+    };
+}
+async function runAuctionBidsMineSubgraphCommand(ctx) {
+    const bidder = parseAddress((0, args_1.getFlagString)(ctx.args.flags, "bidder"), "--bidder");
+    const pagination = parsePagination(ctx);
+    const raw = parseRawFlag(ctx);
+    const common = parseCommonSubgraphOptions(ctx);
+    const response = await (0, client_1.executeSubgraphQuery)({
+        ...common,
+        queryName: "auction.bids-mine",
+        query: queries_1.GBM_BIDS_BY_BIDDER_QUERY,
+        variables: {
+            bidder,
+            ...pagination,
+        },
+        raw,
+    });
+    if (!Array.isArray(response.data.bids)) {
+        throw new errors_1.CliError("SUBGRAPH_INVALID_RESPONSE", "Expected bids to be an array.", 2, {
+            source: response.source,
+            endpoint: response.endpoint,
+            queryName: response.queryName,
+        });
+    }
+    const bids = response.data.bids;
+    return {
+        source: response.source,
+        endpoint: response.endpoint,
+        queryName: response.queryName,
+        bidder,
+        pagination,
+        bids: withNormalizeContext(response, () => (0, normalize_1.normalizeGbmBids)(bids)),
+        ...(raw ? { raw: response.raw } : {}),
+    };
+}
+async function runAuctionSubgraphCommand(ctx) {
+    const action = ctx.commandPath[1];
+    if (action === "get") {
+        return runAuctionGetSubgraphCommand(ctx);
+    }
+    if (action === "active") {
+        return runAuctionActiveSubgraphCommand(ctx);
+    }
+    if (action === "mine") {
+        return runAuctionMineSubgraphCommand(ctx);
+    }
+    if (action === "bids") {
+        return runAuctionBidsSubgraphCommand(ctx);
+    }
+    if (action === "bids-mine") {
+        return runAuctionBidsMineSubgraphCommand(ctx);
+    }
+    throw new errors_1.CliError("UNKNOWN_COMMAND", `Unknown command '${ctx.commandPath.join(" ")}'.`, 2);
+}