@superfluid-finance/sdk-core 0.1.1-dev.fa49a94.0 → 0.2.1-dev.652c1bb.0

package/README.md

@@ -23,6 +23,30 @@
 
 ### 📖 [Docs](https://docs.superfluid.finance)
 
+# Introduction
+SDK-Core is an application framework for interacting with the Superfluid Protocol without Solidity knowledge.
+
+More specifically, SDK-Core is a wrapper library around `@superfluid-finance/ethereum-contracts` which allows web developers to interact with the Superfluid contracts.
+Under the hood, SDK-Core leverages TypeScript, ethers.js and The Graph and GraphQL.
+
+## Important Disclaimer
+SDK-Core is in early active development and can have breaking releases without warning and without consideration for semantic versioning.
+
+# Features
+* Minimal Framework initialization (`networkName` or `chainId` and `provider`)
+* New Operation syntax for transactions
+* Create/Update/Delete Agreement Operations (Constant Flow Agreement and Instant Distribution Agreement)
+* SuperToken Operations
+* Subgraph-powered GraphQL querying with ordering and pagination
+* Event subscription
+* CFA/IDA/SuperToken Web3 Getters
+* Batch Call functionality for batching multiple Superfluid Operations in one transaction
+
+# Notable Used Technologies
+* TypeScript
+* Ethers
+* GraphQL
+
 # Prerequisites
 
 To get the package up and running you'll need to install the necessary dependencies and build the project:
@@ -31,18 +55,32 @@ To get the package up and running you'll need to install the necessary dependenc
 yarn install && yarn build
 ```
 
-# Usage
+# Tutorial
 
+For the best and most immersive experience of learning how to use the main sdk-core features, I would highly recommend heading over to our [interactive tutorials](https://docs.superfluid.finance/superfluid/protocol-tutorials/interactive-tutorials).
+# Getting Started
 ## Framework Initialization
 
 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,36 +98,83 @@ const web3jsSf = await Framework.create({
   networkName: "matic",
   provider: web3jsProvider
 });
-```
-
-JavaScript (CommonJS) - usually a Node.js environment:
-
-```js
-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({
+// 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",
+});
+
+// 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
+});
+
+// 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({
-  networkName: "matic",
-  provider: web3jsProvider
+// web3modal
+import Web3Modal from "web3modal";
+const web3Modal = new Web3Modal({
+  cacheProvider: false,
+  providerOptions: {}
 });
+const web3ModalRawProvider = await web3Modal.connect();
+const web3ModalProvider = new ethers.providers.Web3Provider(web3ModalRawProvider);
+const web3ModalSf = await Framework.create({
+  networkName: "matic",
+  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"`.
 
-This is the absolute minimum you need to provide the constructor (`chainId` or `networkName` and a `provider` object) if all you want to do are read operations. It is also important to note that the provider does not need to be an InfuraProvider - it just needs to satisfy the `ethers.Provider` interface.
+The absolute minimum you need to provide the constructor is `chainId` or `networkName` and a `provider` object if all you want to do are read operations. It is also important to note that the provider does not need to be an InfuraProvider - it just needs to satisfy the `SupportedProvider` interface: `ethers.providers.Provider | (typeof ethers & HardhatEthersHelpers) | Web3`.
 
 ## Helper Classes
 
@@ -119,8 +204,6 @@ const sf = await Framework.create({
 type Paging = { take: number, skip?: number, lastId?: string };
 
 const pageResult = await sf.query.
-  listAllResults(paging: Paging);
-  
   // The different queries can take different order by properties 
   // given the properties that exist on the entity itself.
   listAllSuperTokens({ isListed?: boolean },
@@ -229,11 +312,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
@@ -278,9 +361,7 @@ const sf = await Framework.create({
   provider,
 });
 
-const signer = sf.createSigner({
-  signer: wallet
-});
+const signer = sf.createSigner({ signer: wallet });
 ```
 
 ### Operation
@@ -307,10 +388,10 @@ const sf = await Framework.create({
 const signer = sf.createSigner({ privateKey: "<TEST_ACCOUNT_PRIVATE_KEY>", provider });
 
 // load the usdcx SuperToken via the Framework
-const usdcx = sf.loadToken("0xCAa7349CEA390F89641fe306D93591f87595dc1F");
+const usdcx = sf.loadSuperToken("0xCAa7349CEA390F89641fe306D93591f87595dc1F");
 
 // create an approve operation
-const approveOperation = usdcx.approve("0xab...", ethers.utils.parseUnits("100"));
+const approveOperation = usdcx.approve({ receiver: "0xab...", amount: ethers.utils.parseUnits("100").toString() });
 
 // execute the approve operation, passing in a signer
 const txn = await approveOperation.exec(signer);
@@ -319,7 +400,7 @@ const txn = await approveOperation.exec(signer);
 const receipt = await txn.wait();
 
 // or you can create and execute the transaction in a single line
-const approveTxn = await usdcx.approve("0xab...", ethers.utils.parseUnits("100")).exec(signer);
+const approveTxn = await usdcx.approve({ receiver: "0xab...", amount: ethers.utils.parseUnits("100").toString() }).exec(signer);
 const approveTxnReceipt = await approveTxn.wait();
 ```
 
@@ -334,7 +415,6 @@ import { ConstantFlowAgreementV1 } from "@superfluid-finance/sdk-core";
 
 const config = {
   hostAddress: "0x3E14dC1b13c488a8d5D310918780c983bD5982E7",
-  superTokenFactoryAddress: "0x2C90719f25B10Fc5646c82DA3240C76Fa5BcCF34",
   cfaV1Address: "0x6EeE6060f715257b970700bc2656De21dEdF074C",
   idaV1Address: "0xB0aABBA4B2783A72C52956CDEF62d438ecA2d7a1"
 };
@@ -369,7 +449,7 @@ await sf.cfaV1.getNetFlow({
 sf.cfaV1.createFlow({
   sender: string,
   receiver: string,
-  token: string,
+  superToken: string,
   flowRate: string,
   userData?: string
 });
@@ -377,7 +457,7 @@ sf.cfaV1.createFlow({
 sf.cfaV1.updateFlow({
   sender: string,
   receiver: string,
-  token: string,
+  superToken: string,
   flowRate: string,
   userData?: string
 });
@@ -385,7 +465,7 @@ sf.cfaV1.updateFlow({
 sf.cfaV1.deleteFlow({
   sender: string,
   receiver: string,
-  token: string,
+  superToken: string,
   userData?: string
 });
 ```
@@ -420,7 +500,7 @@ const signer = sf.createSigner({ privateKey: "<TEST_ACCOUNT_PRIVATE_KEY>", provi
 const createFlowOperation = sf.cfaV1.createFlow({
   sender: "0x...",
   receiver: "0x...",
-  token: "0x...",
+  superToken: "0x...",
   flowRate: "1000000000"
 });
 const txnResponse = await createFlowOperation.exec(signer);
@@ -439,8 +519,7 @@ import { InstantDistributionAgreementV1 } from "@superfluid-finance/sdk-core";
 
 const config = {
   hostAddress: "0x3E14dC1b13c488a8d5D310918780c983bD5982E7",
-  superTokenFactoryAddress: "0x2C90719f25B10Fc5646c82DA3240C76Fa5BcCF34",
-  idaV1Address: "0x6EeE6060f715257b970700bc2656De21dEdF074C",
+  cfaV1Address: "0x6EeE6060f715257b970700bc2656De21dEdF074C",
   idaV1Address: "0xB0aABBA4B2783A72C52956CDEF62d438ecA2d7a1"
 };
 
@@ -575,7 +654,7 @@ const sf = await Framework.create({
   provider
 });
 
-const usdcx = sf.loadToken("0xCAa7349CEA390F89641fe306D93591f87595dc1F");
+const usdcx = sf.loadSuperToken("0xCAa7349CEA390F89641fe306D93591f87595dc1F");
 ```
 
 #### Direct Initialization
@@ -591,7 +670,6 @@ const provider = new ethers.providers.InfuraProvider(
 
 const config = {
   hostAddress: "0x3E14dC1b13c488a8d5D310918780c983bD5982E7",
-  superTokenFactoryAddress: "0x2C90719f25B10Fc5646c82DA3240C76Fa5BcCF34",
   cfaV1Address: "0x6EeE6060f715257b970700bc2656De21dEdF074C",
   idaV1Address: "0xB0aABBA4B2783A72C52956CDEF62d438ecA2d7a1"
 };
@@ -599,7 +677,7 @@ const config = {
 const usdcx = await SuperToken.create({
   address: "0xCAa7349CEA390F89641fe306D93591f87595dc1F",
   config,
-  networkName: "matic",
+  networkName: "matic", // you can also pass in chainId instead (e.g. chainId: 137)
   provider
 });
 ```
@@ -607,7 +685,7 @@ const usdcx = await SuperToken.create({
 #### SuperToken Functions
 
 ```ts
-const usdcx = sf.loadToken("0xCAa7349CEA390F89641fe306D93591f87595dc1F");
+const usdcx = sf.loadSuperToken("0xCAa7349CEA390F89641fe306D93591f87595dc1F");
 
 // ERC20 `Token`
 // Read functions
@@ -692,7 +770,7 @@ const sf = await Framework.create({
   provider
 });
 
-const usdcx = sf.loadToken("0xCAa7349CEA390F89641fe306D93591f87595dc1F");
+const usdcx = sf.loadSuperToken("0xCAa7349CEA390F89641fe306D93591f87595dc1F");
 
 // Read example
 const name = await usdcx.name();
@@ -757,15 +835,8 @@ const batchCall = sf.batchCall([<OPERATION_A>, <OPERATION_B>, ...]);
 ```ts
 import { SuperToken } from "@superfluid-finance/sdk-core";
 
-const config = {
-  hostAddress: "0x3E14dC1b13c488a8d5D310918780c983bD5982E7",
-  superTokenFactoryAddress: "0x2C90719f25B10Fc5646c82DA3240C76Fa5BcCF34",
-  cfaV1Address: "0x6EeE6060f715257b970700bc2656De21dEdF074C",
-  idaV1Address: "0xB0aABBA4B2783A72C52956CDEF62d438ecA2d7a1"
-};
-
 const batchCall = new BatchCall({
-  config,
+  hostAddress: "0x3E14dC1b13c488a8d5D310918780c983bD5982E7",
   operations: [<OPERATION_A>, <OPERATION_B>, ...],
 });
 ```