StreamPay Javascript SDK

Usage

const StreamPaySDK = require("@streampay/js-sdk");
const { Web3Provider } = require("@ethersproject/providers");

const sf = new StreamPaySDK.Framework({
    ethers: new Web3Provider(window.ethereum),
    tokens: ["fDAI"]
});
await sf.initialize();

const bob = sf.user({ address: "0xabc...", token: sf.tokens.fDAIx.address });

// Constant Flow Agreement
await bob.flow({
    recipient: "0x123...",
    flowRate: "38580246913580" // 100 tokens / mo
});

// Instant Distribution Agreement
// - More utilities coming soon. See the docs for now

Instructions for getting started

1. Install the dependencies � npm install
2. Build the project � npm run build OR bash tasks/build-abi-js.sh && webpack

Tests can be run with the following commands � npm run test OR truffle test

What's In the Bag

• sf.user: A helpful abstraction that should handle most of your needs. See below for more details.
• sf.contracts : The truffle contract objects loaded by the SDK:
  • IERC20 : The ERC20 Interface.
  • TokenInfo : A customary ERC20 token info interface (name/symbol/decimals).
  • ERC20WithTokenInfo : A combination of IERC20 and TokenInfo.
  • TestToken : A ERC20 Test token.
  • IResolver : A simple resolver interface to locate different versions of the contracts.
  • ISuperToken : The Super token contract interface.
  • IConstantFlowAgreementV1 : The constant flow agreement (v1) contract interface.
  • IInstantDistributionAgreementV1 : The instant distribution agreement (v1) contract interface.
• Token factory helper functions:
  • sf.createERC20Wrapper
• sf.resolver: The resolver used by the SDK.
  • In test nets, there are some test tokens can be located with the resolver:
    • fDAI : The fake DAI. sf.resolver.get("tokens.fDAI").
    • fUSDC : The fake USDC. sf.resolver.get("tokens.fUSDC").
    • fTUSD : The fake TUSD. sf.resolver.get("tokens.fTUSD").
• sf.agreements:
  • sf.agreements.cfa : Constant flow agreement truffle contract instance.
  • sf.agreements.ida : Instant distribution agreement truffle contract instance.
• sf.cfa: The constant flow agreement helper class instance.
• sf.ida: The instant distribution agreement helper class instance.

Initialization

During initialization, the resolver will be used to fetch the correct set of contracts based on the version you provide

| Argument | Type | description | default | | :----------- | :------- | ---------------------------------------- | ------- | | version | String | Release version of the deployed protocol | v1 | | isTruffle | Boolean | Use the Framework under the native truffle environment | false | | web3 | Object | Use the Framework with web3.js (1.3.x) | undefined | | ethers | Object | Use the Framework with ethers.js (5.x.y) | undefined | | tokens | String[] | List of tokens | [] |

You also need to choose what web3 framework you plan to use, currently we support three modes:

• Truffle native environment (developing using truffle test|exec|egc.).
• Web3.js, currently the SDK has been tested with web3.js 1.3.x versions.
• Ethers.js, currently the SDK has been tested with ethers.js 5.x.y versions.

Example with Ethers.js

const StreamPaySDK = require("@streampay/js-sdk");
const { Web3Provider } = require("@ethersproject/providers");

const sf = new StreamPaySDK.Framework({
    ethers: new Web3Provider(window.ethereum),
    tokens: ["fDAI"]
});
await sf.initialize();

const bob = sf.user({ address: "0xabc...", token: sf.tokens.fDAIx.address });

The exposed contract objects are an adapted version that look like truffle-contract objects.

Example with Web3.js

const StreamPaySDK = require("@streampay/js-sdk");
const web3 = require("web3");

const sf = new StreamPaySDK.Framework({
    web3: new Web3(window.ethereum),
    tokens: ["fDAI"]
});
await sf.initialize();

const bob = sf.user({ address: "0xabc...", token: sf.tokens.fDAIx.address });

The exposed contract objects are of truffle-contract type.

Example with truffle native

const StreamPaySDK = require("@streampay/js-sdk");

const sf = new StreamPaySDK.Framework({
    isTruffle: true,
    tokens: ["fDAI"]
});
await sf.initialize();

const bob = sf.user({ address: "0xabc...", token: sf.tokens.fDAIx.address });

The exposed contract objects are of truffle-contract type loaded using truffle artifacts object.

User

Create a new User object to quickly create and modify agreements.

Example:

const bob = sf.user({ address: "0xabc...", token: sf.tokens.fDAI });
const carol = sf.user({ address: "0x123...", token: sf.tokens.fDAI });

user.details()

Returns details about an account.

| Argument | Type | default | | :------- | :--- | ------- | | n/a | | |

Example:

console.log(await bob.details());

> {
    cfa: {
        flows: {
            inFlows: [
                {
                    sender: "0xf17f52151EbEF6C7334FAD080c5704D77216b732",
                    receiver: "0xC5fdf4076b8F3A5357c5E395ab970B5B54098Fef",
                    flowRate: "38580246913580"
                }
            ],
            outFlows: [
                {
                    sender: "0xC5fdf4076b8F3A5357c5E395ab970B5B54098Fef",
                    receiver: "0x821aEa9a577a9b44299B9c15c88cf3087F3b5544",
                    flowRate: "19290123456790"
                }
            ]
        },
        netFlow: "19290123456790"
    },
    ida: {} // Available soon
}

user.flow({recipient, flowRate, [, onTransaction, ...]})

Create / update / delete a flow to the recipient. Enter "0" to delete a flow.

| Argument | Type | default | | :------------ | :----------------------------- | -------- | | recipient | Address or another User Object | required | | flowRate | String | required | | onTransaction | Function | null |

Example:

const tx = await alice.flow({
    recipient: bob,
    flowRate: "38580246913580", // 100 / mo
    // OPTIONS: See ConstantFlowAgreementV1Helper for more
    onTransaction: hash => {
        txHash = hash;
    }
});

Closer to the metal

You may also use the helper classes and functions instead of the User abstraction.

The helpers are usually considered thinner wrappers of the underlying contract calls. It is suitable if you want more control and customization of how to interact with the protocol.

The available helpers currently are:

• sf.cfa - Constant flow agreement helper.
• sf.ida - Instant distribution agreement helper.
• sf.createERC20Wrapper - Create a new ERC20 wrapper.
• sf.batchCall - (TBD) batchCall helper.
• sf.callAppAction - (TBD) callAppAction helper.

For their documentations, please look into their code comments directly.

Module packaging

Check the module size and dependencies:

yarn stats

Testing

Since testing can take a long time to execute, you may want to use the execlusive tests feature from MochaJS to isolate only the test you want. For example:

# Only run User.test.js
nodemon -x npx truffle test ./test/User.test.js