@across-protocol/sdk 3.0.0

package/src/priceClient/README.md

@@ -0,0 +1,36 @@
+# Price Client
+An interface for retrieving Ethereum ERC20 prices from various price feeds.
+
+# Overview
+The PriceClient aggregates user-defined preferential list of price feeds. This permits prices to be retrieved from a range of sources according to preference (i.e. failover to a lesser-preferred source in the event that a more-preferred source is unavailable).
+
+## Features
+ - Basic support for caching of prices.
+ - Support for bundling token price requests.
+ - Currently supported price feeds:
+     - CoinGecko (Free & Pro)
+     - Across API
+ - Candidates for future addition:
+     - DefiLlama
+     - On-chain lookups (i.e. Uniswap)
+
+This code can be independently used by bots, the frontend, and the backend Across API:
+ - Bots can source their prices from the Across API, falling back to CoinGecko.
+ - The frontend can use this for greater robustness, and to abstract away the source of its price feeds.
+ - The API can add additional fallback price feeds to ensure that it is always able to resolve a price.
+
+The interface exposed by this feature maps very closely to our existing Coingecko API.
+
+### Preferential token price lookups
+The PriceClient is initialised with an ordered list of Price Feeds. When performing price lookups, it will iterate through this list until it is able to successfully resolve a price for the requested tokens.
+
+### Token price cache with configurable age
+PriceClient.maxPriceAge controls the maximum age (in seconds) for cached prices. When a price is requested by a caller, the PriceClient will serve directly out of its internal cache if it holds a price that is younger than the maximum price age. This bypasses an external price lookup and may be used to mitigate rate-limiting. If no price is held, or if an expired price is held, then the PriceClient will perform the lookup against its ordered list of price feeds.
+
+## Constraints
+- There is no mapping of individual tokens to upstream PriceFeedAdapters.
+  If some tokens are only available from specific sources, then a separate
+  PriceClient instance may be used.
+
+## Usage
+Usage instructions will be added.

package/src/priceClient/adapters/acrossApi.ts

@@ -0,0 +1,44 @@
+import { msToS, PriceFeedAdapter, TokenPrice } from "../priceClient";
+import { BaseHTTPAdapter, BaseHTTPAdapterArgs } from "./baseAdapter";
+
+type AcrossPrice = { price: number };
+type AcrossApiArgs = BaseHTTPAdapterArgs & {
+  name?: string;
+  host?: string;
+};
+
+export class PriceFeed extends BaseHTTPAdapter implements PriceFeedAdapter {
+  constructor({
+    name = "Across API",
+    host = "across.to",
+    timeout = 5000, // ms
+    retries = 3,
+  }: AcrossApiArgs = {}) {
+    // Allow host to be overridden for test or alternative deployments.
+    super(name, host, { timeout, retries });
+  }
+
+  async getPriceByAddress(address: string, currency = "usd"): Promise<TokenPrice> {
+    const queryArgs = {
+      l1Token: address,
+      baseCurrency: currency,
+    };
+
+    const now = msToS(Date.now()) - 60; // Assume price is 60 seconds old.
+    const response: unknown = await this.query("api/coingecko", queryArgs);
+    if (!this.validateResponse(response))
+      throw new Error(`Unexpected ${this.name} response: ${JSON.stringify(response)}`);
+
+    return { address: address, price: response.price, timestamp: now };
+  }
+
+  // todo: Support bundled prices in the API endpoint.
+  getPricesByAddress(addresses: string[], currency = "usd"): Promise<TokenPrice[]> {
+    return Promise.all(addresses.map((address) => this.getPriceByAddress(address, currency)));
+  }
+
+  private validateResponse(response: unknown): response is AcrossPrice {
+    if (typeof response !== "object") return false;
+    return response !== null && typeof (response as { [key: string]: unknown }).price === "number";
+  }
+}

package/src/priceClient/adapters/baseAdapter.ts

@@ -0,0 +1,65 @@
+import assert from "assert";
+import axios from "axios";
+
+export type BaseHTTPAdapterArgs = {
+  timeout?: number;
+  retries?: number;
+};
+
+export class BaseHTTPAdapter {
+  private _retries = 0;
+  private _timeout = 0;
+
+  get retries(): number {
+    return this._retries;
+  }
+
+  set retries(retries: number) {
+    assert(retries >= 0);
+    this._retries = retries;
+  }
+
+  get timeout(): number {
+    return this._timeout;
+  }
+
+  set timeout(timeout: number) {
+    assert(timeout >= 0);
+    this._timeout = timeout;
+  }
+
+  constructor(
+    public readonly name: string,
+    public readonly host: string,
+    { timeout = 1000, retries = 1 }: BaseHTTPAdapterArgs
+  ) {
+    this.retries = retries;
+    this.timeout = timeout; // ms
+  }
+
+  protected async query(path: string, urlArgs?: object): Promise<unknown> {
+    const url = `https://${this.host}/${path ?? ""}`;
+    const args = {
+      timeout: this.timeout,
+      params: urlArgs ?? {},
+    };
+
+    const errs: string[] = [];
+    let tries = 0;
+    do {
+      try {
+        return (await axios(url, args)).data;
+      } catch (err) {
+        const errMsg = axios.isAxiosError(err) || err instanceof Error ? err.message : "unknown error";
+        errs.push(errMsg);
+        if (++tries <= this.retries) await this.sleep(Math.pow(1.5, tries) * 1000); // simple backoff
+      }
+    } while (tries <= this.retries);
+
+    throw new Error(`${this.name} price lookup failure (${errs.join(", ")})`);
+  }
+
+  protected sleep(ms: number): Promise<void> {
+    return new Promise((r) => setTimeout(r, ms));
+  }
+}

package/src/priceClient/adapters/coingecko.ts

@@ -0,0 +1,67 @@
+import { PriceFeedAdapter, TokenPrice } from "../priceClient";
+import { BaseHTTPAdapter, BaseHTTPAdapterArgs } from "./baseAdapter";
+
+type CoinGeckoTokenPrice = {
+  [currency: string]: number;
+  last_updated_at: number;
+};
+
+type CoinGeckoPriceResponse = {
+  [address: string]: CoinGeckoTokenPrice;
+};
+
+type CoinGeckoArgs = BaseHTTPAdapterArgs & {
+  name?: string;
+  apiKey?: string;
+};
+
+export class PriceFeed extends BaseHTTPAdapter implements PriceFeedAdapter {
+  private readonly apiKey: string | undefined = undefined;
+
+  constructor({ name, apiKey, timeout = 5000, retries = 3 }: CoinGeckoArgs = {}) {
+    super(name ?? apiKey ? "CoinGecko Pro" : "CoinGecko Free", apiKey ? "pro-api.coingecko.com" : "api.coingecko.com", {
+      timeout,
+      retries,
+    });
+    this.apiKey = apiKey;
+  }
+
+  async getPriceByAddress(address: string, currency = "usd"): Promise<TokenPrice> {
+    const price = await this.getPricesByAddress([address], currency);
+    return price[0];
+  }
+
+  async getPricesByAddress(addresses: string[], currency = "usd"): Promise<TokenPrice[]> {
+    const queryArgs: { [key: string]: boolean | string } = {
+      contract_addresses: addresses.map((address) => address.toLowerCase()).join(","),
+      vs_currencies: currency,
+      include_last_updated_at: true,
+    };
+    if (this.apiKey) queryArgs["x_cg_pro_api_key"] = this.apiKey;
+
+    const prices: unknown = await this.query("api/v3/simple/token_price/ethereum", queryArgs);
+    if (!this.validateResponse(prices, currency))
+      throw new Error(`Unexpected ${this.name} response: ${JSON.stringify(prices)}`);
+
+    return addresses
+      .filter((address) => prices[address.toLowerCase()] !== undefined)
+      .map((address) => {
+        const price: CoinGeckoTokenPrice = prices[address.toLowerCase()];
+        return { address, price: price[currency], timestamp: price.last_updated_at };
+      });
+  }
+
+  private validateResponse(response: unknown, currency: string): response is CoinGeckoPriceResponse {
+    if (typeof response !== "object") return false;
+
+    return Object.entries(response as object).every(([address, tokenPrice]) => {
+      // prettier-ignore
+      return (
+        /0x[0-9a-fA-F]{40}/.exec(address) !== undefined
+        && typeof tokenPrice === "object"
+        && !isNaN(tokenPrice[currency])
+        && !isNaN(tokenPrice.last_updated_at)
+      );
+    });
+  }
+}

package/src/priceClient/adapters/defiLlama.ts

@@ -0,0 +1,96 @@
+import assert from "assert";
+import { PriceFeedAdapter, TokenPrice } from "../priceClient";
+import { BaseHTTPAdapter, BaseHTTPAdapterArgs } from "./baseAdapter";
+
+type DefiLlamaTokenPrice = {
+  price: number;
+  symbol: string;
+  timestamp: number;
+  confidence: number;
+};
+
+type DefiLlamaPriceResponse = {
+  coins: {
+    [key: string]: DefiLlamaTokenPrice;
+  };
+};
+
+type DefiLlamaArgs = BaseHTTPAdapterArgs & {
+  name?: string;
+  host?: string;
+  minConfidence?: number;
+};
+
+export class PriceFeed extends BaseHTTPAdapter implements PriceFeedAdapter {
+  private _minConfidence: number;
+
+  constructor({
+    name = "DefiLlama",
+    host = "coins.llama.fi",
+    timeout = 5000,
+    retries = 2,
+    minConfidence = 0.9,
+  }: DefiLlamaArgs = {}) {
+    super(name, host, { timeout, retries });
+    assert(minConfidence >= 0.0 && minConfidence <= 1.0);
+    this._minConfidence = minConfidence;
+  }
+
+  get minConfidence(): number {
+    return this._minConfidence;
+  }
+
+  set minConfidence(minConfidence: number) {
+    assert(minConfidence >= 0.0 && minConfidence <= 1.0);
+    this._minConfidence = minConfidence;
+  }
+
+  async getPriceByAddress(address: string, currency = "usd"): Promise<TokenPrice> {
+    const price = await this.getPricesByAddress([address], currency);
+    return price[0];
+  }
+
+  async getPricesByAddress(addresses: string[], currency = "usd"): Promise<TokenPrice[]> {
+    if (currency != "usd") throw new Error(`Currency ${currency} not supported by ${this.name}`);
+
+    const path = "prices/current/" + addresses.map((address) => `ethereum:${address.toLowerCase()}`).join();
+    const response: unknown = await this.query(path, {});
+    if (!this.validateResponse(response))
+      throw new Error(`Unexpected ${this.name} response: ${JSON.stringify(response)}`);
+
+    // Normalise the address format: "etherum:<address>" => "<address>".
+    const tokenPrices: { [address: string]: DefiLlamaTokenPrice } = Object.fromEntries(
+      Object.entries(response.coins).map(([identifier, tokenPrice]) => [identifier.split(":")[1], tokenPrice])
+    );
+
+    return addresses
+      .filter((address) => {
+        return (tokenPrices[address.toLowerCase()]?.confidence || 0.0) >= this.minConfidence;
+      })
+      .map((address) => {
+        const { price, timestamp } = tokenPrices[address.toLowerCase()];
+        return { address, price, timestamp };
+      });
+  }
+
+  private validateResponse(response: unknown): response is DefiLlamaPriceResponse {
+    if (response === null || typeof response !== "object") return false;
+
+    const coins: unknown = (response as Record<string, unknown>).coins;
+    if (coins === null || typeof coins !== "object") return false;
+
+    return Object.entries(coins as object).every(([address, tokenPrice]) => {
+      // prettier-ignore
+      return (
+        /[a-z]+:0[xX][0-9a-fA-F]{40}/.exec(address) !== undefined
+        && typeof tokenPrice === "object"
+        && typeof tokenPrice.symbol === "string"
+        && !isNaN(tokenPrice.decimals)
+        && (tokenPrice.decimals > 0 && tokenPrice.decimals <= 18)
+        && !isNaN(tokenPrice.price)
+        && !isNaN(tokenPrice.timestamp)
+        && !isNaN(tokenPrice.confidence)
+      );
+    });
+  }
+}

package/src/priceClient/adapters/index.ts

@@ -0,0 +1,3 @@
+export * as acrossApi from "./acrossApi";
+export * as coingecko from "./coingecko";
+export * as defiLlama from "./defiLlama";

package/src/priceClient/index.ts

@@ -0,0 +1,2 @@
+export * from "./priceClient";
+export * as adapters from "./adapters";

package/src/priceClient/priceClient.ts

@@ -0,0 +1,192 @@
+import assert from "assert";
+import { CoinGeckoPrice } from "../coingecko";
+import { Logger } from "../relayFeeCalculator"; // @todo: Relocate Logger to utils?
+
+export { Logger }; // Permit adapters to import a common definition.
+export type TokenPrice = CoinGeckoPrice; // Temporary inversion; CoinGecko should source from here.
+
+// Represents valid source for spot prices (Across API, CoinGecko, ...)
+export interface PriceFeedAdapter {
+  readonly name: string;
+  getPriceByAddress(address: string, currency: string): Promise<TokenPrice>;
+  getPricesByAddress(addresses: string[], currency: string): Promise<TokenPrice[]>;
+}
+
+// It's convenient to map TokenPrice objects by their address, but consumers typically want an array
+// of TokenPrice objects, so the address must also be embedded within the TokenPrice object. To
+// avoid storing multiple copies of the same TokenPrice, always use the lower-case variant of the
+// address when performing a lookup into the PriceCache, and substitute the provided address into the
+// TokenPrice object when returning to the caller.
+export type PriceCache = {
+  [address: string]: TokenPrice;
+};
+
+export function msToS(ms: number): number {
+  return Math.floor(ms / 1000);
+}
+
+// PriceClient aggregates various user-configured price feeds/sources and retains them for a
+// configurable time period. External price lookups are performed according to an ordered list that
+// is supplied during instantiation. The PriceClient will iterate over the list until a complete set
+// of prices has been retrieved from a single source. External price lookups will opportunistically
+// request new prices for _all_ previously requested tokens. Price lookups into PriceClient will be
+// served out of its local cache if the token price is less than maxPriceAge seconds. This helps to
+// suppress external price lookups and can help to mitigate rate-limiting by external providers.
+// See README.md for further information and usage guidelines.
+export class PriceClient implements PriceFeedAdapter {
+  public readonly name: string = "PriceClient";
+  private _maxPriceAge = 300; // seconds
+  protected prices: {
+    [currency: string]: PriceCache;
+  } = {};
+
+  constructor(
+    protected logger: Logger,
+    readonly priceFeeds: PriceFeedAdapter[]
+  ) {
+    assert(logger, "No logging instance supplied.");
+    assert(priceFeeds.length > 0, "No price feeds supplied.");
+  }
+
+  get maxPriceAge(): number {
+    return this._maxPriceAge;
+  }
+
+  set maxPriceAge(age: number) {
+    assert(age >= 0);
+    this.logger.debug({
+      at: "PriceClient#maxPriceAge",
+      message: `Setting maxPriceAge (S) ${this._maxPriceAge} => ${age}.`,
+    });
+    this._maxPriceAge = age;
+  }
+
+  listPriceFeeds(): string[] {
+    return this.priceFeeds.map((priceFeed: PriceFeedAdapter) => priceFeed.name);
+  }
+
+  async getPriceByAddress(address: string, currency = "usd"): Promise<TokenPrice> {
+    const tokenPrices = await this.getPricesByAddress([address], currency);
+    return tokenPrices[0];
+  }
+
+  // note: Input addresses are *always* converted to lower case for storage as
+  // keys in the PriceClient cache. Adapters will therefore always receive
+  // addresses in lower case form.
+  async getPricesByAddress(addresses: string[], currency = "usd"): Promise<TokenPrice[]> {
+    assert(this.priceFeeds.length > 0, "No price feeds are registered.");
+    const priceCache = this.getPriceCache(currency);
+
+    // Determine whether each *requested* price is current.
+    const now = msToS(Date.now());
+    const missed: { [address: string]: number } = {};
+    addresses.forEach((address: string) => {
+      const addr = address.toLowerCase();
+      const tokenPrice = priceCache[addr] ?? ({ price: 0, timestamp: 0 } as TokenPrice);
+      priceCache[addr] = tokenPrice; // Update priceCache if necessary;
+
+      const age = now - tokenPrice.timestamp;
+      if (age > this.maxPriceAge) {
+        missed[address] = age;
+      }
+    });
+
+    if (Object.keys(missed).length > 0) {
+      this.logger.debug({
+        at: "PriceClient#getPricesByAddress",
+        message: `${currency.toUpperCase()} cache miss (age > ${this.maxPriceAge} S).`,
+        tokens: missed,
+      });
+      await this.updatePrices(currency);
+    }
+
+    return addresses.map((address: string) => {
+      const { price, timestamp } = priceCache[address.toLowerCase()];
+      return { address, price, timestamp };
+    });
+  }
+
+  expireCache(currency: string): void {
+    const priceCache = this.getPriceCache(currency);
+    Object.values(priceCache).forEach((token: TokenPrice) => (token.timestamp = 0));
+    this.logger.debug({ at: "PriceClient#expireCache", message: `Expired ${currency} cache.` });
+  }
+
+  protected getPriceCache(currency: string): PriceCache {
+    if (this.prices[currency] === undefined) this.prices[currency] = {};
+    return this.prices[currency];
+  }
+
+  private async updatePrices(currency: string): Promise<void> {
+    const priceCache = this.getPriceCache(currency);
+    let addresses = Object.keys(priceCache);
+
+    for (const priceFeed of this.priceFeeds) {
+      this.logger.debug({
+        at: "PriceClient#updatePrices",
+        message: `Looking up prices via ${priceFeed.name}.`,
+        tokens: addresses,
+      });
+      try {
+        const prices = await priceFeed.getPricesByAddress(addresses, currency);
+        addresses = await this.updateCache(priceCache, prices, addresses);
+        if (addresses.length === 0) break; // All done
+      } catch (err) {
+        this.logger.debug({
+          at: "PriceClient#updatePrices",
+          message: `Price lookup against ${priceFeed.name} failed (${err}).`,
+          tokens: addresses,
+        });
+        // Failover to the next price feed...
+      }
+    }
+
+    if (addresses.length !== 0) {
+      this.logger.debug({
+        at: "PriceClient#updatePrices",
+        message: "Unable to resolve some token prices.",
+        priceFeeds: this.listPriceFeeds(),
+        tokens: addresses,
+      });
+      throw new Error(`Price lookup failed against all price feeds (${this.listPriceFeeds().join(", ")})`);
+    }
+  }
+
+  private updateCache(priceCache: PriceCache, prices: TokenPrice[], expected: string[]): string[] {
+    const updated: TokenPrice[] = [];
+    const skipped: { [token: string]: string } = {}; // Includes reason for skipping
+    const now = msToS(Date.now());
+
+    expected.forEach((address: string) => {
+      const addr = address.toLowerCase(); // for internal priceCache lookup.
+      const tokenPrice: TokenPrice | undefined = prices.find((price) => price?.address?.toLowerCase() === addr);
+
+      if (tokenPrice === undefined) {
+        skipped[address] = "Not included in price feed response.";
+      } else if (tokenPrice.timestamp > now) {
+        skipped[address] = `Token price timestamp is too new (timestamp ${tokenPrice.timestamp}).`;
+      } else if (tokenPrice.timestamp >= priceCache[addr].timestamp) {
+        const { price, timestamp } = tokenPrice;
+        // Drop the address; we sub it in when returning to the caller.
+        // @todo: Do we care if the token price is older than maxPriceAge?
+        priceCache[addr] = { price, timestamp } as TokenPrice;
+        updated.push(tokenPrice);
+      } else if (tokenPrice.timestamp === priceCache[addr].timestamp) {
+        this.logger.debug({
+          at: "PriceClient#updateCache",
+          message: `No new price available for token ${address}.`,
+          token: tokenPrice,
+        });
+      }
+    });
+
+    this.logger.debug({
+      at: "PriceClient#updateCache",
+      message: `Updated ${updated.length ?? 0} price(s), skipped ${Object.keys(skipped).length ?? 0}.`,
+      updated,
+      skipped,
+    });
+
+    return Object.keys(skipped);
+  }
+}

package/src/relayFeeCalculator/README.md

@@ -0,0 +1,34 @@
+# Relay Fee Calculator
+
+Calculates relay fee percentages for a relay deposit.
+
+## Usage
+
+See tests for more documentation: [Relay Fee Calculator Test]("./relayFeeDetails.test.ts")
+
+```ts
+import * as across from "@across/sdk"
+import {ethers} from 'ethers'
+
+const {RelayFeeCalculator, DefaultQueries} = across.relayFeeCalculator
+
+const mainnetUsdcAddress = ethers.utils.getAddress("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48")
+
+// Relay fee calculator requires different queries depending on the chain, the default works with mainnet.
+const provider = ethers.getDefaultProvider(process.env.CUSTOM_NODE_URL);
+const queries = new DefaultQueries(provider)
+const client = new RelayFeeCalculator({queries})
+const result = await client.relayerFeeDetails(100000000,mainnetUsdcAddress)
+// result =
+// {
+//   amountToRelay: '100000000',
+//   relayFeePercent: '878173320000000000',
+//   relayFeeTotal: '87817332',
+//   discountPercent: 0,
+//   feeLimitPercent: 0,
+//   tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+//   isAmountTooLow: false
+// }
+
+```
+

package/src/relayFeeCalculator/chain-queries/baseQuery.ts

@@ -0,0 +1,98 @@
+import { L2Provider } from "@eth-optimism/sdk/dist/interfaces/l2-provider";
+import { providers } from "ethers";
+import { Coingecko } from "../../coingecko";
+import { CHAIN_IDs, DEFAULT_SIMULATED_RELAYER_ADDRESS } from "../../constants";
+import { Deposit } from "../../interfaces";
+import { SpokePool, SpokePool__factory } from "../../typechain";
+import {
+  BigNumberish,
+  TransactionCostEstimate,
+  estimateTotalGasRequiredByUnsignedTransaction,
+  populateV3Relay,
+} from "../../utils";
+import { Logger, QueryInterface } from "../relayFeeCalculator";
+
+type Provider = providers.Provider;
+type OptimismProvider = L2Provider<Provider>;
+type SymbolMappingType = Record<
+  string,
+  {
+    addresses: Record<number, string>;
+    decimals: number;
+  }
+>;
+
+/**
+ * A unified QueryBase for querying gas costs, token prices, and decimals of various tokens
+ * on a blockchain.
+ */
+export class QueryBase implements QueryInterface {
+  readonly spokePool: SpokePool;
+  /**
+   * Instantiates a QueryBase instance
+   * @param provider A valid Ethers.js provider
+   * @param symbolMapping A mapping to valid ERC20 tokens and their respective characteristics
+   * @param spokePoolAddress The valid address of the Spoke Pool deployment
+   * @param simulatedRelayerAddress The address that these queries will reference as the sender. Note: This address must be approved for USDC
+   * @param gasMarkup A multiplier that is applied to the total gas estimate
+   * @param logger A logging utility to report logs
+   * @param coingeckoProApiKey An optional CoinGecko API key that links to a PRO account
+   * @param fixedGasPrice Overrides the gas price with a fixed value. Note: primarily used for the Boba blockchain
+   * @param coingeckoBaseCurrency The basis currency that CoinGecko will use to resolve pricing
+   */
+  constructor(
+    readonly provider: Provider | OptimismProvider,
+    readonly symbolMapping: SymbolMappingType,
+    readonly spokePoolAddress: string,
+    readonly simulatedRelayerAddress: string,
+    readonly gasMarkup: number,
+    readonly logger: Logger,
+    readonly coingeckoProApiKey?: string,
+    readonly fixedGasPrice?: BigNumberish,
+    readonly coingeckoBaseCurrency: string = "eth"
+  ) {
+    this.spokePool = SpokePool__factory.connect(spokePoolAddress, provider);
+  }
+
+  /**
+   * Retrieves the current gas costs of performing a fillRelay contract at the referenced SpokePool.
+   * @param deposit V3 deposit instance.
+   * @param relayerAddress Relayer address to simulate with.
+   * @returns The gas estimate for this function call (multplied with the optional buffer).
+   */
+  async getGasCosts(deposit: Deposit, relayer = DEFAULT_SIMULATED_RELAYER_ADDRESS): Promise<TransactionCostEstimate> {
+    const tx = await populateV3Relay(this.spokePool, deposit, relayer);
+    return estimateTotalGasRequiredByUnsignedTransaction(
+      tx,
+      relayer,
+      this.provider,
+      this.gasMarkup,
+      this.fixedGasPrice
+    );
+  }
+
+  /**
+   * Retrieves the current price of a token
+   * @param tokenSymbol A valid [CoinGecko-ID](https://api.coingecko.com/api/v3/coins/list)
+   * @returns The resolved token price within the specified coingeckoBaseCurrency
+   */
+  async getTokenPrice(tokenSymbol: string): Promise<number> {
+    if (!this.symbolMapping[tokenSymbol]) throw new Error(`${tokenSymbol} does not exist in mapping`);
+    const coingeckoInstance = Coingecko.get(this.logger, this.coingeckoProApiKey);
+    const [, price] = await coingeckoInstance.getCurrentPriceByContract(
+      this.symbolMapping[tokenSymbol].addresses[CHAIN_IDs.MAINNET],
+      this.coingeckoBaseCurrency
+    );
+    return price;
+  }
+
+  /**
+   * Resolves the number of decimal places a token can have
+   * @param tokenSymbol A valid Across-Enabled Token ID
+   * @returns The number of decimals of precision for the corresponding tokenSymbol
+   */
+  getTokenDecimals(tokenSymbol: string): number {
+    if (!this.symbolMapping[tokenSymbol]) throw new Error(`${tokenSymbol} does not exist in mapping`);
+    return this.symbolMapping[tokenSymbol].decimals;
+  }
+}