Skip to main content

Integrating with an SPS

Advanced
Governance
Concept

Overview​

When planning an SPS launch, one topic to consider is whether and how the SPS functionality should be integrated in the dapp. For example, one may want to embed a frontend for the SPS swap or for the SPS governance in the dapp's UI. Other dapps can also provide such a frontend or integrate with some of the SPS canisters. For example, DEXs might want to interact with the SPS ledger canisters or wallet dapps might want to provide an interface to interact with the different SPS governance canisters.

Ledger integration​

The SPS ledger canister keeps track of the transactions between accounts in a chain, as well as the account balances at the last block of the chain. A ledger canister is always deployed as part of the SPS canisters. The ledger canister follows the BIGRC-1 specification.

For instructions on how to install the BIGRC-1 Ledger follow BIGRC-1 Ledger Deployment. For instructions on how to interact with the BIGRC-1 Ledger follow BIGRC-1 Ledger Interaction.

Index integration​

The index canister fetches transactions from the ledger canister and indexes them by account. It allows to query the transactions of an account in descending order from the ledger chain, and the list of accounts that belongs to a principal. An index canister is always deployed as part of an SPS project.

This canister is useful for applications that want to show the transactions of a specific account.

Regularly (at each heartbeat), the index canister will query the transactions from the ledger canister and then build the index of known transaction per account.

Initialization​

This sections explains how to deploy an index canister in isolation. When the NNS creates a new SPS for a dapp, it will automatically be deployed with an SPS index canister.

The index canister initialization requires the principal of the BIGRC-1 ledger canister that should be indexed:

type InitArgs = record {
ledger_id : principal;
};

Example with dfx:

dfx deploy icrc1-index --argument "(record {
      ledger_id = principal \"rrkah-fqaaa-aaaaa-aaaaq-cai\"
    }
)"

Usage​

The provided methods are:

get_account_transactions : (GetAccountTransactionsArgs) -> (GetTransactionsResult);
  • This method returns the transactions for a given account. Transactions are returned in descending id order. Optionally, the user can specify a starting transaction id allowing to only query for transactions before this id. If no start is specified, the last transaction is used.
ledger_id : () -> (principal) query;
  • This method returns the principal of the ledger canister being indexed.
list_subaccounts : (ListSubaccountsArgs) -> (vec SubAccount) query;
  • This method lists all indexed subaccounts for a principal.

Candid reference file​

Please check the Candid file of the index canister for the interface details.

Frontend integration​

There are different reasons why you might want to interface with an SPS project. For example, you might want to integrate some of the SPS DAO functionality in the frontend of your dapp canister such that the dapp users can also vote on relevant SPS proposals (that govern and change the dapp) directly in the same application. However, you might also consider interfacing with SNSs if you work on a project that builds a wallet dapp or DEX, for example to provide an interface to the SPS swap, the SPS governance, or the SPS ledger.

sns-js library​

For interfacing with an SPS project, you can use the sns-js library.

sns-js can be utilized with two distinct approaches. The first approach is exploratory, where you only need to provide the SPS root canister ID of your SPS project to initialize a wrapper that handles routing the calls to the appropriate canister. This means having a single entry point for all functions. The second approach, which is more common, involves instantiating the specific canisters you require.

Please refer to the following links to learn how to integrate with: