Generate Swagger from Module Manager

[okwme]

Command that reads current module manager in app.go then cycles through each Module's list of Msg Types in order to create a swagger file outlining the requirements for each Msg type. This would allow a front end library to automatically create and sign all message types for a new chain.

[okwme]

would solve cosmos/cosmos-sdk#4322

[okwme]

or generate something like an ABI file from Eth world. A necessary spec to allow js libs to craft Msg Types that can be signed and submitted in transactions.

[tac0turtle]

I believe you are talking about this: cosmos/cosmos-sdk#5038?

[okwme]

#5038 is really cool but not all of what i am referring to. #5038 is another solution to the problem this issue is meant to address.

Basically it is easy to generate Msgs for already common types like send and vote. It's not easy to know how to generate Msgs when dealing with new chains with new Msg types. Generating a swagger file for those new types is great for describing the REST server that may (or may not) be running somewhere. If that REST server is running it will be able to generate those Msgs for you. This is kind of a bad pattern tho, to make a query to a REST server to generate the Msg, then sign it locally, then submit it to a node to be accepted in a block. A better method would be to generate the Msg locally (in whatever client language you want) sign it locally (again in whatever client language you want) then submit it to a public node. That way the client isn't responsible for running any infrastrucutre like the REST server to generate the transactions and will be more likely to be able to access some publicly available submit tx endpoint. For this scenario to happen tho, the js lib needs to know what the Msg types are and what variables are needed, etc. In Eth world they use a json object called the Application Binary Interface (ABI) to do this. It might be possible to generate something similar straight from the swagger file that is useful for a client lib to do this kind of work flow. Otherwise all the information should be present inside of the module manager -> Msg Types that would also be available to generate something like an ABI.

tagging @jordansexton to give a place to add his thoughts wrt js client libs

i realize i might be jumping ahead in trying to solve a problem that doesn't exist yet but i'd like to see client side developer experience not rely on the REST server in the future.

[fedekunze]

This issue should go to the SDK imo then. I think this should be prioritized in the roadmap too

[jackzampolin]

I think @hschoenburg is working on generating type script definitions from Amino that might help with this.

Also the work @jordansexton is doing is planned to be modular and able to handle this.

i realize i might be jumping ahead in trying to solve a problem that doesn't exist yet but i'd like to see client side developer experience not rely on the REST server in the future.

No REST server has been a dream of mine for a while 🤔💭

[fedekunze]

I think @hschoenburg is working on generating type script definitions from Amino that might help with this.

Also the work @jordansexton is doing is planned to be modular and able to handle this.

i.e create an ABI for msg types ?

[okwme]

bingo @fedekunze
i think it's better to begin from the js side though. i'd be curious how @hschoenburg is thinking about the flow for converting the amino types into typrscript definitions. typescript projects have files that describe external types, right? Maybe this file type can already function as the ABI?

[okwme]

ah this is the *.d.ts typescript description file. I guess the file format isn't great for easy parsing. Would be better if it were json or something. It does seem to cover all the necessary info tho:

// Type definitions for [~THE LIBRARY NAME~] [~OPTIONAL VERSION NUMBER~]
// Project: [~THE PROJECT NAME~]
// Definitions by: [~YOUR NAME~] <[~A URL FOR YOU~]>

/*~ This is the module template file. You should rename it to index.d.ts
 *~ and place it in a folder with the same name as the module.
 *~ For example, if you were writing a file for "super-greeter", this
 *~ file should be 'super-greeter/index.d.ts'
 */

/*~ If this module is a UMD module that exposes a global variable 'myLib' when
 *~ loaded outside a module loader environment, declare that global here.
 *~ Otherwise, delete this declaration.
 */
export as namespace myLib;

/*~ If this module has methods, declare them as functions like so.
 */
export function myMethod(a: string): string;
export function myOtherMethod(a: number): number;

/*~ You can declare types that are available via importing the module */
export interface someType {
    name: string;
    length: number;
    extras?: string[];
}

/*~ You can declare properties of the module using const, let, or var */
export const myField: number;

/*~ If there are types, properties, or methods inside dotted names
 *~ of the module, declare them inside a 'namespace'.
 */
export namespace subProp {
    /*~ For example, given this definition, someone could write:
     *~   import { subProp } from 'yourModule';
     *~   subProp.foo();
     *~ or
     *~   import * as yourMod from 'yourModule';
     *~   yourMod.subProp.foo();
     */
    export function foo(): void;
}

[okwme]

compared to an ABI:

pragma solidity >=0.5.0 <0.7.0;


contract Test {
    constructor() public { b = hex"12345678901234567890123456789012"; }
    event Event(uint indexed a, bytes32 b);
    event Event2(uint indexed a, bytes32 b);
    function foo(uint a) public { emit Event(a, b); }
    bytes32 b;
}

[{
"type":"event",
"inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}],
"name":"Event"
}, {
"type":"event",
"inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}],
"name":"Event2"
}, {
"type":"function",
"inputs": [{"name":"a","type":"uint256"}],
"name":"foo",
"outputs": []
}]

[okwme]

Would love to hear @jordansexton 's opinion as well