Definition of libraries in kadena.js

[alber70g]

Libraries based on what pact-lang-api used to have

• @kadena/cryptography-utils contains encode/decode/hash utils
• @kadena/chainweb-node-client typed js wrapper with fetch to call chainweb-node API endpoints.
  This will probably have some breakdown
  • blockchain wrapper around chainweb-node p2p api endpoints
  • pact https://api.chainweb.com/openapi/pact.html
  • rosetta https://api.chainweb.com/openapi/#tag/rosetta
• @kadena/chainweb-data-client typed js wrapper with fetch to call chainweb-data API endpoints
• @kadena/pactjs-client wrapper around chainweb-node-client with ability to switch environments etc. Removed in favor of @kadena/chainweb-node-client/pact
• @kadena/wallet-client client for wallet to sign, connect, retreive account info, etc
• @kadena/marmalade-client specific client for marmalade/NFTs
• @kadena/types common used typescript definitions. Preferably this will all move to the low-level libraries. Whenever you build something on top of those, you can use those types.
• @kadena/pactjs-utils low level pact utils (like PactNumber, createExp, keySet, ...) Renamed to @kadena/pactjs
• @kadena/chainweaver-client typed js wrapper with fetch to call chainweaver endpoints
• ====
• @kadena/pactjs runtime for generating pact expressions Renamed to @kadena/client
• @kadena/pactjs-cli cli to generate pact contract type definitions and interface to pact client. deployment of contracts, etc
• @kadena/pactjs-generator library that creates typescript definition from contract, template, etc
• .kadena/pactjs-generated library that does not exist on npm.
  It is generated by @kadena/pactjs-cli and @kadena/pactjs-generator and is a dependency of @kadena/pactjs(to be @kadena/client)
• @kadena/transaction-templates a supportive library for transactions. As there is no way to determine from pact alone which caps are needed for a given transaction, and in turn which signatures are needed, we want to provide the community a way to "publish" templates. These templates can be used by @kadena/pactjs-cli to generate the necessary typescript definitions
• packages/kadena.js do not depend on this package, as it's leftovers from when we started with the kadena-community/kadena.js monorepo

@LindaOrtega, @ggobugi27, @jmininger, @buckie can you review the libs and what we think that the contents should be, if that's correct?

// JSON blob that will export all the functions so we can generate the types from this file - chainweaver add button

{
  crypto: { // @kadena/cryptography-utils
    binToHex: binToHex,
    hexToBin: hexToBin,
    base64UrlEncode: b64url.encode,
    base64UrlDecode: b64url.decode,
    base64UrlEncodeArr: b64urlEncodeArr,
    base64UrlDecodeArr: b64urlDecodeArr,
    strToUint8Array: strToUint8Array,
    uint8ArrayToStr: uint8ArrayToStr,
    hash: hash,
    hashBin: hashBin,
    genKeyPair: genKeyPair,
    restoreKeyPairFromSecretKey: restoreKeyPairFromSecretKey,
    sign: sign,
    signHash: signHash,
    verifySig: nacl.sign.detached.verify,
    verifySignature: verifySignature,
    toTweetNaclSecretKey: toTweetNaclSecretKey
  },
  api: { // @kadena/chainweb-node-client
    prepareContCmd: prepareContCmd,
    prepareExecCmd: prepareExecCmd,
    mkSingleCmd: mkSingleCmd,
    mkPublicSend: mkPublicSend
  },
  lang: { 
    mkExp: mkExp, // will be removed, replaced by @kadena/pact-core
    mkMeta: mkMeta, // removed
    mkCap: mkCap // @kadena/chainweb-node-client
  },
  simple: { // @kadena/pact-client or @kadena/pact-core ?
    cont: {
      createCommand: simpleContCommand
    },
    exec: {
      createCommand: simpleExecCommand,
      createLocalCommand: prepareExecCmd,
      createPollRequest: simplePollRequestFromExec,
      createListenRequest: simpleListenRequestFromExec
    }
  },
  fetch: { // @kadena/chainweb-node-client
    send: fetchSend,
    local: fetchLocal,
    poll: fetchPoll,
    listen: fetchListen,
    spv: fetchSPV
  },
  wallet: { // @kadena/wallet-client
    sign: signWallet,
    sendSigned: sendSigned
  },
  cut: {  // @kadena/chainweb-node-client
    current: chainweb.cut.current
  },
  event: { // @kadena/chainweb-node-client
      range: chainweb.event.range,
      recent: chainweb.event.recent,
      stream: chainweb.event.stream,
      height: chainweb.event.height,
      blockHash: chainweb.event.blockHash,
  }  
}

[alber70g]

removed. Let's discuss Pact generator etc in another issue

[LindaOrtega]

Some thoughts:

• pact-core as a name might be confusing since the term is already being used (at least internally) to refer to some of the work going on at https://github.com/kadena-io/pact-model. What about something like pact-generator?
• @kadena/pact-cli I'm not sure I understand the intended purpose of this library. Would this library contain wrapper functions for interacting with the coin contract (and other contracts deployed on chainweb) for example? Or is it intended to be more generalizable to work with any pact contract? If it's the latter, then the name seems appropriate, but if its the former (i.e. only for interaction with public blockchain chainweb smart contracts) I would prefer something like chainweb-pact-cli.
• Tied to the previous point. I think we should have a conversation on how we want to name the different components. Chainweb-deployed smart contracts are using pact, but pact is used not just with chainweb. So my biased association when I hear pact-{some-other-name} is that this is referring to a generalized "thing" that makes use of pact or pact rest api generalizations. But I'm not sure what associations developers have when they hear pact vs chainweb, ect.
• A little bit more on semantics. For pact-cli, I associate cli with a command line tool. Is that the intended purpose/use for this library?

====

Regarding:

@kadena/chainweb-node-client typed js wrapper with fetch to call chainweb-node API endpoints (amongst others https://api.chainweb.com/openapi/pact.html).
@kadena/pact-client wrapper around chainweb-node-client with ability to switch environments etc.

I would switch the name of the two:

@kadena/pact-client typed JS wrapper with fetch to call Pact API endpoints (amongst others https://api.chainweb.com/openapi/pact.html).
@kadena/chainweb-node-client wrapper around pact-client with ability to switch environments etc.

The api endpoints we're discussing here (i.e. send, poll, ect.) are known as Pact Rest API endpoints (See: https://api.chainweb.com/openapi/#tag/pact).

So they can be used to interact with a pact-server (a simple http server that comes with the pact command line installation), any version of chainweb-node, and the private blockchain kuro.

The prefix added to these endpoints is what changes across these different networks.
A pact-server example:

const pactServerApiHost: string = 'http://127.0.0.1:9001'

A devnet example:

const devnetApiHostChain0: string =
  'http://localhost:8080/chainweb/0.0/development/chain/0/pact';

And the request and response types of these endpoints are pretty generalized, except that certain networks will require specific values.

For example, the networkId field in CommandPayload can be null for pact-server, but could be mainnet01 when interacting with the Mainnet version of chainweb-node.

Also, the metadata field in CommandPayload can be null for pact-server, but would need to adhere to the model specified here for chainweb-node.

Currently, some of the functions and type definitions are chainweb-node specific (with the ability to set null) because pact-server will ignore the chainweb-specific types.

But maybe we want to have more generalizable types/functions along with the very specific chainweb types/functions.

[mightybyte]

prepareContCmd, prepareExecCmd, mkSingleCmd, mkPublicSend and similar should probably go in one of the pact libraries. Most likely a lower-level one, as they pretty closely match things defined here: https://api.chainweb.com/openapi/pact.html.

Same thing applies to mkCap, send, local, poll, and listen.

Other than that, I think this list of libraries looks pretty good. I also broadly agree with the thrust of Linda's comments about names.

[alber70g]

We had a meeting addressing the concerns raised in the comments above.

• pact-core as a name might be confusing since the term is already being used (at least internally) to refer to some of the work going on at https://github.com/kadena-io/pact-model. What about something like pact-generator?

We've decided to rename all the pact libs to include js to prevent confusion between libraries with the same name but in other realms (updated comment: #42 (comment))

• @kadena/pact-cli I'm not sure I understand the intended purpose of this library. Would this library contain wrapper functions for interacting with the coin contract (and other contracts deployed on chainweb) for example? Or is it intended to be more generalizable to work with any pact contract? If it's the latter, then the name seems appropriate, but if its the former (i.e. only for interaction with public blockchain chainweb smart contracts) I would prefer something like chainweb-pact-cli.
• A little bit more on semantics. For pact-cli, I associate cli with a command line tool. Is that the intended purpose/use for this library?

It is intende to be more generalizable work with any pact contract. It is to be a CLI with commands like

• pactjs-cli generate-client <arbitrary-contract-definition>
• pactjs-cli deploy <arbitrary-contract-definition> chain{0..19}
• pactjs-cli update-client <arbitrary-contract-definition>
• other pactjs-cli commands that we want to provide as utilities

Where arbitrary-contract-definition can be a url, a template, a json/yaml with some config, etc. (mentioned here: #46)

• Tied to the previous point. I think we should have a conversation on how we want to name the different components. Chainweb-deployed smart contracts are using pact, but pact is used not just with chainweb. So my biased association when I hear pact-{some-other-name} is that this is referring to a generalized "thing" that makes use of pact or pact rest api generalizations. But I'm not sure what associations developers have when they hear pact vs chainweb, ect.

This point is about the difference between pact (the smart contract language), kadena (the blockchain), chainweb (the public implementation of kadena) and other relating things. For this I'd like to make a glossary that clearly defines the terms and their meaning, so there is no confusion between them. (@LindaOrtega can you confirm that using "Kadena blockchain" as term for the underlying technology that allows Chainweb and Kuro to exist, is correct? Or should we use another name? I have seen other terms like ScalableBFT as well)

So, all chainweb related libs are tied to the public Kadena. Maybe we find that it is generic enough that we can use another term for those and these libraries can used both in public Kadena, i.e. Chainweb, and Kuro.

====

Regarding:

@kadena/chainweb-node-client typed js wrapper with fetch to call chainweb-node API endpoints (amongst others https://api.chainweb.com/openapi/pact.html).
@kadena/pact-client wrapper around chainweb-node-client with ability to switch environments etc.

I would switch the name of the two:

@kadena/pact-client typed JS wrapper with fetch to call Pact API endpoints (amongst others https://api.chainweb.com/openapi/pact.html).
@kadena/chainweb-node-client wrapper around pact-client with ability to switch environments etc.

The api endpoints we're discussing here (i.e. send, poll, ect.) are known as Pact Rest API endpoints (See: https://api.chainweb.com/openapi/#tag/pact).

Omitted the rest for brevity

I have changed the name of the two libs. Especially because pact is used in not only Chainweb but also Kuro.

@LindaOrtega Would it make sense to combine those two? Just have everything in @kadena/pactjs-client and have specific implementations inside this package for customization for the permissioned blockchain?

I'd say we want them separate, so anyone who has a permissioned blockchain can implement their own @kadena/chainweb-node-client equivalent. But let's discuss this.

Addition

Maybe it could be an idea that we have pactjs-client that needs a blockchain-client-provider that implements an interface to communicate with the blockchain nodes. So @kadena/chainweb-node-client-provider implements the interface for Chainweb, and another can implement an interface for a permissioned blockchain

[alber70g]

I've renamed @kadena/pactjs-core to @kadena/pactjs to avoid ambiguity. The core part is not really descriptive as this is just one part of the core: the runtime for building expressions. Other parts of the core are the generator and the cli.

I've added

• @kadena/pactjs-generator library that creates typescript definition from contract, template, etc
• @kadena/pactjs-generated library that is generated on the fly by @kadena/pactjs-cli and @kadena/pactjs-generator and is a dependency of @kadena/pactjs

[alber70g]

Thought; maybe we should rename @kadena/pactjs to @kadena/client (similar to @prisma/client) and have our bigNumber and other low-level utils in @kadena/pactjs @ggobugi27 @Randynamic @LindaOrtega @mightybyte

[github-actions]

This issue is stale because it is open for 60 days with no activity