songchain-sdk v2.1.6

Songchain SDK

This SDK can be used to build (d)Apps on top of the Songchain smart contracts in Javascript/Typescript. Its purpose is to abstract the needed configurations and direct interactions with the blockchain, smart contracts and other Web3 related 'connection' code and provide a simple more functional interface based on the use case of the dApp. It is also made in a way that it can be used both in node.js applications as in browser environments.

Local Development and Testing

Build

To build the SDK, run the following command:

npm run build

Package

The SDK is meant to be used as a dependency in other projects. To package the SDK for local testing, run the following command:

npm pack

Install

To install the package created in the previous step, you can run the following command in the project you want to use the SDK in:

npm install <path-to-sdk>/songchain-sdk-<version>.tgz

Publishing

To publish the package to npm, a Github Action is used. You can find the code of the action in (.github/workflows/publish.yaml).github/workflows/publish.yaml. Currently the Action is set to be triggered manually as to not necesarrily have a new version on every small change, but so it can be controlled when a new release is published.The Action will bump the version depending on the semver type that can be passed as an input to the Action. The action will then build the SDK and publish it to npm.

Project structure

The actual code of the SDK is located in the src folder. The index.ts file in the root of the project is the entry point of the SDK and exports all the public functions and classes of the SDK. In the src folder you can find the following folders that separate code based on different data-sources:

• blockchain-layer: contains the code that interacts with the blockchain and smart contracts
• ipfs-layer: contains the code to interact with IPFS
• the-graph-layer: contains the code to interact with The Graph

There is also a wallets folder that provides some functions to make it easier to query balances of the different tokens created and used in the platform. For example a wallet for an Artist can be generated which has some extra functionalities compared to a wallet of a regular user, since an artist also has a balance of the funding he received by selling tokens.

The rest of the folders in the src folder contains utility functions and classes that provide a specific functionality combining different layers of the SDK. Those files form the main interface of the SDK and are the ones that should be used in other projects. Some functions of the layers are also exported in case more granular control is needed though.

Blockchain layer

This layer contains the code to connect to the blockchain and smart contracts and implements the basic function calls that can be done to the smart contracts.

ABI's

The abi (application binary interface) of the smart contracts can be found in the abis folder.

Addresses

The addresses of the contracts as deployed on different networks can be found in the addresses.ts file. They are configured by network id and can be changed if needed. When new deployments of the smart contracts are done in which the address changes, they should be updated here.

Provider & network

In the provider.ts file some utility functions are added to easily construct a signer or provider, or in other words a connection to the blockchain, respectively with a wallet to be able to also sign and send transactions to the network, or without a wallet to just read information from the blockchain. The network.ts file contains some utility functions to get information about the network that is connected to, like the chain id.

Contracts

The two smart contracts that should be interacted with in songchain are the Songchain's own smart contracts and the contracts of the tokens that are accepted as means of payment in the platform. These tokens are ERC20 contracts, so the erc20Contract.ts file can be used to create an instance with basic erc20 functions to interact with a specific token. A list of accepted tokens and their addresses it maintained in a tokenlist in stablecoin.tokenlist.json.

To interact with the basic songchain smart contract functions, an instance of SongchainContract can be obtained from the songchainContract.ts file.

IPFS layer

The IPFS layer implementes and exports a ipfs client that can be used to add and obtain metadata of the tokens that are created on the platform.

The Graph layer

The Graph layer is the layer to interact with the subgraph of the Songchain platform. It implements some basic queries that can be done to the subgraph and returns the results in a structured way. A client can be instantiated and queries can be passed to it. The client will then take care of the connection to the subgraph and the query execution. It also has the interfaces of all entities that are indexed by subgraph.

Wallets

Since the front-end applications need to show different balances of different tokens, like the payment tokens they have in their account, the royalty rights tokens they have bought, the royalties they can claim etc. it is useful to have a wallet instance that more easily can fetch all this information in a straight forward way, that is what a wallet instance can do. It is an abstraction layer that aggregates a lot of the public API of the SDK in a more convenient way to obtain "wallet" data. An instance can be created using the WalletFactory. Just pass the account address of a user and you will be able to obtain all different balances of the user or any related transactional wallet data.

Other

The other files in the src folder contain the public API of the SDK that should be used by the users of the SDK. It contains functions to create transactions in the platform, like buying tokens, claiming royalties, creating tokens etc. Therefore a signer needs to be created first. It also contains getter functions, of which some are also available through the wallet instances, but they can also be called directly.

Usage

Installation

In the project where you want to use the SDK, you can install it using npm:

npm install songchain-sdk

Examples

// For write transactions, a signer needs to be created and passed
const privateKey = '<privateKey>';
const network = '<network>';
const infuraProjectId = '<infuraProjectId>';
const infuraProjectSecret = '<infuraProjectSecret>';
const signer = getConnectedWalletProvider(privateKey, network, infuraProjectId, infuraProjectSecret);
// Then you can use the functions of the SDK to create transactions. For example to claim royalties:
const paymentTokenAddress = '<paymentTokenAddress>';
const txResponse = await claimRoyalties(<royaltyRightsId>, paymentTokenAddress, signer);
// Then the txId can be obtained from the txResponse and the transaction can be tracked on the blockchain

// For read-only functions, a provider can be created and passed
const provider = getReadProvider(network, infuraProjectId, infuraProjectSecret);
// Then you can use the functions of the SDK to get information from the blockchain. For example to get the amount of funding available to an artist:
const availableFromFunding = await getAvailableAmountOfFunding(<royaltyRightsId>, paymentTokenAddress, provider);

// You can get a list of accepted payment tokens like this:
const acceptedPaymentTokens = await getAcceptedPaymentTokens(<signerOrProvider>);

// To use the wallet instances, you can create one like this:
const walletAddress = '0x...';
const isArtist = true | false; // rue if the account is from an artist, false if it is from an investor user
const wallet = await WalletFactory.getWallet(walletAddress, isArtist);
const balances = await wallet.getPaymentTokenBalances(provider | signer); // Both a signer or provider can be used for read functions, a signer is always a provider too.