deso-protocol

deso-protocol

Client side typescript/javascript SDK for building web3 applications for the DeSo blockchain.

Installation

npm i deso-protocol

Configuration

import { configure } from 'deso-protocol'; configure({ // Here we indicate the permissions a user will be asked to approve when they // log into your application. You may specify as many or as few permissions up // front as you want. You may choose not to request any permissions up front // and that's okay! Just remember that you will need to request them in your // app progressively, and you can always request as many or as few as you want // using the `requestPermissions` method described in the usage section. // // See more about the spending limit options object here // https://docs.deso.org/for-developers/backend/blockchain-data/basics/data-types#transactionspendinglimitresponse // And See an exhaustive list of transaction types here: // https://github.com/deso-protocol/core/blob/a836e4d2e92f59f7570c7a00f82a3107ec80dd02/lib/network.go#L244 spendingLimitOptions: { // NOTE: this value is in Deso nanos, so 1 Deso * 1e9 GlobalDESOLimit: 1 * 1e9 // 1 Deso // Map of transaction type to the number of times this derived key is // allowed to perform this operation on behalf of the owner public key TransactionCountLimitMap: { BASIC_TRANSFER: 2, // 2 basic transfer transactions are authorized SUBMIT_POST: 4, // 4 submit post transactions are authorized }, } // Optional node uri. Sets the uri for the node that will be used for all // subsequent requests. If not passed it will default to https://node.deso.org nodeURI: 'https://mynode.com', // Optional redirect URI. This is mostly useful for native mobile use cases. // Most web applications will not want to use it. If provided, we do a full // redirect to the identity domain and pass data via query params back to the // provided uri. redirectURI: 'https://mydomain.com/my-redirect-path', // This will be associated with all of the derived keys that your application // authorizes. appName: 'My Cool App', // this is optional, if not passed the default of 1500 will be used. MinFeeRateNanosPerKB: 1000, // THE FOLLOWING CONFIGURATIONS ARE ONLY NEEDED IN A REACT NATIVE CONTEXT /** * An optional storage provider. If not provided, we will assume we're running * in a browser context and localStorage is available. In react native you must * set a storage provider which is likely an async storage instance. */ storageProvider?: Storage | AsyncStorage; /** * An optional function that can be used to customize how the identity url is opened. For * example, if you are using react native, you might want to use the WebBrowser * API to open the url in a system browser window. * @example * ```ts * identityPresenter: async (url) => { * const result = await WebBrowser.openAuthSessionAsync(url); * if (result.type === 'success') { * identity.handleRedirectURI(result.url); * } * }, * ``` */ identityPresenter?: (url: string) => void; })

Usage

See our react examples repo

API

Identity: (logging in and out, creating new accounts, etc)

import { identity } from 'deso-protocol'; // Subscribe to identity state changes (user login/logout, permissions updated, // etc). This is useful for binding your preferred framework's state management // system to the identity instance's internal state. The function you provide to // `subscribe` will be called anytime identity's internal state changes. identity.subscribe((state) => { // The event property is a string value that tells you what triggered the // subscribe call. Useful for setting loading states or otherwise making // decisions about how you want your app to react to identity state. // You can see an exhaustive list of the events here: https://github.com/deso-protocol/deso-js/blob/4d91fd7a66debd2aa0b0b49c0ccb872c0c849d49/src/identity/types.ts#L225 const event = state.event; // The current user object contains the user's current permissions // (TransactionCountLimitMap). This value will be updated when the logged in // user changes or when the permissions change for the current user. Read // more about the transaction count limit map here // https://docs.deso.org/for-developers/backend/blockchain-data/basics/data-types#transactionspendinglimitresponse const currentUser = state.currentUser; // A list of all users that a given user has logged in with (excluding // currentUser). This is useful if you want to show a list of accounts and // provide a way to switch accounts easily. const alernateUsers = state.alternateUsers; }); // Start a login flow await identity.login(); // Start a logout flow await identity.logout(); // Switch users (for apps that manage multiple accounts for a single user). // NOTE: The publicKey here must be a user that has previously logged in. await identity.setActiveUser(publicKey); // Generate a jwt for making authenticated requests via `Authorization` http // header. await identity.jwt(); // Sign and submit a transaction. This is handled for you if you're using any // of the provided transaction creation helpers. But you can also do this yourself // if you have a more complex use case. const tx = await axios.post('https://node.deso.org/api/v0/submit-post'); const submittedTx = await identity.signAndSubmit(tx); // For some use cases, you might want to handle signing, submitting, // and retrying yourself. Here's an example of handling each step of the process // yourself. const postTransaction = await axios.post( 'https://node.deso.org/api/v0/submit-post' ); const signedTx = await identity.signTx(postTransaction.TransactionHex); const submittedTx = await identity.submitTx(signedTx); // Checking for permissions is straightforward. Here we check if our app can // post on behalf of a user Read more about the transaction count limit map here // https://docs.deso.org/for-developers/backend/blockchain-data/basics/data-types#transactionspendinglimitresponse and you can find an exhaustive list // of available transaction types here: https://github.com/deso-protocol/core/blob/a836e4d2e92f59f7570c7a00f82a3107ec80dd02/lib/network.go#L244 // This returns a boolean value synchronously and should be used in a browser context to prevent issues with // popup blockers. const hasPermission = identity.hasPermissions({ TransactionCountLimitMap: { SUBMIT_POST: 1, }, }); // The same as `hasPermissions` but async because the storage provider might be AsyncStorage // This would typically be used in a native mobile (react native) context. const hasPermission = await identity.hasPermissionsAsync({ TransactionCountLimitMap: { SUBMIT_POST: 1, }, }); // Here we request approval for permissions from a user. This will present the // user with the deso identity approve derived key UI. if (!hasPermissions) { await identity.requestPermissions({ TransactionCountLimitMap: { SUBMIT_POST: 1, }, }); } // Encrypt plain text with the recipients public key. This can be subsequently // decrypted using the recipient's private key. const encryptedMessageHex = await identity.encryptMessage( recipientPublicKeyBase58Check, plaintextMsg ); // Decrypt a message returned from any of the message endpoints of the deso // backend messages api. If it is a group message you will need to fetch the // groups the user is a member of and provide them. If it's known that the // message is not a a group message you can pass an empty array for the groups // parameter. // // See the api docs for sending and receiving messages here: // https://docs.deso.org/deso-backend/api/messages-endpoints // // See the api docs for access groups here: // https://docs.deso.org/deso-backend/api/access-group-endpoints const decryptedMessagePlaintext = await identity.decryptMessage( message, accessGroups );

Data: fetching data from a node

import { getUsersStateless, getPostsStateless } from 'deso-protocol'; const users = await getUsersStateless({ PublicKeysBase58Check: [key1, key2, ...rest], }); const posts = await getPostsStateless({ NumToFetch: 20 });

See the backend api documentation for reference. See an exhaustive list of the available data fetching functions here.

Transactions: Writing data to the blockchain

The deso-protocol library will handle signing and submitting transactions for confirmation for you. All you need to do is construct them by providing the raw data.

import { submitPost } from 'deso-protocol'; const txInfo = await submitPost({ UpdaterPublicKeyBase58Check: currentUser.publicKey, BodyObj: { Body: 'My first post on DeSo!', ImageURLs: [], VideoURLs: [], }, });

See the transaction construction api documentation for reference. See an exhaustive list of the available transaction construction functions here

React Native

See REACT-NATIVE.md

Contributing

Pull requests are welcome!

Setup

• Clone this repo

git clone ... cd deso-js

Useful workflows

• Run the test suite

npm run test

• Link local changes into another project

# in the deso-js root directory run npm run link # navigate to your project's root cd $your_project_root_dir # create symlink in node_modules that points to your local copy of deso-protocol npm link deso-protocol