docs: Expand readme for investments

README.md

@@ -84,6 +84,53 @@ const subscription = pool.closeEpoch().subscribe(
 )
 ```
 
+## Investments
+
+Investments for a pool are done via [ERC-7540 Tokenized Vaults](https://eips.ethereum.org/EIPS/eip-7540). Vaults can be deployed for a tranche on any supported network, for any supported currency
+
+Retrieve a vault by querying it from the pool:
+
+```js
+const pool = await centrifuge.pool('1')
+const vault = await pool.vault(1, '0xabc...', '0xdef...') // Chain ID, tranche ID, investment currency address
+```
+
+Query the state of an investment on the vault for an investor:
+
+```js
+const investment = await vault.investment('0x123...')
+// Will return an object containing:
+// isAllowedToInvest - Whether an investor is allowed to invest in the tranche
+// investmentCurrency - The ERC20 token that is used to invest in the vault
+// investmentCurrencyBalance - The balance of the investor of the investment currency
+// investmentCurrencyAllowance - The allowance of the vault
+// shareCurrency - The ERC20 token that is issued to investors to account for their share in the tranche
+// shareBalance - The number of shares the investor has in the tranche
+// claimableInvestShares - The number of shares an investor can claim after their invest order has been processed (partially or not)
+// claimableInvestCurrencyEquivalent - The equivalent value of the claimable shares denominated in the invest currency
+// claimableRedeemCurrency - The amout of money an investor can claim after their redeem order has been processed (partially or not)
+// claimableRedeemSharesEquivalent - The amount of shares that have been redeemed for which the investor can claim money
+// pendingInvestCurrency - The amount of money that the investor wants to invest in the tranche that has not been processed yet
+// pendingRedeemShares - The amount of shares that the investor wants to redeem from the tranche that has not been processed yet
+// claimableCancelInvestCurrency - The amount of money an investor can claim after an invest order cancellation has been processed
+// claimableCancelRedeemShares - The amount of shares an investor can claim after a redeem order cancellation has been processed
+// hasPendingCancelInvestRequest - Whether the investor has an invest order that is in the process of being cancelled
+// hasPendingCancelRedeemRequest - Whether the investor has a redeem order that is in the process of being cancelled
+```
+
+Invest in a vault:
+
+```js
+const result = await vault.increaseInvestOrder(1000)
+console.log(result.hash)
+```
+
+Once an order has been processed, `claimableInvestShares` will positive and shares can be claimed with:
+
+```js
+const result = await vault.claim()
+```
+
 ## Reports
 
 Reports are generated from data from the Centrifuge API and are combined with pool metadata to provide a comprehensive view of the pool's financials.

src/Pool.test.ts

@@ -3,6 +3,8 @@ import { Pool } from './Pool.js'
 import { context } from './tests/setup.js'
 
 const poolId = '2779829532'
+const trancheId = '0xac6bffc5fd68f7772ceddec7b0a316ca'
+const asset = '0x8503b4452Bf6238cC76CdbEE223b46d7196b1c93'
 
 describe('Pool', () => {
   let pool: Pool
@@ -17,4 +19,9 @@ describe('Pool', () => {
     expect(networks[0]!.chainId).to.equal(11155111)
     expect(networks[1]!.chainId).to.equal(84532)
   })
+
+  it('can query a vault', async () => {
+    const vault = await pool.vault(11155111, trancheId, asset)
+    expect(vault).to.not.be.undefined
+  })
 })

src/PoolNetwork.test.ts

@@ -1,5 +1,4 @@
 import { expect } from 'chai'
-import sinon from 'sinon'
 import { Pool } from './Pool.js'
 import { PoolNetwork } from './PoolNetwork.js'
 import { context } from './tests/setup.js'
@@ -16,10 +15,6 @@ describe('PoolNetwork', () => {
     poolNetwork = new PoolNetwork(centrifuge, pool, 11155111)
   })
 
-  afterEach(() => {
-    sinon.restore()
-  })
-
   it('should get whether a pool is deployed to a network', async () => {
     const isActive = await poolNetwork.isActive()
     expect(isActive).to.equal(true)
@@ -31,12 +26,9 @@ describe('PoolNetwork', () => {
   })
 
   it('get vaults for a tranche', async () => {
-    const fetchSpy = sinon.spy(globalThis, 'fetch')
     const vaults = await poolNetwork.vaults(trancheId)
     expect(vaults).to.have.length(1)
     expect(vaults[0]!.address.toLowerCase()).to.equal(vaultAddress)
-    // Calls should get batched
-    expect(fetchSpy.getCalls().length).to.equal(1)
   })
 
   it('should deploy a tranche', async () => {

src/PoolNetwork.ts

@@ -211,10 +211,11 @@ export class PoolNetwork extends Entity {
    * @param asset - The investment currency address
    */
   vault(trancheId: string, asset: string) {
+    const assetAddress = asset.toLowerCase()
     return this._query(null, () =>
       this.vaults(trancheId).pipe(
         map((vaults) => {
-          const vault = vaults.find((v) => v._asset === asset)
+          const vault = vaults.find((v) => v._asset === assetAddress)
           if (!vault) throw new Error('Vault not found')
           return vault
         })