Skip to main content

Telescope πŸ”­

A "babel for the Cosmos", Telescope is a TypeScript Transpiler for Cosmos Protobufs. Telescope is used to generate libraries for Cosmos blockchains. Simply point to your protobuffer files and create developer-friendly Typescript libraries for teams to build on your blockchain.

The following blockchain libraries (generated by Telescope) are available via npm

πŸŽ₯ Checkout our video playlist to learn how to use telescope!

Table of contents​

Quickstart​

Follow the instructions below to generate a new Typescript package that you can publish to npm.

First, install telescope:

npm install -g @osmonauts/telescope

Generate​

Use the generate command to create a new package.

telescope generate
cd ./your-new-project
yarn

Add Protobufs​

If you have .proto files, simply add them to a ./proto folder.

However, if you want to get started quickly using existing protos from our registry, simply use the install command.

telescope install

It's not necessary, but you may also specify specific packages, e.g.

telescope install @protobufs/osmosis

Transpile​

To create the Typescript files, run the transpile command.

telescope transpile

You should now see some .ts files generated in ./src. These are the real source files used in your application.

Build​

Finally, run install and build to generate the JS and types for publishing your module to npm.

yarn install
yarn build

Now you should have code inside of your ./src folder, ready for publishing via npm publish. Or, if you used the defaults, you can start developing and your code can be imported from ./src/codegen;

Usage

Programmatic Usage​

First add telescope to your devDependencies:

yarn add --dev @osmonauts/telescope

Install helpers and cosmjs dependencies listed here

import { join } from 'path';
import telescope from '@osmonauts/telescope';
import { sync as rimraf } from 'rimraf';

const protoDirs = [join(__dirname, '/../proto')];
const outPath = join(__dirname, '../src/codegen');
rimraf(outPath);

telescope({
protoDirs,
outPath,

// all options are totally optional ;)
options: {
aminoEncoding: {
enabled: true
},
lcdClients: {
enabled: false
},
rpcClients: {
enabled: false,
camelCase: true
},

// you can scope options to certain packages:
packages: {
nebula: {
prototypes: {
typingsFormat: {
useExact: false
}
}
},
akash: {
stargateClients: {
enabled: true;
includeCosmosDefaultTypes: false;
},
prototypes: {
typingsFormat: {
useExact: false
}
}
}
}
}
}).then(()=>{
console.log('✨ all done!');
}).catch(e=>{
console.error(e);
process.exit(1);
})

Options​

Amino Encoding​

optiondescriptiondefaults
aminoEncoding.enabledgenerate amino types and amino converterstrue
aminoEncoding.casingFnset the amino-casing function for a projectsnake()
aminoEncoding.exceptionsset specific aminoType name exceptionssee code
aminoEncoding.typeUrlToAminocreate functions for aminoType name exceptionsundefined

Prototypes Options​

optiondescriptiondefaults
prototypes.enabledenables the generation of proto encoding methodstrue
prototypes.includePackageVarexport a protoPackage variable to indicate package namefalse
prototypes.excluded.packagesexclude a set of packages from transpilationundefined
prototypes.excluded.protosexclude a set of proto files from transpilationundefined
prototypes.fieldDefaultIsOptionalboolean value representing default optionality of fieldfalse
prototypes.useOptionalNullableuse (gogoproto.nullable) values in determining optionalitytrue
prototypes.allowUndefinedTypesboolean value allowing Types to be undefinedfalse
prototypes.optionalQueryParamsboolean value setting queryParams to be optionalfalse
prototypes.optionalPageRequestsboolean value setting PageRequest fields to optionalfalse

Prototypes Methods​

optiondescriptiondefaults
prototypes.methods.encodeboolean to enable encode method on proto objectstrue
prototypes.methods.decodeboolean to enable decode method on proto objectstrue
prototypes.methods.fromJSONboolean to enable fromJSON method on proto objectstrue
prototypes.methods.toJSONboolean to enable toJSON method on proto objectstrue
prototypes.methods.fromPartialboolean to enable fromPartial method on proto objectstrue
prototypes.methods.fromSDKboolean to enable fromSDK method on proto objectsfalse
prototypes.methods.toSDKboolean to enable toSDK method on proto objectsfalse

LCD Client Options​

optiondescriptiondefaults
lcdClients.enabledgenerate LCD clients that can query proto Query messagestrue
lcdClients.bundlewill generate factory bundle aggregate of all LCD Clientstrue
lcdClients.scopedwill generate factory of scoped LCD Clientsundefined
lcdClients.scopedIsExclusivewill allow both scoped bundles and all RPC Clientstrue

See LCD Clients for more info.

RPC Client Options​

optiondescriptiondefaults
rpcClients.enabledgenerate RPC clients that can interact with proto messagestrue
rpcClients.bundlewill generate factory bundle aggregate of all RPC Clientstrue
rpcClients.camelCaseuse camel-case for RPC methods when generating RPC clientstrue
rpcClients.scopedwill generate factory of scoped RPC Clientsundefined
rpcClients.scopedIsExclusivewill allow both scoped bundles and all RPC Clientstrue
rpcClients.enabledServiceswhich services to enable[Msg,Query,Service]

See RPC Clients for more info.

Stargate Client Options​

optiondescriptiondefaults
stargateClients.includeCosmosDefaultTypesif true, will include the cosmjs defaults with stargate clientstrue (except cosmos package)

Typings and Formatting​

optiondescriptiondefaults
prototypes.typingsFormat.useDeepPartialdefaults to true, but if disabled uses the Partial TS typetrue
prototypes.typingsFormat.useExactdefaults to false, but if enabled uses the Exact TS typefalse
prototypes.typingsFormat.timestampuse either date or timestamp for Timestamp proto type"date"
prototypes.typingsFormat.durationuse either duration or string for Duration proto type"duration"

Protobuf parser​

optiondescriptiondefaults
prototypes.parser.keepCasepasses keepCase to protobuf parse() to keep original casingtrue
prototypes.parser.alternateCommentModepasses alternateCommentMode to protobuf parse() methodtrue
prototypes.parser.preferTrailingCommentpasses preferTrailingComment to protobuf parse() methodfalse

Typescript Disabling​

optiondescriptiondefaults
tsDisable.disableAllif true, will include //@ts-nocheck on every output filefalse
tsDisable.patternsif set, will include //@ts-nocheck on matched patterns[]
tsDisable.filesif set, will include //@ts-nocheck on matched files[]

ESLint Disabling​

optiondescriptiondefaults
eslintDisable.disableAllif true, will include /* eslint-disable */ on every output filefalse
eslintDisable.patternsif set, will include /* eslint-disable */ on matched patterns[]
eslintDisable.filesif set, will include /* eslint-disable */ on matched files[]

Bundle​

optiondescriptiondefaults
bundle.enabledbundle all files into a scoped index filetrue

Output​

optiondescriptiondefaults
removeUnusedImportsremoves unused importstrue
classesUseArrowFunctionsclasses use arrow functions instead of bind()ing in constructorsfalse

Types​

Timestamp​

The representation of google.protobuf.Timestamp is configurable by the prototypes.typingsFormat.timestamp option.

Protobuf typeDefault/date='date'date='timestamp'
google.protobuf.TimestampDate{ seconds: Long, nanos: number }

TODO

  • add date='string' option

Duration​

The representation of google.protobuf.Duration is configurable by the prototypes.typingsFormat.duration option.

Protobuf typeDefault/duration='duration'duration='string'
google.protobuf.Duration{ seconds: Long, nanos: number }string

Composing Messages​

This example shows messages from the osmojs, which was built with Telescope.

Import the osmosis object from osmojs. In this case, we're show the messages available from the osmosis.gamm.v1beta1 module:

import { osmosis } from 'osmojs';

const {
joinPool,
exitPool,
exitSwapExternAmountOut,
exitSwapShareAmountIn,
joinSwapExternAmountIn,
joinSwapShareAmountOut,
swapExactAmountIn,
swapExactAmountOut
} = osmosis.gamm.v1beta1.MessageComposer.withTypeUrl;

Now you can construct messages. If you use vscode or another typescript-enabled IDE, you should also be able to use ctrl+space to see auto-completion of the fields required for the message.

import { coin } from '@cosmjs/amino';

const msg = swapExactAmountIn({
sender,
routes,
tokenIn: coin(amount, denom),
tokenOutMinAmount
});

Calculating Fees​

Make sure to create a fee object in addition to your message.

import { coins } from '@cosmjs/amino';

const fee = {
amount: coins(0, 'uosmo'),
gas: '250000'
}

if you are broadcasting multiple messages in a batch, you should simulate your tx and estimate the fee

import { Dec, IntPretty } from '@keplr-wallet/unit';

const gasEstimated = await stargateClient.simulate(address, msgs, memo);
const fee = {
amount: coins(0, 'uosmo'),
gas: new IntPretty(new Dec(gasEstimated).mul(new Dec(1.3)))
.maxDecimals(0)
.locale(false)
.toString()
};

Stargate Clients​

Every module gets their own signing client. This example demonstrates for the osmosis module.

Use getSigningOsmosisClient to get your SigningStargateClient, with the Osmosis proto/amino messages full-loaded. No need to manually add amino types, just require and initialize the client:

import { getSigningOsmosisClient } from 'osmojs';

const client = await getSigningOsmosisClient({
rpcEndpoint,
signer // OfflineSigner
});

Creating Signers​

To broadcast messages, you'll want to use either keplr or an OfflineSigner from cosmjs using mnemonics.

Amino Signer​

Likely you'll want to use the Amino, so unless you need proto, you should use this one:

import { getOfflineSigner as getOfflineSignerAmino } from 'cosmjs-utils';

Proto Signer​

import { getOfflineSigner as getOfflineSignerProto } from 'cosmjs-utils';

WARNING: NOT RECOMMENDED TO USE PLAIN-TEXT MNEMONICS. Please take care of your security and use best practices such as AES encryption and/or methods from 12factor applications.

import { chains } from 'chain-registry';

const mnemonic =
'unfold client turtle either pilot stock floor glow toward bullet car science';
const chain = chains.find(({ chain_name }) => chain_name === 'osmosis');
const signer = await getOfflineSigner({
mnemonic,
chain
});

Broadcasting messages​

Now that you have your client, you can broadcast messages:

import { signAndBroadcast } from '@osmosnauts/helpers';

const res = await signAndBroadcast({
client, // SigningStargateClient
chainId: 'osmosis-1', // use 'osmo-test-5' for testnet
address,
msgs: [msg],
fee,
memo: ''
});

LCD Clients​

For querying data via REST endpoints, you can use LCD Clients. For a better developer experience, you can generate a factory of scoped bundles of all LCD Clients with the lcdClients option.

const options: TelescopeOptions = {
lcdClients: {
enabled: true;
}
};

If you use the lcdClients.scoped array, you can scope to only the modules of your interest.

const options: TelescopeOptions = {
lcdClients: {
enabled: true,
scoped: [
{
dir: 'osmosis',
filename: 'custom-lcd-client.ts',
packages: [
'cosmos.bank.v1beta1',
'cosmos.gov.v1beta1',
'osmosis.gamm.v1beta1'
],
addToBundle: true,
methodName: 'createCustomLCDClient'
},
{
dir: 'evmos',
filename: 'custom-lcd-client.ts',
packages: [
'cosmos.bank.v1beta1',
'cosmos.gov.v1beta1',
'evmos.erc20.v1'
],
addToBundle: true,
methodName: 'createEvmosLCDClient'
}
]
}
};

This will generate a nice helper in the ClientFactory, which you can then use to query multiple modules from a single object:

import { osmosis } from './codegen';

const main = async () => {
const client = await osmosis.ClientFactory.createLCDClient({ restEndpoint: REST_ENDPOINT });

// now you can query the modules
const pool = await client.osmosis.gamm.v1beta1.pool({ poolId: "1" });
const balance = await client.cosmos.bank.v1beta1.allBalances({ address: 'osmo1addresshere' });
};

LCD Clients Classes​

If you want to instantiate a single client, for any module that has a Query type, there will be a LCDQueryClient object:

import { osmosis } from "osmojs";

export const main = async () => {
const requestClient = new LCDClient({ restEndpoint: REST_ENDPOINT });
const client = new osmosis.gamm.v1beta1.LCDQueryClient({ requestClient });
const pools = await client.pools();
console.log(pools);
};

main().then(() => {
console.log('all done')
})

RPC Clients​

For querying data via RPC endpoints, you can use RPC Clients. For a better developer experience, you can generate a factory of scoped bundles of all RPC Clients with the rpcClients option.

const options: TelescopeOptions = {
rpcClients: {
enabled: true
}
};

If you use the rpcClients.scoped array, you can scope to only the modules of your interest.

const options: TelescopeOptions = {
rpcClients: {
enabled: true,
camelCase: true,
scoped: [
{
dir: 'osmosis',
filename: 'osmosis-rpc-client.ts',
packages: [
'cosmos.bank.v1beta1',
'cosmos.gov.v1beta1',
'osmosis.gamm.v1beta1'
],
addToBundle: true,
methodNameQuery: 'createRPCQueryClient',
methodNameTx: 'createRPCTxClient'
}
]
}
};

This will generate helpers createRPCQueryClient and createRPCTxClient in the ClientFactory, which you can then use to query multiple modules from a single object:

import { osmosis } from './proto';

const main = async () => {
const client = await osmosis.ClientFactory.createRPCQueryClient({ rpcEndpoint });

// now you can query the modules
const pool = await client.osmosis.gamm.v1beta1.pool({ poolId: "1" });
const balance = await client.cosmos.bank.v1beta1.allBalances({ address: 'osmo1addresshere' });
};

RPC Client Classes​

If you want to instantiate a single client, you can generate RPC classes with the rpcClients option;

For any module that has a Msg, Query or Service type, a

import { osmosis, cosmos } from 'osmojs';

const MsgClient = osmosis.gamm.v1beta1.MsgClientImpl;
const QueryClient = osmosis.gamm.v1beta1.QueryClientImpl;
const ServiceClient = cosmos.base.tendermint.v1beta1.ServiceClientImpl;

Here is an example of making a query if you want to use the RPC client classes manually:

import { osmosis } from "osmojs";
import { createProtobufRpcClient, QueryClient } from "@cosmjs/stargate";
import { Tendermint34Client } from "@cosmjs/tendermint-rpc";

export const main = async () => {
const tmClient = await Tendermint34Client.connect(RPC_ENDPOINT);
const QueryClientImpl = osmosis.gamm.v1beta1.QueryClientImpl;
const client = new QueryClient(tmClient);
const rpc = createProtobufRpcClient(client);
const queryService = new QueryClientImpl(rpc);
const pools = await queryService.pools({})
console.log(pools);
};

main().then(() => {
console.log('all done')
})

Manually registering types​

This example is with osmosis module in osmojs, but it is the same pattern for any module.

NOTE: this is using @cosmjs/stargate@0.28.4

import {
AminoTypes,
SigningStargateClient
} from '@cosmjs/stargate';
import { Registry } from '@cosmjs/proto-signing';
import { defaultRegistryTypes } from '@cosmjs/stargate';
import { OfflineSigner } from '@cosmjs/proto-signing'
import { osmosis } from 'osmojs';

export const getCustomSigningClient = async ({ rpcEndpoint, signer }: { rpcEndpoint: string, signer: OfflineSigner }) => {
// registry
const registry = new Registry(defaultRegistryTypes);

// aminotypes
const aminoTypes = new AminoTypes({
...osmosis.gamm.v1beta1.AminoConverter,
...osmosis.lockup.AminoConverter,
...osmosis.superfluid.AminoConverter
});

// load the
osmosis.gamm.v1beta1.load(registry);
osmosis.lockup.load(registry);
osmosis.superfluid.load(registry);

const client = await SigningStargateClient.connectWithSigner(
rpcEndpoint,
signer,
{ registry, aminoTypes }
);

return client;
};

CosmWasm​

Generate TypeScript SDKs for your CosmWasm smart contracts by using the cosmwasm option on TelescopeOptions. The cosmwasm option is actually a direct reference to the TSBuilderInput object, for the most up-to-date documentation, visit @cosmwasm/ts-codegen.

import { TSBuilderInput } from '@cosmwasm/ts-codegen';
const options: TelescopeOptions = {
cosmwasm: {
contracts: [
{
name: 'SG721',
dir: './path/to/sg721/schema'
},
{
name: 'Minter',
dir: './path/to/Minter/schema'
}
],
outPath: './path/to/code/src/'
}
};

Dependencies​

If you don't use the boilerplate, you will need to manually install

  • @cosmjs/amino
  • @cosmjs/proto-signing
  • @cosmjs/stargate
  • @cosmjs/tendermint-rpc
yarn add @cosmjs/amino @cosmjs/proto-signing @cosmjs/stargate @cosmjs/tendermint-rpc

If you use the LCD Client generation, you'll need to add

  • @osmonauts/lcd
yarn add @osmonauts/lcd

Troubleshooting​

Create React App​

CRA requires that you update Webpack configurations:

https://github.com/cosmos/cosmjs/blob/656e02374898afe755e980e93390591b4b65fd86/README.md#webpack-configs

Here is an example of a config-overrides.js:

https://github.com/pyramation/osmosis-ui/blob/main/config-overrides.js

Babel​

This should not be an issue, but if you experience problems with syntax or are not using preset-env, you may need these babel plugins:

Developing​

Initial setup​

yarn 
yarn bootstrap

Building​

yarn build

Tests​

Then cd into a package and run the tests

cd ./packages/ast
yarn test:watch

Generators​

See our plugin generators.

Sponsors​

Kudos to our sponsors:

  • Osmosis funded the creation of Telescope.

Checkout these related projects:

Credits​

πŸ›  Built by Cosmology β€”Β if you like our tools, please consider delegating to our validator βš›οΈ

Thanks to these engineers, teams and projects for inspiring Telescope:

Disclaimer​

AS DESCRIBED IN THE TELESCOPE LICENSES, THE SOFTWARE IS PROVIDED β€œAS IS”, AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating Telescope will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the Telescope code or Telescope CLI, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.