This package provides a set of helper functions and components that can be used in a frontend React application for the Open-Source On-Chain DAO Governance.
The main functionality of this package includes:
- Context provider for clients that are used to fetch data and create blockchain transactions
- Set of hooks for data fetching
- Set of hooks for creating blockchain transactions
Look at our example application which is an example implementation of frontend for On-Chain DAO Governance that uses this package.
yarn add @wingriders/cab
yarn add @wingriders/governance-sdk
yarn add @wingriders/governance-frontend-react-sdk
Create a queries client which will be used to fetch data. Pass in the url to your governance backend server:
import {createQueriesClient} from '@wingriders/governance-sdk'
const queriesClient = createQueriesClient({
governanceUrl: 'https://api.governance.exampleapp.com', // pass in your URL
})
The queries client should be created only once so you can call this on a global level in one of your root components.
Actions client is used to create actions (mutations) for blockchain transactions, for example creating a proposal or casting a vote. As these actions are dependant on users wallet, you should create an action client once user connects a wallet to your site.
import {CborToJsApiWalletConnector} from '@wingriders/cab/wallet/connector'
import {createActionsClient} from '@wingriders/governance-sdk'
const walletConnector = new CborToJsApiWalletConnector(window.cardano.nami, {vendor: null}) // choose wallet based on users connected wallet type
const jsApi = await walletConnector.enableJs()
const actionsClient = await createActionsClient({
networkName: NetworkName.PREPROD, // set your network
jsApi,
governanceVotingParams,
protocolParameters,
})
governanceVotingParams
and protocolParameters
can be fetched using the queries client, see Fetching data.
Once you create your queries and actions clients, you should pass them to <DaoGovernanceProvider />
which should wrap your entire application:
const App = () => {
return (
<DaoGovernanceProvider queriesClient={queriesClient} actionsClient={actionsClient}>
...your app
</DaoGovernanceProvider>
)
}
Not that actionsClient
is optional and should be passed in only if the user has his wallet connected to your site.
Once you complete the setup steps, you will be able to use the following hooks for fetching data and creating actions.
Every endpoint that is provided by the governance server, has it's own useQuery hook that can be used to fetch data from that endpoint. For example, fetching all proposals would look like this:
import {useProposalsQuery} from '@wingriders/governance-frontend-react-sdk'
const Proposals = () => {
const {data, isLoading, isError} = useProposalsQuery()
return <div>{data?.map((proposal) => <div>...render proposals</div>)}</div>
}
Here is the list of query hooks that is available in @wingriders/governance-frontend-react-sdk
:
query hook | corresponding backend endpoint |
---|---|
useActiveProposalsCountQuery | /activeProposalsCount |
useProposalsQuery | /proposals |
useProposalQuery | /proposal |
useTheoreticalMaxVotingPowerQuery | /theoreticalMaxVotingPower |
useUserVotableProposalsCountPowerQuery | /userVotableProposalsCount |
useUserVotesQuery | /userVotes |
useUserVotingDistributionQuery | /userVotingDistribution |
useVotesQuery | /votes |
useVotingParamsQuery | /params |
useProtocolParametersQuery | /protocolParameters |
usePaidFeesQuery | /paidFees |
Every blockchain transaction that can be created in the On-Chain DAO Governance has its own useAction hook. For example creating a new proposal would look like this:
import {
useCreateProposalAction,
useSignTxAction,
useSubmitTxAction,
} from '@wingriders/governance-frontend-react-sdk'
const CreateProposal = () => {
const {mutateAsync: createProposal, isLoading: isLoadingCreate} = useCreateProposalAction()
const {mutateAsync: signTx, isLoading: isLoadingSign} = useSignTxAction()
const {mutateAsync: submitTx, isLoading: isLoadingSubmit} = useSubmitTxAction()
const handleCreateProposal = async () => {
try {
const buildTxInfo = await createProposal({
...proposal parameters
})
// sign the built transaction
const {cborizedTx, txHash} = await signTx({buildTxInfo})
// submit the signed transaction
await submitTx({cborizedTx})
} catch (e) {
console.error(e)
}
}
Here is the list of actions hooks that is available in @wingriders/governance-frontend-react-sdk
:
action hook | corresponding SDK action |
---|---|
useCancelProposalAction | buildCancelProposalAction |
useCastVoteAction | buildCastVoteAction |
useCreateProposalAction | buildCreateProposalAction |
useConcludeProposalAction | buildConcludeProposalAction |
useSignTxAction | signTxAction |
useSubmitTxAction | submitTxAction |