@agoric/cosmic-proto 0.3.1-upgrade-14-dev-c8f9e7b.0 → 0.4.1-orchestration-dev-096c4e8.0

package/README.md

@@ -1,9 +1,223 @@
-# Protobuf Stubs for Cosmic Swingset
+# @agoric/cosmic-proto
 
-This package exports JavaScript and TypeScript generated from Cosmic Swingset
-Protobuf IDL so that clients can communicate with the Agoric chain.
+<p align="center">
+  <img src="https://user-images.githubusercontent.com/545047/188804067-28e67e5e-0214-4449-ab04-2e0c564a6885.svg" width="80"><br />
+    Protobuf interfaces for Agoric on Cosmos
+</p>
 
-Package exports are defined in `exports` and also made available in the
-`swingset/` file path for backwards compatibility.
 
-See also [MAINTAINERS.md](MAINTAINERS.md).
+## install
+
+```sh
+npm install @agoric/cosmic-proto
+```
+## Table of contents
+
+- [Usage](#usage)
+    - [RPC Clients](#rpc-clients)
+    - [Composing Messages](#composing-messages)
+- [Wallets and Signers](#connecting-with-wallets-and-signing-messages)
+    - [Stargate Client](#initializing-the-stargate-client)
+    - [Creating Signers](#creating-signers)
+    - [Broadcasting Messages](#broadcasting-messages)
+- [Advanced Usage](#advanced-usage)
+- [Developing](#developing)
+- [Credits](#credits)
+
+## Usage
+### RPC Clients
+
+```js
+import { agoric } from '@agoric/cosmic-proto';
+
+const { createRPCQueryClient } = agoric.ClientFactory; 
+const client = await createRPCQueryClient({ rpcEndpoint: RPC_ENDPOINT });
+
+const swingsetParams = await client.agoric.swingset.params()
+```
+
+### Composing Messages
+
+Import the `agoric` object from `@agoric/cosmic-proto`. 
+
+```js
+import { agoric } from '@agoric/cosmic-proto';
+
+const {
+    installBundle,
+} = agoric.exchange.v1beta1.MessageComposer.withTypeUrl;
+```
+
+## Connecting with Wallets and Signing Messages
+
+⚡️ For web interfaces, we recommend using [cosmos-kit](https://github.com/cosmology-tech/cosmos-kit). Continue below to see how to manually construct signers and clients.
+
+Here are the docs on [creating signers](https://github.com/cosmology-tech/cosmos-kit/tree/main/packages/react#signing-clients) in cosmos-kit that can be used with Keplr and other wallets.
+
+### Initializing the Stargate Client
+
+Use `getSigningAgoricClient` to get your `SigningStargateClient`, with the proto/amino messages full-loaded. No need to manually add amino types, just require and initialize the client:
+
+```js
+import { getSigningAgoricClient } from '@agoric/cosmic-proto';
+
+const stargateClient = await getSigningAgoricClient({
+  rpcEndpoint,
+  signer // OfflineSigner
+});
+```
+### Creating Signers
+
+To broadcast messages, you can create signers with a variety of options:
+
+* [cosmos-kit](https://github.com/cosmology-tech/cosmos-kit/tree/main/packages/react#signing-clients) (recommended)
+* [keplr](https://docs.keplr.app/api/cosmjs.html)
+* [cosmjs](https://gist.github.com/webmaster128/8444d42a7eceeda2544c8a59fbd7e1d9)
+### Amino Signer
+
+Likely you'll want to use the Amino, so unless you need proto, you should use this one:
+
+```js
+import { getOfflineSignerAmino as getOfflineSigner } from 'cosmjs-utils';
+```
+### Proto Signer
+
+```js
+import { getOfflineSignerProto as getOfflineSigner } 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.
+
+```js
+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 === 'agoric');
+  const signer = await getOfflineSigner({
+    mnemonic,
+    chain
+  });
+```
+### Broadcasting Messages
+
+Now that you have your `stargateClient`, you can broadcast messages:
+
+```js
+const { send } = cosmos.bank.v1beta1.MessageComposer.withTypeUrl;
+
+const msg = send({
+    amount: [
+    {
+        denom: 'coin',
+        amount: '1000'
+    }
+    ],
+    toAddress: address,
+    fromAddress: address
+});
+
+const fee: StdFee = {
+    amount: [
+    {
+        denom: 'coin',
+        amount: '864'
+    }
+    ],
+    gas: '86364'
+};
+const response = await stargateClient.signAndBroadcast(address, [msg], fee);
+```
+
+## Advanced Usage
+
+
+If you want to manually construct a stargate client
+
+```js
+import { OfflineSigner, GeneratedType, Registry } from "@cosmjs/proto-signing";
+import { AminoTypes, SigningStargateClient } from "@cosmjs/stargate";
+
+import { 
+    cosmosAminoConverters,
+    cosmosProtoRegistry,
+    ibcProtoRegistry,
+    ibcAminoConverters,
+    agoricAminoConverters,
+    agoricProtoRegistry
+} from '@agoric/cosmic-proto';
+
+const signer: OfflineSigner = /* create your signer (see above)  */
+const rpcEndpint = 'https://rpc.cosmos.directory/agoric'; // or another URL
+
+const protoRegistry: ReadonlyArray<[string, GeneratedType]> = [
+    ...cosmosProtoRegistry,
+    ...ibcProtoRegistry,
+    ...agoricProtoRegistry
+];
+
+const aminoConverters = {
+    ...cosmosAminoConverters,
+    ...ibcAminoConverters,
+    ...agoricAminoConverters
+};
+
+const registry = new Registry(protoRegistry);
+const aminoTypes = new AminoTypes(aminoConverters);
+
+const stargateClient = await SigningStargateClient.connectWithSigner(rpcEndpoint, signer, {
+    registry,
+    aminoTypes
+});
+```
+
+## Developing
+
+When first cloning the repo:
+
+```
+yarn
+yarn build
+```
+
+For very basic unit tests:
+```
+yarn test
+```
+
+To test with a real network,
+```
+yarn test:live
+```
+
+
+
+
+### Codegen
+
+Protos live in `./proto`. Look inside of `scripts/codegen.cjs` and configure the settings for bundling your SDK into `@agoric/cosmic-proto`:
+
+```
+yarn codegen
+```
+
+### Publishing
+
+Build the types and then publish:
+
+```
+yarn build
+yarn publish
+```
+
+## Related
+
+Checkout these related projects:
+
+* [@cosmology/telescope](https://github.com/cosmology-tech/telescope) Your Frontend Companion for Building with TypeScript with Cosmos SDK Modules.
+* [chain-registry](https://github.com/cosmology-tech/chain-registry) Everything from token symbols, logos, and IBC denominations for all assets you want to support in your application.
+* [cosmos-kit](https://github.com/cosmology-tech/cosmos-kit) Experience the convenience of connecting with a variety of web3 wallets through a single, streamlined interface.
+* [create-cosmos-app](https://github.com/cosmology-tech/create-cosmos-app) Set up a modern Cosmos app by running one command.
+* [interchain-ui](https://github.com/cosmology-tech/interchain-ui) The Interchain Design System, empowering developers with a flexible, easy-to-use UI kit.
+* [starship](https://github.com/cosmology-tech/starship) Unified Testing and Development for the Interchain.
+