@w3lib/evm-batch-call 0.6.0 → 0.8.0

package/dist/history.d.ts

@@ -0,0 +1,154 @@
+import type { Provider } from './provider.js';
+import { type HistorySource } from './historySources.js';
+export type ActivityType = 'transfer' | 'swap' | 'approve' | 'liquidity' | 'mint' | 'contract' | 'other';
+export interface ActivityChange {
+    /** 代币 / NFT 合约地址；主币是 'native' */
+    asset: string;
+    symbol: string | null;
+    decimals: number;
+    /** 带符号的最小单位数量 */
+    delta: string;
+    formatted: string;
+    /** NFT（721 / 1155）：tokenId */
+    tokenId?: string;
+}
+export interface Activity {
+    hash: string;
+    /** 秒级时间戳 */
+    time: number;
+    block?: number;
+    status: 'success' | 'failed';
+    type: ActivityType;
+    /** 转账 / 铸造的方向（自己转给自己是 self）；兑换等没有 */
+    direction?: 'in' | 'out' | 'self';
+    /** 对方地址（转账的另一方；合约调用是合约地址） */
+    counterparty?: string;
+    /** 一句话描述 */
+    label?: string;
+    /** 这个地址的资产变化（失败的交易没有） */
+    changes: ActivityChange[];
+    /** 手续费（最小单位的主币，只有这个地址是发送者时）。Tron 为 sun */
+    fee?: string;
+    protocol?: string;
+    /** 调用的方法名（能解码时） */
+    method?: string;
+}
+export interface RawTx {
+    hash: string;
+    /** 位置：EVM 是区块号，Tron 是毫秒时间戳（分页用） */
+    pos: number;
+    block?: number;
+    time: number;
+    from: string;
+    to?: string | null;
+    /** 附带的主币 */
+    value: bigint;
+    /** calldata（0x 开头） */
+    input: string;
+    ok: boolean;
+    fee?: bigint;
+}
+export interface RawMove {
+    hash: string;
+    pos: number;
+    block?: number;
+    time: number;
+    /** 'native' 或代币合约地址 */
+    asset: string;
+    from: string;
+    to: string;
+    value: bigint;
+    tokenId?: string;
+    symbol?: string | null;
+    decimals?: number | null;
+}
+export interface RawPage {
+    txs: RawTx[];
+    moves: RawMove[];
+    /** 位置 ≥ 这个值的记录是完整的（列表按条数截断时，最后一个位置上的记录可能只拿到一部分）；没有更多历史时为 0 */
+    completeFrom: number;
+    /** 下一页查到这个位置（含）为止，往旧的方向；没有更多历史时没有 */
+    next?: number;
+}
+export interface HistoryQuery {
+    /** 要查的地址：EVM 是 0x 小写，Tron 是 T 开头 */
+    address: string;
+    chainId: number;
+    /** 每次从各个列表取多少条 */
+    limit: number;
+    /** 只查位置 ≤ 这个值的记录（分页用，不传从最新开始） */
+    endPos?: number;
+    /** 是否包含 NFT 转账 */
+    nft: boolean;
+    provider: Provider;
+    fetch: typeof fetch;
+    signal?: AbortSignal;
+}
+/** 数据来源适配器：按查询返回原始记录 */
+export interface HistoryAdapter {
+    name: string;
+    /** 这个来源是否支持这条链（不支持的在故障切换里直接跳过） */
+    supports?(chainId: number): boolean;
+    fetch(query: HistoryQuery): Promise<RawPage>;
+}
+export interface HistoryOptions {
+    /** 数据来源：名字（'blockscout' | 'etherscan' | 'rpc' | 'trongrid'）、适配器对象，或它们的数组（按顺序故障切换）。默认：有 Blockscout 的链 [blockscout, rpc]，否则 [rpc]；传了 apiKey 时 etherscan 排最前；Tron 是 trongrid */
+    source?: HistorySource | readonly HistorySource[];
+    /** Etherscan 系（v2，一个 Key 覆盖多条链）/ TronGrid 的 API Key */
+    apiKey?: string;
+    /** 至少返回多少条（按区块整块取，可能略多；历史到头时可能不足） */
+    limit?: number;
+    /** 上一次返回的 nextCursor */
+    cursor?: string;
+    /** 只要这些类型（过滤后不够 limit 会继续往前翻页，直到 maxPages） */
+    types?: readonly ActivityType[];
+    /** 时间范围（秒级时间戳）：只要这个时间之前 / 之后的；往前翻到早于 after 就停 */
+    before?: number;
+    after?: number;
+    /** 是否包含 NFT 转账，默认 true */
+    nft?: boolean;
+    /** 为凑够 limit 最多翻几页，默认 5 */
+    maxPages?: number;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}
+export interface HistoryResult {
+    items: Activity[];
+    /** 还有更早的历史时给出，传给下一次的 cursor */
+    nextCursor?: string;
+    /** 实际用的数据来源 */
+    source: string;
+}
+export declare class HistorySourceError extends Error {
+    readonly errors: ReadonlyArray<{
+        source: string;
+        error: unknown;
+    }>;
+    constructor(errors: ReadonlyArray<{
+        source: string;
+        error: unknown;
+    }>);
+}
+interface BuildCtx {
+    chainId: number;
+    tron: boolean;
+    /** 比较用的 0x 小写地址 */
+    me: string;
+    native: {
+        symbol: string | null;
+        decimals: number;
+    };
+}
+export declare function buildActivities(page: Pick<RawPage, 'txs' | 'moves'>, ctx: BuildCtx, minPos?: number): Activity[];
+/**
+ * 查一个地址的历史活动（最新的在前），分页用 nextCursor。
+ *
+ * ```ts
+ * const page = await history(provider, user, { limit: 20 })                       // Blockscout，失败换 RPC 日志
+ * const next = await history(provider, user, { cursor: page.nextCursor, types: ['swap'] })
+ * await history(provider, user, { source: ['etherscan', 'rpc'], apiKey })         // Etherscan v2 的 Key 覆盖多条链
+ * ```
+ */
+export declare function history(provider: Provider, address: string, options?: HistoryOptions): Promise<HistoryResult>;
+export type { HistorySource } from './historySources.js';
+//# sourceMappingURL=history.d.ts.map

package/dist/history.d.ts.map

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

package/dist/history.js

@@ -0,0 +1,247 @@
+/**
+ * 交易历史（子路径 `@w3lib/evm-batch-call/history`）：一个地址的转账 / 兑换 / 授权 / 流动性 / 铸造记录，统一成 Activity。
+ * 数据来源是可替换的适配器（见 historySources.ts）：Blockscout、Etherscan 系（需要 Key）、纯 RPC 日志、Tron 的 TronGrid；
+ * `source: [a, b]` 按顺序故障切换。适配器只返回原始记录（交易、转账），这里负责合并、解码和分类。
+ */
+import { getAddress } from 'ethers';
+import { getNativeCurrency } from './chains.js';
+import { formatUnits } from './erc20.js';
+import { decodeCalldata } from './simulateDecode.js';
+import { historySourcesFor } from './historySources.js';
+import { isTronChain, toEvmAddress, toTronAddress } from './tron.js';
+export class HistorySourceError extends Error {
+    errors;
+    constructor(errors) {
+        super(`All history sources failed: ${errors.map((e) => `${e.source}: ${e.error instanceof Error ? e.error.message : String(e.error)}`).join(' | ')}`);
+        this.errors = errors;
+        this.name = 'HistorySourceError';
+    }
+}
+const ZERO = '0x0000000000000000000000000000000000000000';
+const CURSOR_RE = /^p:(\d+)$/;
+const short = (a) => `${a.slice(0, 6)}…${a.slice(-4)}`;
+/** 地址的比较键：EVM 小写 0x；Tron 的 T 地址 / 41 开头的 hex 地址转成 0x 小写 */
+function key(ctx, address) {
+    if (!ctx.tron)
+        return address.toLowerCase();
+    try {
+        return toEvmAddress(address).toLowerCase();
+    }
+    catch {
+        return address.toLowerCase();
+    }
+}
+const show = (ctx, address) => {
+    try {
+        return ctx.tron ? toTronAddress(address) : getAddress(address);
+    }
+    catch {
+        return address;
+    }
+};
+function changesOf(ctx, moves) {
+    const net = new Map();
+    const partners = new Map();
+    let mints = false;
+    for (const m of moves) {
+        const from = key(ctx, m.from);
+        const to = key(ctx, m.to);
+        if (from === to)
+            continue;
+        const sign = to === ctx.me ? 1n : from === ctx.me ? -1n : 0n;
+        if (!sign)
+            continue;
+        const nft = m.tokenId !== undefined;
+        const k = `${m.asset}|${m.tokenId ?? ''}`;
+        const decimals = nft ? 0 : (m.decimals ?? (m.asset === 'native' ? ctx.native.decimals : 18));
+        const entry = net.get(k) ?? { asset: m.asset === 'native' ? 'native' : show(ctx, m.asset), symbol: m.asset === 'native' ? ctx.native.symbol : (m.symbol ?? null), decimals, delta: '0', formatted: '0', ...(nft ? { tokenId: m.tokenId } : {}), raw: 0n };
+        entry.raw += sign * m.value;
+        net.set(k, entry);
+        const other = sign > 0n ? from : to;
+        partners.set(other, (partners.get(other) ?? 0n) + m.value);
+        if (sign > 0n && from === ZERO && (nft || m.asset !== 'native'))
+            mints = true;
+    }
+    const changes = [...net.values()].filter((e) => e.raw !== 0n).sort((a, b) => Number(a.raw > 0n) - Number(b.raw > 0n)).map(({ raw, ...e }) => ({ ...e, delta: raw.toString(), formatted: formatUnits(raw, e.decimals) }));
+    return { changes, mints, partners };
+}
+const amount = (c) => `${c.formatted.replace('-', '')} ${c.symbol ?? (c.tokenId === undefined ? short(c.asset) : `#${c.tokenId}`)}`;
+function classify(ctx, tx, decoded, changes, mints) {
+    const outs = changes.filter((c) => c.delta.startsWith('-'));
+    const ins = changes.filter((c) => !c.delta.startsWith('-'));
+    const sender = tx !== undefined && key(ctx, tx.from) === ctx.me;
+    if (sender && decoded?.type === 'approve')
+        return 'approve';
+    if (sender && decoded?.type === 'liquidity')
+        return 'liquidity';
+    if (mints && ins.length)
+        return 'mint';
+    if (outs.length && ins.length && new Set([...outs, ...ins].map((c) => `${c.asset}|${c.tokenId ?? ''}`)).size > 1)
+        return 'swap';
+    if (decoded?.type === 'swap')
+        return 'swap';
+    if (changes.length || (tx && tx.input === '0x') || decoded?.type === 'transfer')
+        return 'transfer';
+    if (decoded)
+        return 'contract';
+    return 'other';
+}
+export function buildActivities(page, ctx, minPos = 0) {
+    const groups = new Map();
+    const group = (hash, pos, time, block) => {
+        let g = groups.get(hash);
+        if (!g)
+            groups.set(hash, (g = { moves: [], pos, time, block }));
+        return g;
+    };
+    for (const tx of page.txs)
+        if (tx.pos >= minPos)
+            group(tx.hash, tx.pos, tx.time, tx.block).tx = tx;
+    for (const m of page.moves)
+        if (m.pos >= minPos)
+            group(m.hash, m.pos, m.time, m.block).moves.push(m);
+    const items = [];
+    for (const [hash, g] of groups) {
+        const { tx } = g;
+        const moves = [...g.moves];
+        // 顶层的主币转账（explorer 的转账列表里没有）；失败的交易没有任何资产变化
+        if (tx?.ok && tx.value > 0n && tx.to)
+            moves.push({ hash, pos: g.pos, time: g.time, asset: 'native', from: tx.from, to: tx.to, value: tx.value });
+        const { changes, mints, partners } = tx && !tx.ok ? { changes: [], mints: false, partners: new Map() } : changesOf(ctx, moves);
+        const decoded = tx && tx.input !== '0x' && tx.to ? decodeCalldata(tx.input, { to: show(ctx, tx.to), chainId: ctx.chainId, value: tx.value }) : null;
+        const type = classify(ctx, tx, decoded, changes, mints);
+        const sender = tx !== undefined && key(ctx, tx.from) === ctx.me;
+        const outs = changes.filter((c) => c.delta.startsWith('-'));
+        const ins = changes.filter((c) => !c.delta.startsWith('-'));
+        let direction;
+        if (type === 'transfer' || type === 'mint') {
+            if (tx?.to && key(ctx, tx.to) === ctx.me && sender)
+                direction = 'self';
+            else if (outs.length && !ins.length)
+                direction = 'out';
+            else if (ins.length && !outs.length)
+                direction = 'in';
+            else if (!changes.length)
+                direction = sender ? 'out' : 'in';
+        }
+        // 对方：转账是出入金额最大的那一方；其他是合约（自己发起时）或发起者
+        let counterparty;
+        if (type === 'transfer' || type === 'mint') {
+            const top = [...partners.entries()].sort((a, b) => (a[1] > b[1] ? -1 : 1))[0]?.[0];
+            counterparty = top && top !== ZERO ? top : tx?.to && !sender ? tx.from : (tx?.to ?? undefined);
+        }
+        else if (tx) {
+            counterparty = sender ? (tx.to ?? undefined) : tx.from;
+        }
+        const protocol = decoded?.protocol;
+        const failed = tx ? !tx.ok : false;
+        let label;
+        if (failed)
+            label = `Failed ${decoded?.method ?? 'transaction'}${protocol ? ` on ${protocol}` : ''}`;
+        else if (type === 'swap')
+            label = `Swapped ${outs.map(amount).join(' + ')} for ${ins.map(amount).join(' + ')}${protocol ? ` on ${protocol}` : ''}`;
+        else if (type === 'approve')
+            label = `Approved ${decoded?.args?.spender ? short(String(decoded.args.spender)) : (decoded?.method ?? 'spending')}${decoded?.args?.amount === '0' || decoded?.args?.approved === false ? ' (revoked)' : ''}`;
+        else if (type === 'liquidity')
+            label = `${decoded?.method ?? 'Liquidity'}${protocol ? ` on ${protocol}` : ''}: ${changes.map((c) => `${c.delta.startsWith('-') ? '-' : '+'}${amount(c)}`).join(', ')}`;
+        else if (type === 'mint')
+            label = `Minted ${ins.map(amount).join(' + ')}`;
+        else if (type === 'transfer') {
+            const cp = counterparty ? short(show(ctx, counterparty)) : '';
+            label = direction === 'in' ? `Received ${ins.map(amount).join(' + ')}${cp ? ` from ${cp}` : ''}` : direction === 'self' ? 'Sent to self' : `Sent ${outs.map(amount).join(' + ') || 'a transaction'}${cp ? ` to ${cp}` : ''}`;
+        }
+        else
+            label = decoded?.summary ?? 'Transaction';
+        items.push({
+            hash,
+            time: g.time,
+            ...(g.block === undefined ? {} : { block: g.block }),
+            status: failed ? 'failed' : 'success',
+            type,
+            ...(direction ? { direction } : {}),
+            ...(counterparty ? { counterparty: show(ctx, counterparty) } : {}),
+            label,
+            changes,
+            ...(sender && tx?.fee !== undefined ? { fee: tx.fee.toString() } : {}),
+            ...(protocol ? { protocol } : {}),
+            ...(decoded?.method ? { method: decoded.method } : {}),
+        });
+    }
+    // 位置新的在前（同一个位置保持原来的顺序）
+    const posOf = new Map([...groups].map(([h, g]) => [h, g.pos]));
+    return items.sort((a, b) => posOf.get(b.hash) - posOf.get(a.hash));
+}
+// ---------------------------------------------------------------------------
+// 入口
+// ---------------------------------------------------------------------------
+/**
+ * 查一个地址的历史活动（最新的在前），分页用 nextCursor。
+ *
+ * ```ts
+ * const page = await history(provider, user, { limit: 20 })                       // Blockscout，失败换 RPC 日志
+ * const next = await history(provider, user, { cursor: page.nextCursor, types: ['swap'] })
+ * await history(provider, user, { source: ['etherscan', 'rpc'], apiKey })         // Etherscan v2 的 Key 覆盖多条链
+ * ```
+ */
+export async function history(provider, address, options = {}) {
+    const chainId = await provider.getChainId();
+    const tron = isTronChain(chainId);
+    const me = tron ? toTronAddress(address) : address.toLowerCase();
+    if (!tron && !/^0x[0-9a-f]{40}$/.test(me))
+        throw new Error(`Invalid address: ${address}`);
+    const limit = Math.max(1, Math.min(200, Math.floor(options.limit ?? 25)));
+    const cursor = options.cursor === undefined ? undefined : Number(CURSOR_RE.exec(options.cursor)?.[1] ?? Number.NaN);
+    if (cursor !== undefined && !Number.isFinite(cursor))
+        throw new Error(`Invalid cursor: ${options.cursor}`);
+    const adapters = historySourcesFor(chainId, options.source, options.apiKey);
+    if (!adapters.length)
+        throw new Error(`No history source for chain ${chainId}: pass options.source`);
+    const nativeCurrency = getNativeCurrency(chainId);
+    const ctx = { chainId, tron, me: tron ? toEvmAddress(me).toLowerCase() : me, native: { symbol: nativeCurrency?.symbol ?? null, decimals: nativeCurrency?.decimals ?? 18 } };
+    const query = (endPos) => ({ address: me, chainId, limit: Math.max(limit, 10), ...(endPos === undefined ? {} : { endPos }), nft: options.nft ?? true, provider, fetch: options.fetch ?? fetch, ...(options.signal ? { signal: options.signal } : {}) });
+    const items = [];
+    const seen = new Set();
+    let pos = cursor;
+    let used = adapters[0]?.name ?? '';
+    let more = true;
+    for (let pages = 0; pages < (options.maxPages ?? 5) && more; pages++) {
+        let page;
+        const errors = [];
+        for (const adapter of adapters) {
+            try {
+                page = await adapter.fetch(query(pos));
+                used = adapter.name;
+                break;
+            }
+            catch (err) {
+                if (options.signal?.aborted)
+                    throw err;
+                errors.push({ source: adapter.name, error: err });
+            }
+        }
+        if (!page)
+            throw new HistorySourceError(errors);
+        // 整页都落在同一个位置、被条数截断时放不下完整记录：宁可收下这一页，也不能原地打转
+        const hasComplete = [...page.txs, ...page.moves].some((r) => r.pos >= page.completeFrom);
+        const batch = buildActivities(page, ctx, hasComplete ? page.completeFrom : 0);
+        for (const a of batch) {
+            if (seen.has(a.hash))
+                continue;
+            seen.add(a.hash);
+            if (options.before !== undefined && a.time >= options.before)
+                continue;
+            if (options.after !== undefined && a.time < options.after)
+                continue;
+            if (options.types && !options.types.includes(a.type))
+                continue;
+            items.push(a);
+        }
+        const oldest = batch.length ? Math.min(...batch.map((a) => a.time)) : Number.POSITIVE_INFINITY;
+        pos = hasComplete ? page.next : page.next === undefined ? undefined : page.next - 1;
+        more = pos !== undefined && pos >= 0 && !(options.after !== undefined && oldest < options.after);
+        if (items.length >= limit)
+            break;
+    }
+    return { items, ...(more && pos !== undefined ? { nextCursor: `p:${pos}` } : {}), source: used };
+}
+//# sourceMappingURL=history.js.map

package/dist/history.js.map

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

package/dist/historySources.d.ts

@@ -0,0 +1,32 @@
+import type { HistoryAdapter } from './history.js';
+export type HistorySource = 'blockscout' | 'etherscan' | 'rpc' | 'trongrid' | HistoryAdapter;
+/**
+ * 各链的 Blockscout 实例。2026-10 验证过可用：1、10、100、534352、324、130、42220、34443、57073；
+ * 8453 / 42161 / 137 的官方实例前面有 Cloudflare 人机验证，脚本请求可能被 403（此时自动换下一个来源）
+ */
+export declare const BLOCKSCOUT_APIS: Readonly<Record<number, string>>;
+/** Blockscout / Etherscan 系适配器：`url` 是接口地址（可以带 chainid 等固定参数） */
+export declare function explorerSource(name: string, url: (chainId: number) => string | undefined, secret?: string): HistoryAdapter;
+/** Blockscout：`urls` 覆盖 / 补充内置的实例表（chainId → 接口地址） */
+export declare function blockscoutSource(urls?: Readonly<Record<number, string>>): HistoryAdapter;
+/** Etherscan v2：一个 Key 覆盖多条链；`baseUrl` 可换成其他 Etherscan 兼容的地址 */
+export declare function etherscanSource(options: {
+    apiKey: string;
+    baseUrl?: string;
+}): HistoryAdapter;
+export interface RpcSourceOptions {
+    /** 每次 getLogs 的区块窗口，默认 2000（节点嫌大时自动对半缩小） */
+    window?: number;
+    /** 一次最多扫多少个窗口，默认 10（凑够条数就提前停；扫不到记录时用 nextCursor 继续） */
+    maxWindows?: number;
+}
+export declare function rpcSource(options?: RpcSourceOptions): HistoryAdapter;
+export interface TrongridSourceOptions {
+    /** 全节点地址，默认 https://api.trongrid.io */
+    host?: string;
+    apiKey?: string;
+}
+export declare function trongridSource(options?: TrongridSourceOptions): HistoryAdapter;
+/** 来源列表 → 适配器：名字按默认配置创建；没传时按链选默认（传了 apiKey 时 etherscan 排最前） */
+export declare function historySourcesFor(chainId: number, source: HistorySource | readonly HistorySource[] | undefined, apiKey?: string): HistoryAdapter[];
+//# sourceMappingURL=historySources.d.ts.map

package/dist/historySources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"historySources.d.ts","sourceRoot":"","sources":["../src/historySources.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAyC,MAAM,cAAc,CAAA;AAIzF,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,WAAW,GAAG,KAAK,GAAG,UAAU,GAAG,cAAc,CAAA;AAE5F;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAa5D,CAAA;AA6DD,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc,CAoC1H;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAAG,cAAc,CAE5F;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAG7F;AAYD,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAmBD,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,cAAc,CAsFxE;AAMD,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAsBD,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAyClF;AAID,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,SAAS,aAAa,EAAE,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CAalJ"}