@superfluid-finance/sdk-core 0.1.0 → 0.1.1-dev.087c350.0

package/README.md

@@ -37,12 +37,24 @@ yarn install && yarn build
 
 Here is a quick look at initializing the SDK in different environments:
 
-TypeScript / JavaScript (Module):
+TypeScript / JavaScript (Module) vs. JavaScript (CommonJS) - usually a Node.js environment
 
+The primary difference between the two environments is the import/require of the sdk-core package, everything else is the same.
+
+TS/ESModule
 ```ts
 import { Framework } from "@superfluid-finance/sdk-core";
 import { ethers } from "ethers";
+```
+
+CommonJS/Node.js
+```js
+const { Framework } = require("@superfluid-finance/sdk-core");
+const { ethers } = require("ethers");
+```
 
+```ts
+// infura provider initialization
 const provider = new ethers.providers.InfuraProvider(
   "matic",
   "<INFURA_API_KEY>"
@@ -60,31 +72,73 @@ const web3jsSf = await Framework.create({
   networkName: "matic",
   provider: web3jsProvider
 });
-```
 
-JavaScript (CommonJS) - usually a Node.js environment:
+// injected web3.js initialization (Hardhat) 
+// most likely to be used on backend for testing
+// NOTE: if you're using truffle, you should be able to
+// omit the (global as any) as this should be
+// exposed already (in JS at least)
+const injectedWeb3jsSf = await Framework.create({
+  networkName: "custom",
+  provider: (global as any).web3,
+  dataMode: "WEB3_ONLY",
+  resolverAddress: <RESOLVER_ADDRESS>,
+  protocolReleaseVersion: "test",
+});
 
-```js
-const { Framework } = require("@superfluid-finance/sdk-core");
-const { ethers } = require("ethers");
+// injected hardhat ethers initialization
+// most likely to be used on backend for testing
+import hardhat from "hardhat";
+const injectedHardhatEthersSf = await Framework.create({
+  networkName: "custom",
+  provider: hardhat.ethers,
+  dataMode: "WEB3_ONLY",
+  resolverAddress: <RESOLVER_ADDRESS>,
+  protocolReleaseVersion: "test",
+})
+
+// ethers.js + hardhat provider initialization (in testing environment w/ hardhat-ethers)
+import { ethers } from "hardhat";
+const [deployer] = await ethers.getSigners();
+const ethersProvider = deployer.provider;
+const ethersjsSf = await Framework.create({
+  networkName: "custom",
+  dataMode: "WEB3_ONLY",
+  resolverAddress: <RESOLVER_ADDRESS>,
+  protocolReleaseVersion: "test",
+  provider: ethersProvider
+});
 
-const provider = new ethers.providers.InfuraProvider(
-  "matic",
-  "<INFURA_API_KEY>"
-);
-const sf = await Framework.create({
+// metamask
+const mmProvider = new ethers.providers.Web3Provider(window.ethereum);
+const mmSf = await Framework.create({
   networkName: "matic",
-  provider
+  provider: mmProvider
 });
 
-// web3.js + Hardhat provider initialization
-const web3jsProvider = new ethers.providers.Web3Provider(
-  global.web3.currentProvider
-);
-const web3jsSf = await Framework.create({
+// web3modal
+const web3ModalRawProvider = await web3Modal.connect();
+const web3ModalProvider = new ethers.providers.Web3Provider(web3ModalRawProvider);
+const web3ModalSf = await Framework.create({
   networkName: "matic",
-  provider: web3jsProvider
+  provider: web3ModalProvider
+});
+
+//bnc-onboard
+const onboard = Onboard({
+    dappId: "<API_KEY>",
+    networkId: 4,
+    subscriptions: {
+        wallet: wallet => {
+            const web3Provider = new ethers.providers.Web3Provider(wallet.provider);
+            (async () => {
+                const framework = await Framework.create({ networkName: "matic", provider: web3Provider });
+            })();
+        }
+    }
 });
+// this is triggered by:
+await onboard.walletSelect();
 ```
 
 > Note: You specify your project type in `package.json` - `"type": "module"` or `"type": "commonjs"`.
@@ -116,12 +170,50 @@ const sf = await Framework.create({
 	provider
 });
 
+type Paging = { take: number, skip?: number, lastId?: string };
+
 const pageResult = await sf.query.
-  listAllSuperTokens({ isListed?: boolean }, { skip: number, take: number });
-  listIndexes({ indexId?: string, publisher?: string, token?: string }, { skip: number, take: number });
-  listIndexSubscriptions({ subscriber?: string, approved?: boolean }, { skip: number, take: number });
-  listStreams({ sender?: string, receiver?: string, token?: string }, { skip: number, take: number });
-  listUserInteractedSuperTokens({ account?: string, token?: string }, { skip: number, take: number });
+  listAllResults(paging: Paging);
+  
+  // The different queries can take different order by properties 
+  // given the properties that exist on the entity itself.
+  listAllSuperTokens({ isListed?: boolean },
+    paging: Paging,
+    ordering: Ordering<Token_OrderBy>
+  );
+
+  listIndexes({ indexId?: string, publisher?: string, token?: string },
+    paging: Paging,
+    ordering: Ordering<Index_OrderBy>
+  );
+
+  listIndexSubscriptions({ subscriber?: string, approved?: boolean },
+    paging: Paging,
+    ordering: Ordering<IndexSubscription_OrderBy>
+  );
+
+  listStreams({ sender?: string, receiver?: string, token?: string },
+    paging: Paging,
+    ordering: Ordering<Stream_OrderBy>
+  );
+
+  listUserInteractedSuperTokens({ account?: string, token?: string },
+    paging: Paging,
+    ordering: Ordering<AccountTokenSnapshot_OrderBy>
+  );
+
+  listEvents({ account?: string, timestamp_gt?: number },
+    paging: Paging,
+    ordering: Ordering<Event_OrderBy>
+  );
+
+  // A subscription function which allows you to subscribe to events via polling.
+  on(
+        callback: (events: AllEvents[], unsubscribe: () => void) => void,
+        ms: number,
+        account?: string,
+        timeout?: number
+    )
 ```
 
 #### Direct Initialization
@@ -130,17 +222,45 @@ If you'd like, you can also initialize the `Query` class as a standalone class l
 
 ```ts
 import { Query } from "@superfluid-finance/sdk-core";
-const query = new Query({ customSubgraphQueriesEndpoint: "<A_CUSTOM_ENDPOINT>", dataMode: "SUBGRAPH_ONLY" | "SUBGRAPH_WEB3" | "WEB3_ONLY" });
-query.listAllSuperTokens({ isListed?: boolean }, { skip: number, take: number })
-//...same queries as above...
+const query = new Query({
+  customSubgraphQueriesEndpoint: "<A_CUSTOM_ENDPOINT>",
+  dataMode: "SUBGRAPH_ONLY" | "SUBGRAPH_WEB3" | "WEB3_ONLY"
+});
 ```
 
 #### Pagination
 
-All of the pre-defined query functions will accept pagination options: `({ skip: number, take: number })`, if you don't pass anything in, it will use a default of: `{ skip: 0, take: 100 }`.
+All of the pre-defined query functions will accept pagination options: `({ skip: number, take: number })`, if you don't pass anything in, it will use a default of: `{ skip: 0, take: 100 }`. You can also paginate by `lastId`, this allows you to bypass the limitation of the max skip of 5000 entities.
 
 > Note: this example uses the `graphql-request` library, but you just need to provide a valid query which is a string.
 
+#### Ordering
+
+You can also pass in an ordering object for the different queries, each query function will accept different ordering properties depending on the properties on the entity. We have different defaults for each so you don't need to actually pass anything in.
+
+#### Example Usage
+
+```ts
+const { Framework } = require("@superfluid-finance/sdk-core");
+const { ethers } = require("ethers");
+
+const provider = new ethers.providers.InfuraProvider(
+	"matic",
+	"<INFURA_API_KEY>"
+);
+const sf = await Framework.create({
+  networkName: "matic",
+	provider
+});
+const results = await sf.query.listAllSuperTokens(
+  { isListed: true },
+  { skip: 5, take: 150 },
+  {
+    orderBy: "createdAtBlockNumber",
+    orderDirection: "desc"
+  });
+```
+
 ### Creating a Signer
 
 In order to execute a transaction on the blockchain, you need to have a signer. That is, you need to have access to an EOA (Externally Owned Account) to trigger any sort of change. You can do this through a contract, but an EOA still has to be the one which triggers the contract to interact with another contract. The signer that is returned will be passed when executing transactions.
@@ -163,11 +283,11 @@ const sf = await Framework.create({
   provider: web3ModalProvider,
 });
 
-const web3ModalSigner = sf.createSigner(web3ModalProvider);
+const web3ModalSigner = sf.createSigner({ web3Provider: web3ModalProvider });
 
 // MetaMask example
 const metamaskProvider = new Web3Provider(window.ethereum);
-const metaMaskSigner = sf.createSigner(metamaskProvider);
+const metaMaskSigner = sf.createSigner({ web3Provider: metamaskProvider });
 ```
 
 #### Hardhat Signer Example
@@ -212,9 +332,7 @@ const sf = await Framework.create({
   provider,
 });
 
-const signer = sf.createSigner({
-  signer: wallet
-});
+const signer = sf.createSigner({ signer: wallet });
 ```
 
 ### Operation
@@ -278,15 +396,88 @@ const cfaV1 = new ConstantFlowAgreementV1({ options: config });
 
 #### CFAV1 Functions
 ```ts
-// read
-await sf.cfaV1.getFlow({ superToken: string, sender: string, receiver: string, providerOrSigner: ethers.providers.Provider | ethers.Signer });
-await sf.cfaV1.getAccountFlowInfo({ superToken: string, account: string, providerOrSigner: ethers.providers.Provider | ethers.Signer });
-await sf.cfaV1.getNetFlow({ superToken: string, account: string, providerOrSigner: ethers.providers.Provider | ethers.Signer });
-
-// write
-await sf.cfaV1.createFlow({ sender: string, receiver: string, token: string, flowRate: string, userData?: string });
-await sf.cfaV1.updateFlow({ sender: string, receiver: string, token: string, flowRate: string, userData?: string });
-await sf.cfaV1.deleteFlow({ sender: string, receiver: string, token: string, userData?: string });
+// Read functions
+await sf.cfaV1.getFlow({
+  superToken: string,
+  sender: string,
+  receiver: string,
+  providerOrSigner: ethers.providers.Provider | ethers.Signer
+});
+
+await sf.cfaV1.getAccountFlowInfo({
+  superToken: string,
+  account: string,
+  providerOrSigner: ethers.providers.Provider | ethers.Signer
+});
+
+await sf.cfaV1.getNetFlow({
+  superToken: string,
+  account: string,
+  providerOrSigner: ethers.providers.Provider | ethers.Signer
+});
+
+
+// Write operations
+sf.cfaV1.createFlow({
+  sender: string,
+  receiver: string,
+  token: string,
+  flowRate: string,
+  userData?: string
+});
+
+sf.cfaV1.updateFlow({
+  sender: string,
+  receiver: string,
+  token: string,
+  flowRate: string,
+  userData?: string
+});
+
+sf.cfaV1.deleteFlow({
+  sender: string,
+  receiver: string,
+  token: string,
+  userData?: string
+});
+```
+
+#### Example Usage
+
+```ts
+import { Framework } from "@superfluid-finance/sdk-core";
+import { ethers } from "ethers";
+
+const provider = new ethers.providers.InfuraProvider(
+  "matic",
+  "<INFURA_API_KEY>"
+);
+
+const sf = await Framework.create({
+  networkName: "matic",
+  provider
+});
+
+// Read example
+const flowInfo = await sf.cfaV1.getFlow({
+  superToken: "0x...",
+  sender: "0x...",
+  receiver: "0x...",
+  providerOrSigner: provider
+});
+console.log("flowInfo", flowInfo);
+
+// Write operation example
+const signer = sf.createSigner({ privateKey: "<TEST_ACCOUNT_PRIVATE_KEY>", provider });
+const createFlowOperation = sf.cfaV1.createFlow({
+  sender: "0x...",
+  receiver: "0x...",
+  token: "0x...",
+  flowRate: "1000000000"
+});
+const txnResponse = await createFlowOperation.exec(signer);
+const txnReceipt = await txnResponse.wait();
+// Transaction Complete when code reaches here
 ```
 
 ### InstantDistributionAgreementV1
@@ -310,19 +501,110 @@ const idaV1 = new InstantDistributionAgreementV1({ options: config });
 
 #### IDAV1 Functions
 ```ts
-// read
-await sf.idaV1.getSubscription({ superToken: string, publisher: string, indexId: string, subscriber: string, providerOrSigner: string });
-await sf.idaV1.getIndex({ superToken: string, publisher: string, indexId: string, providerOrSigner: string });
-
-// write
-await sf.idaV1.createIndex({ indexId: string, userData: string });
-await sf.idaV1.distribute({ indexId: string, amount: string, userData: string });
-await sf.idaV1.updateIndexValue({ indexId: string, indexValue: string, userData: string });
-await sf.idaV1.updateSubscriptionUnits({ indexId: string, subscriber: string, units: string, userData: string });
-await sf.idaV1.approveSubscription({ indexId: string, subscriber: string, userData: string });
-await sf.idaV1.revokeSubscription({ indexId: string, subscriber: string, userData: string });
-await sf.idaV1.deleteSubscription({ indexId: string, subscriber: string, publisher: string, userData: string });
-await sf.idaV1.claim({ indexId: string, subscriber: string, publisher: string, userData: string });
+// Read functions
+await sf.idaV1.getSubscription({
+  superToken: string,
+  publisher: string,
+  indexId: string,
+  subscriber: string,
+  providerOrSigner: string
+});
+
+await sf.idaV1.getIndex({
+  superToken: string,
+  publisher: string,
+  indexId: string,
+  providerOrSigner: string
+});
+
+
+// Write operations
+sf.idaV1.createIndex({
+  indexId: string,
+  superToken: string,
+  userData?: string
+});
+
+sf.idaV1.distribute({
+  indexId: string,
+  superToken: string,
+  amount: string,
+  userData?: string
+});
+
+sf.idaV1.updateIndexValue({
+  indexId: string,
+  superToken: string,
+  indexValue: string,
+  userData?: string
+});
+
+sf.idaV1.updateSubscriptionUnits({
+  indexId: string,
+  superToken: string,
+  subscriber: string,
+  units: string,
+  userData?: string
+});
+
+sf.idaV1.approveSubscription({
+  indexId: string,
+  superToken: string,
+  publisher: string,
+  userData?: string
+});
+
+sf.idaV1.revokeSubscription({
+  indexId: string,
+  superToken: string,
+  publisher: string,
+  userData?: string
+});
+
+sf.idaV1.deleteSubscription({
+  indexId: string,
+  superToken: string,
+  subscriber: string,
+  publisher: string,
+  userData?: string
+});
+
+sf.idaV1.claim({
+  indexId: string,
+  superToken: string,
+  subscriber: string,
+  publisher: string,
+  userData?: string
+});
+```
+
+#### Example Usage
+
+```ts
+import { Framework } from "@superfluid-finance/sdk-core";
+import { ethers } from "ethers";
+
+const provider = new ethers.providers.InfuraProvider(
+  "matic",
+  "<INFURA_API_KEY>"
+);
+
+const sf = await Framework.create({
+  networkName: "matic",
+  provider
+});
+
+// Read example
+const subscription = await sf.idaV1.getSubscription({ superToken: "0x...", publisher: "0x...", indexId: "1", subscriber: "0x...", providerOrSigner: provider });
+console.log(subscription);
+
+
+// Write operation example
+const signer = sf.createSigner({ privateKey: "<TEST_ACCOUNT_PRIVATE_KEY>", provider });
+const createIndexOperation = sf.idaV1.createIndex({ indexId: "0", userData: "0x" });
+const txnResponse = await createIndexOperation.exec(signer);
+const txnReceipt = await txnResponse.wait();
+// Transaction Complete when code reaches here
 ```
 
 ### SuperToken
@@ -358,7 +640,6 @@ const provider = new ethers.providers.InfuraProvider(
   "matic",
   "<INFURA_API_KEY>"
 );
-let usdcx: SuperToken;
 
 const config = {
   hostAddress: "0x3E14dC1b13c488a8d5D310918780c983bD5982E7",
@@ -367,7 +648,7 @@ const config = {
   idaV1Address: "0xB0aABBA4B2783A72C52956CDEF62d438ecA2d7a1"
 };
 
-usdcx = await SuperToken.create({
+const usdcx = await SuperToken.create({
   address: "0xCAa7349CEA390F89641fe306D93591f87595dc1F",
   config,
   networkName: "matic",
@@ -380,32 +661,103 @@ usdcx = await SuperToken.create({
 ```ts
 const usdcx = sf.loadToken("0xCAa7349CEA390F89641fe306D93591f87595dc1F");
 
-// SuperToken Read Functions
-// ERC20 `Token` function
-await usdcx.balanceOf({ account: string, providerOrSigner: ethers.providers.Provider | ethers.Signer }); // Inherited ERC20 function
-await usdcx.allowance({ owner: string, spender: string, providerOrSigner: ethers.providers.Provider | ethers.Signer }); // Inherited ERC20 function
-await usdcx.totalSupply({ providerOrSigner: ethers.providers.Provider | ethers.Signer }); // Inherited ERC20 function
+// ERC20 `Token`
+// Read functions
+await usdcx.balanceOf({
+  account: string,
+  providerOrSigner: ethers.providers.Provider | ethers.Signer
+});
+
+await usdcx.allowance({
+  owner: string,
+  spender: string,
+  providerOrSigner: ethers.providers.Provider | ethers.Signer
+});
+
+await usdcx.name({
+  providerOrSigner: ethers.providers.Provider | ethers.Signer
+});
+
+await usdcx.symbol({
+  providerOrSigner: ethers.providers.Provider | ethers.Signer
+});
+
+await usdcx.totalSupply({
+  providerOrSigner: ethers.providers.Provider | ethers.Signer
+});
+
+
+// Write operations
+usdcx.approve({
+  recipient: string,
+  amount: string
+});
+
+usdcx.transfer({
+  recipient: string,
+  amount: string
+});
+
+usdcx.transferFrom({
+  sender: string,
+  recipient: string,
+  amount: string
+});
 
 // `SuperToken` only function
-await usdcx.realtimeBalanceOf({ account: string, timestamp: string, providerOrSigner: ethers.providers.Provider | ethers.Signer });
+await usdcx.realtimeBalanceOf({
+  account: string,
+  timestamp: string,
+  providerOrSigner: ethers.providers.Provider | ethers.Signer
+});
 
 // Write Functions
+
 // All write functions return Promise<Operation>
 
-// SuperToken Write Functions
-await usdcx.approve({ recipient: string, amount: string });
-await usdcx.downgrade({ amount: string });
-await usdcx.transfer({ recipient: string, amount: string });
-await usdcx.transferFrom({ sender: string, recipient: string, amount: string });
-await usdcx.upgrade({ amount: string });
+// SuperToken Write operations
+usdcx.downgrade({ amount: string });
+
+usdcx.upgrade({ amount: string });
 
 // SuperToken CFAV1/IDAV1 Functions are the same as the
 // ConstantFlowAgreementV1/InstantDistributionAgreementV1 class functions
 // except instead of the sf.cfaV1/idaV1.function() signature, it is token.function()
+// e.g. await usdcx.createIndex({ indexId: "0", userData: "0x" }).exec(signer);
 // and you don't need to pass in a token as a parameter as it uses the token address
 // of the instantiated class.
 ```
 
+#### Example Usage
+
+```ts
+import { Framework } from "@superfluid-finance/sdk-core";
+import { ethers } from "ethers";
+
+const provider = new ethers.providers.InfuraProvider(
+  "matic",
+  "<INFURA_API_KEY>"
+);
+
+const sf = await Framework.create({
+  networkName: "matic",
+  provider
+});
+
+const usdcx = sf.loadToken("0xCAa7349CEA390F89641fe306D93591f87595dc1F");
+
+// Read example
+const name = await usdcx.name();
+console.log(name);
+
+// Write operation example
+const signer = sf.createSigner({ privateKey: "<TEST_ACCOUNT_PRIVATE_KEY>", provider });
+const transferOperation = usdcx.transfer({ receiver: "0x...", amount: "1000000" });
+const txnResponse = await transferOperation.exec(signer);
+const txnReceipt = await txnResponse.wait();
+// Transaction Complete when code reaches here
+```
+
 > Note: you can also get the underlying Token object which only has ERC20 token read/write methods-this is useful for things like approving token spend to a SuperToken contract prior to upgrading for example.
 
 ```ts
@@ -421,12 +773,12 @@ The `BatchCall` class allows the user to batch multiple supported operations/tra
 
 Not all operations are supported by the batch call feature, below is a list of the supported operations:
 
-- ERC20_APPROVE (SuperToken only)
-- ERC20_TRANSFER_FROM
-- SUPERTOKEN_UPGRADE
-- SUPERTOKEN_DOWNGRADE
-- SUPERFLUID_CALL_AGREEMENT
-- CALL_APP_ACTION
+- `ERC20_APPROVE (SuperToken only)`
+- `ERC20_TRANSFER_FROM`
+- `SUPERTOKEN_UPGRADE`
+- `SUPERTOKEN_DOWNGRADE`
+- `SUPERFLUID_CALL_AGREEMENT`
+- `CALL_APP_ACTION`
 
 Most of the token methods are self explanatory, but some additional context for the last two operations is helpful.
 `SUPERFLUID_CALL_AGREEMENT` refers to all operations related to the CFA or IDA (`createFlow`, `updateIndex`, `distribute`, etc.).
@@ -473,7 +825,32 @@ const batchCall = new BatchCall({
 #### Usage
 
 ```ts
-const txn = await batchCall.execute(signer);
+import { Framework } from "@superfluid-finance/sdk-core";
+import { ethers } from "ethers";
+
+const provider = new ethers.providers.InfuraProvider(
+  "matic",
+  "<INFURA_API_KEY>"
+);
+
+const sf = await Framework.create({
+  networkName: "matic",
+  provider
+});
+ 
+ // 0xabc is the signer on Rinkeby testnet
+const signer = sf.createSigner({ privateKey: "<TEST_ACCOUNT_PRIVATE_KEY>", provider });
+const daix = await sf.loadSuperToken("0x745861AeD1EEe363b4AaA5F1994Be40b1e05Ff90");
+const fromAddress = "0xabc";
+const paymentAddress = "0xdef";
+const approveOp = daix.approve({ receiver: paymentAddress, amount: "10000" });
+const transferFromOp = daix.transferFrom({
+  sender: fromAddress,
+  receiver: paymentAddress,
+  amount: "10000",
+});
+const batchCall = sf.batchCall([approveOp, transferFromOp]);
+const txn = await batchCall.exec(signer);
 
 // creating an operation from a super app function
 // initialize your super app contract
@@ -483,5 +860,5 @@ const superApp = new ethers.Contract("0x...", <SUPER_APP_ABI>);
 const superAppTransactionPromise = superApp.populateTransaction.helloWorld("hello world");
 
 // create the super app operation you can execute this operation directly or pass it in to a batch call
-const superAppOperation = new Operation(superAppOperation, "CALL_APP_ACTION");
+const superAppOperation = new Operation(superAppTransactionPromise, "CALL_APP_ACTION");
 ```