bump

package.json

@@ -113,4 +113,4 @@
   "overrides": {
     "tsconfig-paths": "^4.0.0"
   }
-}
+}

src/Unit/Exchange/generateSwapCalldata.ts

@@ -0,0 +1,315 @@
+import type { ExchangeWithGenericSwap } from '@orionprotocol/contracts/lib/ethers-v5/Exchange.js';
+import { UniswapV3Pool__factory, ERC20__factory, SwapExecutor__factory, CurveRegistry__factory } from '@orionprotocol/contracts/lib/ethers-v5/index.js';
+import { BigNumber, ethers, type BigNumberish } from 'ethers';
+import { concat, defaultAbiCoder, type BytesLike } from 'ethers/lib/utils.js';
+import { safeGet, SafeArray } from '../../utils/safeGetters.js';
+import type Unit from '../index.js';
+import { simpleFetch } from 'simple-typed-fetch';
+import type { PromiseOrValue } from '@orionprotocol/contracts/lib/ethers-v5/common.js';
+
+const EXECUTOR_SWAP_FUNCTION = "func_70LYiww"
+
+export type Factory = "UniswapV2" | "UniswapV3" | "Curve" | "OrionV2" | "OrionV3"
+
+const exchangeToType: Partial<Record<string, Factory>> = {
+  'SPOOKYSWAP': 'UniswapV2',
+  'PANCAKESWAP': 'UniswapV2',
+  'UNISWAP': 'UniswapV2',
+  'QUICKSWAP': 'UniswapV2',
+  'ORION_POOL': 'UniswapV2',
+  'CHERRYSWAP': 'UniswapV2',
+  'OKXSWAP': 'UniswapV2',
+  'INTERNAL_POOL_V2': 'UniswapV2',
+  'INTERNAL_POOL_V3': "OrionV3",
+  'INTERNAL_POOL_V3_0_01': "OrionV3",
+  'INTERNAL_POOL_V3_0_05': "OrionV3",
+  'INTERNAL_POOL_V3_0_3': "OrionV3",
+  'INTERNAL_POOL_V3_1_0': "OrionV3",
+  'CURVE': "Curve",
+  'CURVE_FACTORY': "Curve",
+}
+
+export type SwapInfo = {
+  pool: string,
+  assetIn: string,
+  assetOut: string,
+  factory: string
+}
+
+export type CallParams = {
+  isMandatory?: boolean,
+  target?: string,
+  gaslimit?: BigNumber,
+  value?: BigNumber
+}
+
+export type GenerateSwapCalldataParams = {
+  amount: BigNumberish,
+  minReturnAmount: BigNumberish,
+  receiverAddress: string,
+  path: ArrayLike<SwapInfo>,
+  unit: Unit
+}
+
+export default async function generateSwapCalldata({
+  amount,
+  minReturnAmount,
+  receiverAddress,
+  path: path_,
+  unit
+}: GenerateSwapCalldataParams
+): Promise<{ calldata: string, swapDescription: ExchangeWithGenericSwap.SwapDescriptionStruct }> {
+  if (path_ == undefined || path_.length == 0) {
+    throw new Error(`Empty path`);
+  }
+  const wethAddress = safeGet(unit.contracts, "WETH")
+  const curveRegistryAddress = safeGet(unit.contracts, "curveRegistry")
+  const {assetToAddress, swapExecutorContractAddress, exchangeContractAddress} = await simpleFetch(unit.blockchainService.getInfo)();
+  let path = SafeArray.from(path_).map((swapInfo) => {
+    swapInfo.assetIn = safeGet(assetToAddress, swapInfo.assetIn);
+    swapInfo.assetOut = safeGet(assetToAddress, swapInfo.assetOut);
+    return swapInfo; 
+  })
+  const factory = path.first().factory
+  if (!path.every(swapInfo => swapInfo.factory === factory)) {
+    throw new Error(`Supporting only swaps with single factory`);
+  }
+  
+  const swapDescription: ExchangeWithGenericSwap.SwapDescriptionStruct = {
+    srcToken: path.first().assetIn,
+    dstToken: path.last().assetOut,
+    srcReceiver: swapExecutorContractAddress,
+    dstReceiver: receiverAddress,
+    amount: amount,
+    minReturnAmount: minReturnAmount,
+    flags: 0
+  }
+
+  const exchangeToNativeDecimals = async (token: PromiseOrValue<string>) => {
+    token = await token
+    let decimals = 18
+    if (token !== ethers.constants.AddressZero) {
+      const contract = ERC20__factory.connect(token, unit.provider)
+      decimals = await contract.decimals()
+    }
+    return BigNumber.from(amount).mul(BigNumber.from(10).pow(decimals)).div(BigNumber.from(10).pow(8))
+  }
+  const amountNativeDecimals = await exchangeToNativeDecimals(swapDescription.srcToken);
+
+  path = SafeArray.from(path_).map((swapInfo) => {
+    if (swapInfo.assetIn == ethers.constants.AddressZero) swapInfo.assetIn = wethAddress
+    if (swapInfo.assetOut == ethers.constants.AddressZero) swapInfo.assetOut = wethAddress
+    return swapInfo;
+  });
+  
+
+  let calldata: string
+  switch (exchangeToType[factory]) {
+    case "OrionV2": {
+      swapDescription.srcReceiver = path.first().pool
+      calldata = await generateUni2Calls(exchangeContractAddress, path);
+      break;
+    }
+    case "UniswapV2": {
+      swapDescription.srcReceiver = path.first().pool
+      calldata = await generateUni2Calls(exchangeContractAddress, path);
+      break;
+    }
+    case "UniswapV3": {
+      calldata = await generateUni3Calls(amountNativeDecimals, exchangeContractAddress, path, unit.provider)
+      break;
+    }
+    case "OrionV3": {
+      calldata = await generateOrion3Calls(amountNativeDecimals, exchangeContractAddress, path, unit.provider)
+      break;
+    }
+    case "Curve": {
+      calldata = await generateCurveStableSwapCalls(
+        amountNativeDecimals,
+        exchangeContractAddress,
+        swapExecutorContractAddress,
+        path,
+        unit.provider,
+        curveRegistryAddress
+      );
+      break;
+    }
+    default: {
+      throw new Error(`Factory ${factory} is not supported`)
+    }
+  }
+  return { swapDescription, calldata }
+}
+
+export async function generateUni2Calls(
+  exchangeAddress: string,
+  path: SafeArray<SwapInfo>
+) {
+  const executorInterface = SwapExecutor__factory.createInterface()
+  const calls: BytesLike[] = []
+  if (path.length > 1) {
+    for (let i = 0; i < path.length - 1; ++i) {
+      const currentSwap = path.get(i)
+      const nextSwap = path.get(i + 1)
+
+      const calldata = executorInterface.encodeFunctionData("swapUniV2", [
+        currentSwap.pool,
+        currentSwap.assetIn,
+        currentSwap.assetOut,
+        defaultAbiCoder.encode(["uint256"], [concat(["0x03", nextSwap.pool])]),
+      ]
+      )
+      calls.push(addCallParams(calldata))
+    }
+  }
+  const lastSwap = path.last();
+  const calldata = executorInterface.encodeFunctionData("swapUniV2", [
+    lastSwap.pool,
+    lastSwap.assetIn,
+    lastSwap.assetOut,
+    defaultAbiCoder.encode(["uint256"], [concat(["0x03", exchangeAddress])]),
+  ])
+  calls.push(addCallParams(calldata))
+
+  return generateCalls(calls)
+}
+
+async function generateUni3Calls(
+  amount: BigNumberish,
+  exchangeContractAddress: string,
+  path: SafeArray<SwapInfo>,
+  provider: ethers.providers.JsonRpcProvider
+) {
+  const encodedPools: BytesLike[] = []
+  for (const swap of path) {
+    const pool = UniswapV3Pool__factory.connect(swap.pool, provider)
+    const token0 = await pool.token0()
+    const zeroForOne = token0.toLowerCase() === swap.assetIn.toLowerCase()
+    const unwrapWETH = swap.assetOut === ethers.constants.AddressZero
+
+    let encodedPool = ethers.utils.solidityPack(["uint256"], [pool.address])
+    encodedPool = ethers.utils.hexDataSlice(encodedPool, 1)
+    let firstByte = 0
+    if (unwrapWETH) firstByte += 32
+    if (!zeroForOne) firstByte += 128
+    const encodedFirstByte = ethers.utils.solidityPack(["uint8"], [firstByte])
+    encodedPool = ethers.utils.hexlify(ethers.utils.concat([encodedFirstByte, encodedPool]))
+    encodedPools.push(encodedPool)
+  }
+  const executorInterface = SwapExecutor__factory.createInterface()
+  let calldata = executorInterface.encodeFunctionData("uniswapV3SwapTo", [encodedPools, exchangeContractAddress, amount])
+  calldata = addCallParams(calldata)
+
+  return generateCalls([calldata])
+}
+
+async function generateOrion3Calls(
+  amount: BigNumberish,
+  exchangeContractAddress: string,
+  path: SafeArray<SwapInfo>,
+  provider: ethers.providers.JsonRpcProvider
+) {
+  const encodedPools: BytesLike[] = []
+  for (const swap of path) {
+    const pool = UniswapV3Pool__factory.connect(swap.pool, provider)
+    const token0 = await pool.token0()
+    const zeroForOne = token0.toLowerCase() === swap.assetIn.toLowerCase()
+    const unwrapWETH = swap.assetOut === ethers.constants.AddressZero
+
+    let encodedPool = ethers.utils.solidityPack(["uint256"], [pool.address])
+    encodedPool = ethers.utils.hexDataSlice(encodedPool, 1)
+    let firstByte = 0
+    if (unwrapWETH) firstByte += 32
+    if (!zeroForOne) firstByte += 128
+    const encodedFirstByte = ethers.utils.solidityPack(["uint8"], [firstByte])
+    encodedPool = ethers.utils.hexlify(ethers.utils.concat([encodedFirstByte, encodedPool]))
+    encodedPools.push(encodedPool)
+  }
+  const executorInterface = SwapExecutor__factory.createInterface()
+  let calldata = executorInterface.encodeFunctionData("orionV3SwapTo", [encodedPools, exchangeContractAddress, amount])
+  calldata = addCallParams(calldata)
+
+  return generateCalls([calldata])
+}
+
+async function generateCurveStableSwapCalls(
+  amount: BigNumberish,
+  exchangeContractAddress: string,
+  executorAddress: string,
+  path: SafeArray<SwapInfo>,
+  provider: ethers.providers.JsonRpcProvider,
+  curveRegistry: string
+) {
+  if (path.length > 1) {
+    throw new Error("Supporting only single stable swap on curve")
+  }
+  const executorInterface = SwapExecutor__factory.createInterface()
+  const registry = CurveRegistry__factory.connect(curveRegistry, provider)
+
+  const swap = path.first()
+  const firstToken = ERC20__factory.connect(swap.assetIn, provider)
+  const { pool, assetIn, assetOut } = swap
+  const [i, j,] = await registry.get_coin_indices(pool, assetIn, assetOut)
+
+  const executorAllowance = await firstToken.allowance(executorAddress, swap.pool)
+  const calls: BytesLike[] = []
+  if (executorAllowance.lt(amount)) {
+    const calldata = addCallParams(
+      executorInterface.encodeFunctionData("safeApprove", [
+        swap.assetIn,
+        swap.pool,
+        ethers.constants.MaxUint256
+      ])
+    )
+    calls.push(calldata)
+  }
+  let calldata = executorInterface.encodeFunctionData("curveSwapStableAmountIn", [
+    pool,
+    assetOut,
+    i,
+    j,
+    amount,
+    0,
+    exchangeContractAddress])
+
+  calldata = addCallParams(calldata)
+  calls.push(calldata)
+
+  return generateCalls(calls)
+}
+
+// Adds additional byte to single swap with settings
+function addCallParams(
+  calldata: BytesLike,
+  callParams?: CallParams
+) {
+  let firstByte = 0
+  if (callParams) {
+    if (callParams.value !== undefined) { 
+      firstByte += 16 // 00010000
+      const encodedValue = ethers.utils.solidityPack(["uint128"], [callParams.value])
+      calldata = ethers.utils.hexlify(ethers.utils.concat([encodedValue, calldata]))
+    }
+    if (callParams.target !== undefined) {
+      firstByte += 32 // 00100000
+      const encodedAddress = ethers.utils.solidityPack(["address"], [callParams.target])
+      calldata = ethers.utils.hexlify(ethers.utils.concat([encodedAddress, calldata]))
+    }
+    if (callParams.gaslimit !== undefined) {
+      firstByte += 64 // 01000000
+      const encodedGaslimit = ethers.utils.solidityPack(["uint32"], [callParams.gaslimit])
+      calldata = ethers.utils.hexlify(ethers.utils.concat([encodedGaslimit, calldata]))
+    }
+    if (callParams.isMandatory !== undefined) firstByte += 128 // 10000000
+  }
+
+  const encodedFirstByte = ethers.utils.solidityPack(["uint8"], [firstByte])
+  calldata = ethers.utils.hexlify(ethers.utils.concat([encodedFirstByte, calldata]))
+  return calldata
+}
+
+
+async function generateCalls(calls: BytesLike[]) {
+  const executorInterface = SwapExecutor__factory.createInterface()
+  return "0x" + executorInterface.encodeFunctionData(EXECUTOR_SWAP_FUNCTION, [ethers.constants.AddressZero, calls]).slice(74)
+}

src/Unit/Exchange/index.ts

@@ -1,8 +1,8 @@
 import type Unit from '../index.js';
 import deposit, { type DepositParams } from './deposit.js';
 import getSwapInfo, { type GetSwapInfoParams } from './getSwapInfo.js';
-import type { SwapLimitParams } from './swapLimit.js';
-import swapLimit from './swapLimit.js';
+import generateSwapCalldata, { type GenerateSwapCalldataParams } from './generateSwapCalldata.js';
+import swapLimit, {type SwapLimitParams} from './swapLimit.js';
 import swapMarket, { type SwapMarketParams } from './swapMarket.js';
 import withdraw, { type WithdrawParams } from './withdraw.js';
 
@@ -11,6 +11,7 @@ type PureSwapLimitParams = Omit<SwapLimitParams, 'unit'>
 type PureDepositParams = Omit<DepositParams, 'unit'>
 type PureWithdrawParams = Omit<WithdrawParams, 'unit'>
 type PureGetSwapMarketInfoParams = Omit<GetSwapInfoParams, 'blockchainService' | 'aggregator'>
+type PureGenerateSwapCalldataParams = Omit<GenerateSwapCalldataParams, 'unit'>
 
 export default class Exchange {
   private readonly unit: Unit;
@@ -54,4 +55,11 @@ export default class Exchange {
       unit: this.unit,
     });
   }
+
+  public generateSwapCalldata(params: PureGenerateSwapCalldataParams) {
+    return generateSwapCalldata({
+      ...params,
+      unit: this.unit
+    })
+  }
 }

src/Unit/index.ts

@@ -32,6 +32,8 @@ export default class Unit {
 
   public readonly config: VerboseUnitConfig;
 
+  public readonly contracts: Record<string, string>;
+
   constructor(config: KnownConfig | VerboseUnitConfig) {
     if ('env' in config) {
       const staticConfig = envs[config.env];
@@ -42,7 +44,6 @@ export default class Unit {
 
       const networkConfig = staticConfig.networks[config.chainId];
       if (!networkConfig) throw new Error(`Invalid chainId: ${config.chainId}. Available chainIds: ${Object.keys(staticConfig.networks).join(', ')}`);
-
       this.config = {
         chainId: config.chainId,
         nodeJsonRpc: networkConfig.rpc ?? chainConfig.rpc,
@@ -64,9 +65,10 @@ export default class Unit {
     }
     const chainInfo = chains[config.chainId];
     if (!chainInfo) throw new Error('Chain info is required');
-
+    
     this.chainId = config.chainId;
     this.networkCode = chainInfo.code;
+    this.contracts = chainInfo.contracts
     const intNetwork = parseInt(this.chainId, 10);
     if (Number.isNaN(intNetwork)) throw new Error('Invalid chainId (not a number)' + this.chainId);
     this.provider = new ethers.providers.StaticJsonRpcProvider(this.config.nodeJsonRpc, intNetwork);

src/config/chains.json

@@ -6,7 +6,11 @@
     "shortName": "ETH",
     "code": "eth",
     "rpc": "https://trade.orionprotocol.io/eth-mainnet/rpc",
-    "baseCurrencyName": "ETH"
+    "baseCurrencyName": "ETH",
+    "contracts": {
+      "WETH": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+      "curveRegistry": "0x90E00ACe148ca3b23Ac1bC8C240C2a7Dd9c2d7f5"
+    }
   },
   "56": {
     "chainId": "56",
@@ -15,7 +19,11 @@
     "shortName": "BSC",
     "code": "bsc",
     "rpc": "https://bsc-dataseed.binance.org/",
-    "baseCurrencyName": "BNB"
+    "baseCurrencyName": "BNB",
+    "contracts": {
+      "WETH": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
+      "curveRegistry": ""
+    }
   },
   "97": {
     "chainId": "97",
@@ -24,7 +32,24 @@
     "shortName": "BSC-Testnet",
     "code": "bsc",
     "rpc": "https://data-seed-prebsc-1-s1.bnbchain.org:8545/",
-    "baseCurrencyName": "BNB"
+    "baseCurrencyName": "BNB",
+    "contracts": {
+      "WETH": "0x23eE96bEaAB62abE126AA192e677c52bB7d274F0",
+      "curveRegistry": "0x8845b36C3DE93379F468590FFa102D4aF8C49A6c"
+    }
+  },
+  "3": {
+    "chainId": "3",
+    "explorer": "https://ropsten.etherscan.io/",
+    "label": "Ropsten",
+    "shortName": "ETH-Ropsten",
+    "code": "eth",
+    "rpc": "https://testing.orionprotocol.io/eth-ropsten/rpc",
+    "baseCurrencyName": "ETH",
+    "contracts": {
+      "WETH": "",
+      "curveRegistry": ""
+    }
   },
   "5": {
     "chainId": "5",
@@ -33,7 +58,11 @@
     "shortName": "ETH-Goerli",
     "code": "eth",
     "rpc": "https://testing.orionprotocol.io/eth-goerli/rpc",
-    "baseCurrencyName": "ETH"
+    "baseCurrencyName": "ETH",
+    "contracts": {
+      "WETH": "",
+      "curveRegistry": ""
+    }
   },
   "421613": {
     "chainId": "421613",
@@ -42,7 +71,11 @@
     "shortName": "Arbitrum Goerli",
     "code": "arb",
     "rpc": "https://goerli-rollup.arbitrum.io/rpc",
-    "baseCurrencyName": "ETH"
+    "baseCurrencyName": "ETH",
+    "contracts": {
+      "WETH": "",
+      "curveRegistry": ""
+    }
   },
   "4002": {
     "chainId": "4002",
@@ -51,7 +84,11 @@
     "shortName": "FTM-Testnet",
     "code": "ftm",
     "rpc": "https://rpc.testnet.fantom.network/",
-    "baseCurrencyName": "FTM"
+    "baseCurrencyName": "FTM",
+    "contracts": {
+      "WETH": "",
+      "curveRegistry": ""
+    }
   },
   "250": {
     "chainId": "250",
@@ -60,7 +97,11 @@
     "shortName": "FTM",
     "code": "ftm",
     "rpc": "https://rpcapi.fantom.network/",
-    "baseCurrencyName": "FTM"
+    "baseCurrencyName": "FTM",
+    "contracts": {
+      "WETH": "",
+      "curveRegistry": ""
+    }
   },
   "137": {
     "chainId": "137",
@@ -69,7 +110,11 @@
     "code": "polygon",
     "baseCurrencyName": "MATIC",
     "rpc": "https://polygon-rpc.com/",
-    "explorer": "https://polygonscan.com/"
+    "explorer": "https://polygonscan.com/",
+    "contracts": {
+      "WETH": "",
+      "curveRegistry": ""
+    }
   },
   "80001": {
     "chainId": "80001",
@@ -78,7 +123,11 @@
     "code": "polygon",
     "baseCurrencyName": "MATIC",
     "rpc": "https://rpc-mumbai.matic.today",
-    "explorer": "https://mumbai.polygonscan.com/"
+    "explorer": "https://mumbai.polygonscan.com/",
+    "contracts": {
+      "WETH": "",
+      "curveRegistry": ""
+    }
   },
   "66": {
     "chainId": "66",
@@ -87,7 +136,11 @@
     "shortName": "OKC",
     "code": "okc",
     "rpc": "https://exchainrpc.okex.org/",
-    "baseCurrencyName": "OKT"
+    "baseCurrencyName": "OKT",
+    "contracts": {
+      "WETH": "",
+      "curveRegistry": ""
+    }
   },
   "65": {
     "chainId": "65",
@@ -96,7 +149,11 @@
     "shortName": "OKC-Testnet",
     "code": "okc",
     "rpc": "https://exchaintestrpc.okex.org/",
-    "baseCurrencyName": "OKT"
+    "baseCurrencyName": "OKT",
+    "contracts": {
+      "WETH": "",
+      "curveRegistry": ""
+    }
   },
   "56303": {
     "chainId": "56303",
@@ -105,6 +162,10 @@
     "code": "drip",
     "baseCurrencyName": "DRIP",
     "rpc": "testnet.1d.rip",
-    "explorer": "https://explorer-testnet.1d.rip/"
+    "explorer": "https://explorer-testnet.1d.rip/",
+    "contracts": {
+      "WETH": "",
+      "curveRegistry": ""
+    }
   }
 }

src/config/schemas/pureChainSchema.ts

@@ -10,6 +10,7 @@ export const pureChainInfoPayloadSchema = z.object({
   explorer: z.string(),
   rpc: z.string(),
   baseCurrencyName: z.string(),
+  contracts: z.record(z.string(), z.string())
 });
 
 export const pureChainInfoSchema = z.record(

src/services/Aggregator/ws/index.ts

@@ -503,6 +503,12 @@ class AggregatorWS {
             minAmountIn: json.ma,
             path: json.ps,
             exchanges: json.e,
+            exchangeContractPath: json.eps.map((path) => ({
+              pool: path.p,
+              assetIn: path.ai,
+              assetOut: path.ao,
+              factory: path.f,
+            })),
             poolOptimal: json.po,
             ...(json.oi) && {
               orderInfo: {

src/services/Aggregator/ws/schemas/swapInfoSchema.ts

@@ -33,6 +33,12 @@ const swapInfoSchemaBase = baseMessageSchema.extend({
   }).optional(),
   as: alternativeSchema.array(),
   anm: z.record(z.string()).optional(), // address to ERC20 names
+  eps: z.array(z.object({
+    p: z.string(), // pool address
+    ai: z.string().toUpperCase(), // asset in
+    ao: z.string().toUpperCase(), // asset out
+    f: z.string().toUpperCase(), // factory
+  }))
 });
 
 const swapInfoSchemaByAmountIn = swapInfoSchemaBase.extend({

src/services/BlockchainService/schemas/infoSchema.ts

@@ -11,6 +11,7 @@ const infoSchema = z.object({
   chainId: z.number(),
   chainName: z.string(),
   exchangeContractAddress: z.string(),
+  swapExecutorContractAddress: z.string(),
   oracleContractAddress: z.string(),
   matcherAddress: z.string(),
   orderFeePercent: z.number(),

src/types.ts

@@ -165,6 +165,13 @@ export type SwapInfoAlternative = {
   availableAmountOut?: number | undefined
 }
 
+type ExchangeContractPath = {
+  pool: string
+  assetIn: string
+  assetOut: string
+  factory: string
+}
+
 export type SwapInfoBase = {
   swapRequestId: string
   assetIn: string
@@ -175,6 +182,7 @@ export type SwapInfoBase = {
   minAmountOut: number
 
   path: string[]
+  exchangeContractPath: ExchangeContractPath[]
   exchanges?: string[] | undefined
   poolOptimal: boolean
 

src/utils/safeGetters.ts

@@ -0,0 +1,60 @@
+export class SafeArray<T> extends Array<T> {
+  
+  public static override from<T>(array: ArrayLike<T>): SafeArray<T> {
+    return new SafeArray(array);
+  }
+
+  constructor(array: ArrayLike<T>) {
+    super(array.length);
+    for (const index in array) {
+      const value = array[index]
+      if (value === undefined) {
+        throw new Error("Array passed to constructor has undefined values")
+      }
+      this[index] = value
+    }
+  }
+
+  public toArray(): T[] {
+    return [...this];
+  }
+
+  public override map<U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any): SafeArray<U> {
+    return new SafeArray(super.map(callbackfn, thisArg));
+  }
+
+  public override filter(callbackfn: (value: T, index: number, array: T[]) => boolean, thisArg?: any): SafeArray<T> {
+    return new SafeArray(super.filter(callbackfn, thisArg));
+  }
+
+  public get<T>(this: SafeArray<T>, index: number): T {
+    const value = this.at(index);
+    if (value === undefined) {
+      throw new Error(`Element at index ${index} is undefined.`)
+    }
+    return value
+  }
+
+  public last<T>(this: SafeArray<T>): T {
+    return this.get(this.length - 1)
+  }
+
+  public first<T>(this: SafeArray<T>): T {
+    return this.get(0)
+  }
+}
+
+export function safeGet<V>(obj: Partial<Record<string, V>>, key: string, errorMessage?: string) {
+  const value = obj[key];
+  if (value === undefined) throw new Error(`Key '${key.toString()}' not found in object. Available keys: ${Object.keys(obj).join(', ')}.${errorMessage ? ` ${errorMessage}` : ''}`);
+  return value;
+}
+
+const prefix = 'Requirement not met';
+
+export function must(condition: unknown, message?: string | (() => string)): asserts condition {
+    if (condition) return;
+    const provided = typeof message === 'function' ? message() : message;
+    const value = provided ? `${prefix}: ${provided}` : prefix;
+    throw new Error(value);
+}