{"id":21221810,"url":"https://github.com/primitivefinance/rmm-ethers","last_synced_at":"2025-08-22T05:06:48.344Z","repository":{"id":38172791,"uuid":"443182572","full_name":"primitivefinance/rmm-ethers","owner":"primitivefinance","description":"Library for interacting with RMM protocol through ethers.js.","archived":false,"fork":false,"pushed_at":"2023-02-04T08:50:02.000Z","size":3049,"stargazers_count":15,"open_issues_count":11,"forks_count":3,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-08-16T12:43:23.324Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/primitivefinance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-12-30T20:53:25.000Z","updated_at":"2023-11-18T07:22:29.000Z","dependencies_parsed_at":"2023-02-18T15:00:29.689Z","dependency_job_id":null,"html_url":"https://github.com/primitivefinance/rmm-ethers","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":"amanusk/hardhat-template","purl":"pkg:github/primitivefinance/rmm-ethers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primitivefinance%2Frmm-ethers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primitivefinance%2Frmm-ethers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primitivefinance%2Frmm-ethers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primitivefinance%2Frmm-ethers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/primitivefinance","download_url":"https://codeload.github.com/primitivefinance/rmm-ethers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primitivefinance%2Frmm-ethers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271588743,"owners_count":24785751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-22T02:00:08.480Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-20T22:33:56.791Z","updated_at":"2025-08-22T05:06:48.320Z","avatar_url":"https://github.com/primitivefinance.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🍄 rmm-ethers\n\n![version](https://img.shields.io/npm/v/@primitivefi/rmm-ethers) ![npm](https://img.shields.io/npm/dt/@primitivefi/rmm-ethers) ![license](https://img.shields.io/npm/l/@primitivefi/rmm-ethers) ![stars](https://img.shields.io/github/stars/primitivefinance/rmm-ethers?style=social\u0026color=%23FFB31A)\n\n\u003e Easily connect and transact with RMM protocol.\n\n## 🧩 Features\n\n- 🌲 Deploy RMM protocol\n- ⚡️ Easily connect to an RMM deployment\n- 🌊 Create RMM pools\n- ☄️ Allocate or remove liquidity\n- 🎁 Transfer positions\n- 🔭 Read protocol data\n\n## 📦 Installation\n\n\u003e This software is in Alpha.\n\nInstalling locally:\n\n```bash\n# Clone the repository\ngit clone https://github.com/primitivefinance/rmm-ethers.git\n\n# Install dependencies\nyarn install\n```\n\nInstalling as a package:\n\n```bash\n# Using yarn\nyarn add @primitivefi/rmm-ethers\n\n# Or using npm\nnpm i @primitivefi/rmm-ethers\n```\n\nUse it by connecting with a signer or provider:\n\n```typescript\n// Import the EthersRmm class\nimport { EthersRmm } from '@primitivefi/rmm-ethers'\n\n// Use the class by connecting to a deployment\nawait EthersRmm.connect(signerOrProvider)\n```\n\n## ✏️ Usage as a Package\n\nThis package is designed to extend the [rmm-sdk](https://github.com/primitivefinance/rmm-sdk) package. The SDK has the entity models and interfaces that are used by rmm-ethers to send transactions.\n\n### 🪝 As a react hook:\n\nHere is an example of a React hook that makes use of web3-react and SWR:\n\n```typescript\nimport useSWR, { SWRResponse } from 'swr'\nimport { useWeb3React } from 'web3-react'\nimport { Signer } from '@ethersproject/abstract-signer'\nimport { EthersRmm } from '@primitivefi/rmm-ethers'\n\nfunction getEthersRmm(signerOrProvider: Signer | Provider): () =\u003e Promise\u003cEthersRmm\u003e {\n  return async () =\u003e await EthersRmm.connect(signerOrProvider)\n}\n\n/**\n * Connects to EthersRmm deployment from the connected provider or signer.\n */\nexport function useRmmProtocol(suspense = false): SWRResponse\u003cEthersRmm, Error\u003e {\n  const { library: signerOrProvider, chainId } = useWeb3React()\n  const shouldFetch = !!signerOrProvider \u0026\u0026 typeof chainId !== 'undefined'\n  const result = useSWR(\n    shouldFetch ? [signerOrProvider, 'ethers-rmm', chainId] : null,\n    getEthersRmm(signerOrProvider?.getSigner() as Signer),\n    {\n      dedupingInterval: 60 * 1000,\n      refreshInterval: 60 * 1000,\n      suspense,\n    },\n  )\n\n  return result\n}\n```\n\n### 🌊 Fetch a pool\n\n```typescript\nimport { Pool } from '@primitivefi/rmm-sdk'\nimport { EthersRmm, Position } from '@primitivefi/rmm-ethers'\n\nasync function getPool(poolId: string): Promise\u003cPool\u003e {\n  return rmm.getPool(poolId).then(data =\u003e data)\n}\n```\n\n### ⚱️ Fetching pool liquidity positions\n\n```typescript\nimport { Pool } from '@primitivefi/rmm-sdk'\nimport { EthersRmm, Position } from '@primitivefi/rmm-ethers'\n\nasync function getPoolPosition(pool: Pool, account: string): Promise\u003cPosition\u003e {\n  return rmm.getPosition(pool, account).then(data =\u003e data)\n}\n```\n\n## Adjusting Positions\n\nWhen allocating or removing liquidity, the arguments must match the respective interfaces, which live in the [rmm-sdk](https://github.com/primitivefinance/rmm-sdk):\n\n```typescript\n/** Flag to use a native currency in a transaction.  */\nexport interface NativeOptions {\n  useNative?: NativeCurrency\n}\n\n/** Recipient address of any tokens which are output from transactions. */\nexport interface RecipientOptions {\n  recipient: string\n}\n\n/** Timestamp which will revert the transaction if not yet mined. */\nexport interface Deadline {\n  deadline?: BigNumber\n}\n\n/** Permit details on either risky or stable tokens. */\nexport interface PermitTokens {\n  /** If defined, risky token can be permitted, saving the user an approve tx. */\n  permitRisky?: PermitOptions\n\n  /** If defined, stable token can be permitted, saving the user an approve tx. */\n  permitStable?: PermitOptions\n}\n\n/** Token amounts to use for depositing or withdrawing into a margin account.  */\nexport interface MarginOptions extends PermitTokens, RecipientOptions, NativeOptions {\n  amountRisky: Wei\n  amountStable: Wei\n}\n\n/** Token amounts to use for allocating liquidity. */\nexport interface LiquidityOptions {\n  /** Amount of risky tokens to provide as liquidity. */\n  delRisky: Wei\n  /** Amount of stable tokens to provide as Liquidity. */\n  delStable: Wei\n  /** Desired liquidity to mint. */\n  delLiquidity: Wei\n}\n\n/** Provide liquidity argument details. */\nexport interface AllocateOptions extends PermitTokens, LiquidityOptions, RecipientOptions, NativeOptions, Deadline {\n  fromMargin: boolean\n  slippageTolerance: Percentage\n  createPool?: boolean\n}\n\n/** Remove liquidity argument details. */\nexport interface RemoveOptions extends LiquidityOptions, RecipientOptions, NativeOptions, Deadline {\n  expectedRisky: Wei\n  expectedStable: Wei\n  toMargin: boolean\n  slippageTolerance: Percentage\n}\n```\n\n### 🕳️ Allocating liquidity\n\n```typescript\nimport { Pool, AllocateOptions } from '@primitivefi/rmm-sdk'\nimport { EthersRmm, PositionAdjustmentDetails } from '@primitivefi/rmm-ethers'\n\nasync function onAllocate(rmm: EthersRmm, pool: Pool, options: AllocateOptions): Promise\u003cPositionAdjustmentDetails\u003e {\n  return rmm.allocate({ pool, options }).then(data =\u003e data)\n}\n```\n\n### 💎 Removing liquidity\n\n```typescript\nimport { Pool, AllocateOptions } from '@primitivefi/rmm-sdk'\nimport { EthersRmm, PositionAdjustmentDetails } from '@primitivefi/rmm-ethers'\n\nasync function onRemove(rmm: EthersRmm, pool: Pool, options: RemoveOptions): Promise\u003cPositionAdjustmentDetails\u003e {\n  return rmm.remove({ pool, options }).then(data =\u003e data)\n}\n```\n\n## 🧮 Usage locally\n\nBefore running any command, make sure to install dependencies:\n\n```bash\nyarn install\n```\n\n### Compile\n\nCompile the smart contracts with Hardhat:\n\n```bash\nyarn compile\n```\n\n### Test\n\nRun the Mocha tests:\n\n```bash\nyarn test\n```\n\n## 📃 Deploy RMM\n\nDeploy the protocol to a network:\n\n```bash\nyarn deploy --network nameOfNetwork\n```\n\nThis will call a hardhat task that deploys the RMM protocol contracts from a loaded signer and saves the addresses to `/deployments`.\n\nHere are the options for the `deploy` task:\n\n- `--defender` (optional): Flag to attempt to use an Open Zeppelin Defender Relay Signer, if it exists in the hardhat.config.ts file.\n- `--channel` (optional): Directory name in /deployments/ to save the deployment to.\n- `--gasPrice` (optinal): Price to pay for gas.\n- `--testweth` (optional): Only for test networks, allows specifying a WETH9 address.\n\n### Deploy Primitive Engines - Pair contracts\n\n```bash\nyarn deploy:engine --network nameOfNetwork\n```\n\nThis is a script that runs which requires two of the token addresses. Here is the script, which should be edited to suit the deployment needs:\n\n```typescript\nimport hre from 'hardhat'\nimport { Signer } from '@ethersproject/abstract-signer'\nimport { DefenderRelaySigner } from 'defender-relay-client/lib/ethers'\nimport { deployEngine } from '../utils/deployEngine'\n\ntype Signers = Signer | DefenderRelaySigner\n\nexport async function main() {\n  const signer: Signers = await hre.run('useSigner')\n\n  const rmm = await hre.connect(signer)\n  const chainId = rmm.connection.chainId\n  if (chainId === 1) throw new Error('Do not use this in prod!')\n\n  const risky = '0xc778417E063141139Fce010982780140Aa0cD5Ab' // rinkeby:WETH: FIX\n  const stable = '0x522064c1EafFEd8617BE64137f66A71D6C5c9aA3' // rinkeby:USDC: FIX\n\n  await deployEngine(rmm, risky, stable)\n}\n\nmain()\n  .then(() =\u003e process.exit(0))\n  .catch(error =\u003e {\n    console.error(error)\n    process.exit(1)\n  })\n```\n\n### 🪞 Deploy RMM Pools Script\n\n\u003e Warning: Currently failing for node versions above 14.7.4. Unresolved promises are not handled in the higher node versions, and instead the process is exited with a non-zero error code.\n\n\u003e Work in progress: This script is still being improved! Consider it an alpha version.\n\nDeploy pools in the config of the `deploy-pools.ts` script:\n\n```bash\nyarn deploy:pools --network nameOfNetwork\n```\n\nCreating RMM pools is a process that requires connecting to the protocol, fetching token metadata, and building the transaction's arguments. This script handles loading tokens from a saved pool deployment, located in `/deployments/*/pools.json`.\n\nAll the logic executed by a hardhat script must exist in the script file. Here is an example:\n\n```typescript\nimport hre from 'hardhat'\nimport { EthersRmm } from 'src/EthersRmm'\nimport { deployPools } from 'utils/deployPools'\nimport { poolDeployer } from 'utils/poolDeployer'\n\nexport async function main() {\n  const signer: Signers = await hre.run('useSigner')\n  const from = await signer.getAddress()\n\n  const rmm = await hre.connect(signer)\n\n  const chainId = rmm.connection.chainId\n\n  if (chainId === 1) throw new Error('Do not use this in prod!')\n\n  const deployer = new PoolDeployer(chainId, POOL_DEPLOYMENTS_SAVE, POOL_CONFIG_TO_DEPLOY, rmm)\n\n  await deployPools(deployer)\n}\n\nmain()\n  .then(() =\u003e process.exit(0))\n  .catch(error =\u003e {\n    console.error(error)\n    process.exit(1)\n  })\n```\n\n## 📌 Misc. Scripts\n\nGenerate documentation locally:\n\n```\nyarn docs\n```\n\nDeploy to a local ganache-cli instance:\n\n```\nyarn deploy:devnet\n```\n\nDelete a local deployment to ganache-cli:\n\n```\nyarn delete-dev-deployments\n```\n\n## 🛡️ Use with Open Zeppelin Defender Relays\n\nThe OZ Defender relayers are a safer way to execute transactions on-chain.\n\nThe `hardhat.config.ts` is extended to include OZ defender relay API key and secret:\n\n```typescript\ndefender: {\n    [chainIds.rinkeby]: {\n      apiKey: RELAY_RINKEBY_API || '',\n      apiSecret: RELAY_RINKEBY_SECRET || '',\n    },\n}\n```\n\nAdding this to the hardhat config will expose the relay signer through the task `useSigner`.\n\nThis task is currently only used in the `deployPools.ts` script, so pools can be deployed safely from the OZ defender relay.\n\n🖋️ `useSigner`\n\nIf this subtask is run from task run with a `--network` flag, and the network has an OZ relayer config in the hardhat config file, this task will return the `Signer` object for the relayer. Else, useSigner will default to the `ethers.getSigners()`. This subtask can be used in custom scripts so you can choose to use a relayer or a private key stored in `.env`.\n\n- `--i` (optional): Index of the signer to use from `ethers.getSigners()`\n\n## ⛑ Contribute\n\nFeel free to suggest changes by opening a pull request, or posting an issue. There is a dedicated `dev` channel in the [Primitive discord](https://discord.gg/primitive).\n\n## Credits\n\nInspired by [Liquity Ethers](https://github.com/liquity/dev/tree/main/packages/lib-ethers).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimitivefinance%2Frmm-ethers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprimitivefinance%2Frmm-ethers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimitivefinance%2Frmm-ethers/lists"}