Merge pull request #148 from kommitters/v0.8

Release v0.8.0

CHANGELOG.md

@@ -1,49 +1,55 @@
 # Changelog
 
+## 0.8.0 (30.11.2022)
+
+- Added [PACT Command Behaviour](https://github.com/kommitters/kadena.ex/issues/132)
+- Added [Execution Command](https://github.com/kommitters/kadena.ex/issues/134)
+- [Refactor ExecCommand and Types.KeyPair ](https://github.com/kommitters/kadena.ex/pull/147)
+
 ## 0.7.0 (09.11.2022)
 
-* Added JSONPayload protocol
-* Implemented JSONPayload protocol in [LocalRequestBody](https://github.com/kommitters/kadena.ex/issues/119)
-* Implemented JSONPayload protocol in [SendRequestBody](https://github.com/kommitters/kadena.ex/issues/117)
-* Implemented JSONPayload protocol in [PollRequestBody](https://github.com/kommitters/kadena.ex/issues/123)
-* Implemented JSONPayload protocol in [ListenRequestBody](https://github.com/kommitters/kadena.ex/issues/124)
-* Implemented JSONPayload protocol in [SPVRequestBody](https://github.com/kommitters/kadena.ex/issues/125)
+- Added JSONPayload protocol
+- Implemented JSONPayload protocol in [LocalRequestBody](https://github.com/kommitters/kadena.ex/issues/119)
+- Implemented JSONPayload protocol in [SendRequestBody](https://github.com/kommitters/kadena.ex/issues/117)
+- Implemented JSONPayload protocol in [PollRequestBody](https://github.com/kommitters/kadena.ex/issues/123)
+- Implemented JSONPayload protocol in [ListenRequestBody](https://github.com/kommitters/kadena.ex/issues/124)
+- Implemented JSONPayload protocol in [SPVRequestBody](https://github.com/kommitters/kadena.ex/issues/125)
 
 ## 0.6.1 (27.10.2022)
 
-* Bump ossf/scorecard-action to v2.0.6
+- Bump ossf/scorecard-action to v2.0.6
 
 ## 0.6.0 (26.10.2022)
 
-* Added [Kadena Chainweb Client](https://github.com/kommitters/kadena.ex/issues/59) functions
-* Added [Chainweb Pact Behaviour](https://github.com/kommitters/kadena.ex/issues/96)
-* Added [Error struct](https://github.com/kommitters/kadena.ex/pull/111) for the `Chainweb.Client` boundary
+- Added [Kadena Chainweb Client](https://github.com/kommitters/kadena.ex/issues/59) functions
+- Added [Chainweb Pact Behaviour](https://github.com/kommitters/kadena.ex/issues/96)
+- Added [Error struct](https://github.com/kommitters/kadena.ex/pull/111) for the `Chainweb.Client` boundary
 
 ## 0.5.0 (21.10.2022)
 
-* Added [Kadena Pact](https://github.com/kommitters/kadena.ex/issues/55) functions
+- Added [Kadena Pact](https://github.com/kommitters/kadena.ex/issues/55) functions
 
 ## 0.4.0 (17.10.2022)
 
-* Added [Kadena Crypto](https://github.com/kommitters/kadena.ex/issues/51) functions
+- Added [Kadena Crypto](https://github.com/kommitters/kadena.ex/issues/51) functions
 
 ## 0.3.0 (13.10.2022)
 
 We finished the implementation of initial types on the `Kadena.Types` boundary.
 
-* Added [PactCommand types](https://github.com/kommitters/kadena.ex/issues/13)
-* Added [PactAPI types](https://github.com/kommitters/kadena.ex/issues/17)
-* Added [SignCommand types](https://github.com/kommitters/kadena.ex/issues/18)
+- Added [PactCommand types](https://github.com/kommitters/kadena.ex/issues/13)
+- Added [PactAPI types](https://github.com/kommitters/kadena.ex/issues/17)
+- Added [SignCommand types](https://github.com/kommitters/kadena.ex/issues/18)
 
 ## 0.2.0 (11.10.2022)
 
 We started the implementation of initial types on the `Kadena.Types` boundary.
 
-* Added [Base types](https://github.com/kommitters/kadena.ex/issues/11)
-* Added [PactValue types](https://github.com/kommitters/kadena.ex/issues/15)
-* Added [SignCommand types](https://github.com/kommitters/kadena.ex/issues/16)
-* Added [KeyPair types](https://github.com/kommitters/kadena.ex/issues/12)
+- Added [Base types](https://github.com/kommitters/kadena.ex/issues/11)
+- Added [PactValue types](https://github.com/kommitters/kadena.ex/issues/15)
+- Added [SignCommand types](https://github.com/kommitters/kadena.ex/issues/16)
+- Added [KeyPair types](https://github.com/kommitters/kadena.ex/issues/12)
 
 ## 0.1.0 (08.09.2022)
 
-* Initial release
+- Initial release

README.md

@@ -1,4 +1,5 @@
 # Kadena.ex
+
 ![Build Badge](https://img.shields.io/github/workflow/status/kommitters/kadena.ex/Kadena%20CI/main?style=for-the-badge)
 [![Coverage Status](https://img.shields.io/coveralls/github/kommitters/kadena.ex?style=for-the-badge)](https://coveralls.io/github/kommitters/kadena.ex)
 [![Version Badge](https://img.shields.io/hexpm/v/kadena?style=for-the-badge)](https://hexdocs.pm/kadena)
@@ -9,11 +10,11 @@
 
 ## What can you do with Kadena.ex?
 
-* Construct commands for transactions.
-* Implement cryptography required by the network.
-* Interacting with public network endpoints:
-    - listen, local, poll, send, spv, cut.
-* Send, test and update smart contracts on the network.
+- Construct commands for transactions.
+- Implement cryptography required by the network.
+- Interacting with public network endpoints:
+  - listen, local, poll, send, spv, cut.
+- Send, test and update smart contracts on the network.
 
 ## Installation
 
@@ -22,20 +23,21 @@ Add `kadena` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:kadena, "~> 0.7.0"}
+    {:kadena, "~> 0.8.0"}
   ]
 end
 ```
 
 ## Roadmap
 
-The latest updated branch to target a PR is `v0.7`
+The latest updated branch to target a PR is `v0.9`
 
 You can see a big picture of the roadmap here: [**ROADMAP**][roadmap]
 
 ### What we're working on now 🎉
 
-- [Kadena Chainweb](https://github.com/kommitters/kadena.ex/issues/57)
+- [Chainweb](https://github.com/kommitters/kadena.ex/issues/57)
+- [Pact Commands Builder](https://github.com/kommitters/kadena.ex/issues/131)
 
 ### Done - What we've already developed! 🚀
 
@@ -65,6 +67,156 @@ You can see a big picture of the roadmap here: [**ROADMAP**][roadmap]
 
 ---
 
+## Building Commands
+
+This library allows to build command payloads in a composable and semantic manner.
+These commands are intended to be used as the request body to the Pact API endpoints.
+
+There are two type of commands:
+
+- [`Execution`](#execution-command)
+- `Continuation`.
+
+### Execution Command
+
+To create an execution command is needed:
+
+- [NetworkID](#networkid)
+- [Code](#code)
+- [Nonce](#nonce)
+- [EnvData](#envdata) (optional)
+- [MetaData](#metadata)
+- [KeyPairs](#keypair)
+- [Signers](#signerslist)
+
+The following example shows how to create an execution command:
+
+```elixir
+Kadena.Pact.ExecCommand.new()
+  |> Kadena.Pact.ExecCommand.set_network(network_id)
+  |> Kadena.Pact.ExecCommand.set_code(code)
+  |> Kadena.Pact.ExecCommand.set_nonce(nonce)
+  |> Kadena.Pact.ExecCommand.set_data(env_data)
+  |> Kadena.Pact.ExecCommand.set_metadata(keypair)
+  |> Kadena.Pact.ExecCommand.add_keypair(keypair)
+  |> Kadena.Pact.ExecCommand.add_signers(signers_list)
+  |> Kadena.Pact.ExecCommand.build()
+```
+
+#### NetworkID
+
+There are three options allowed to set a NetworkID:
+
+- `:testnet04`
+- `:mainnet01`
+- `:development`
+
+#### Code
+
+String value that represents the Pact code to execute in the `Execution Command`.
+
+#### Nonce
+
+String value to ensure unique hash. You can use current timestamp.
+
+#### EnvData
+
+A map must be provided to create an environment data, for example:
+
+```elixir
+data = %{
+  accounts_admin_keyset: [
+    "ba54b224d1924dd98403f5c751abdd10de6cd81b0121800bf7bdbdcfaec7388d"
+  ]
+}
+
+Kadena.Types.EnvData.new(data)
+```
+
+#### MetaData
+
+To create a MetaData:
+
+```elixir
+raw_metadata = [
+  creation_time: 0,
+  ttl: 0,
+  gas_limit: 2500,
+  gas_price: 1.0e-2,
+  sender: "account_name",
+  chain_id: "0"
+]
+
+Kadena.Types.MetaData.new(raw_metadata)
+```
+
+#### KeyPairs
+
+There are two ways to get a keypair:
+
+```elixir
+# generate a random keypair
+{:ok, %Kadena.Types.KeyPair{} = keypair} = Kadena.Cryptography.KeyPair.generate()
+
+# derive a keypair from a secret key
+secret_key = "secret_key_value"
+{:ok, %Kadena.Types.KeyPair{} = keypair} = Kadena.Cryptography.KeyPair.from_secret_key(secret_key)
+```
+
+
+**KeyPairs with Capabilites**
+
+Creating a keypair with capabilities:
+
+```elixir
+clist =
+  Kadena.Types.CapsList.new([
+    [name: "gas", args: ["COIN.gas", 0.02]],
+    [name: "transfer", args: ["COIN.transfer", "key_1", 50, "key_2"]]
+  ])
+
+keypair_values = [
+  pub_key: "pub_key_value",
+  secret_key: "secret_key_value",
+  clist: clist
+]
+
+Kadena.Types.KeyPair.new(keypair_values)
+```
+
+Adding capabilities to existing keypair:
+```elixir
+clist =
+  Kadena.Types.CapsList.new([
+    [name: "gas", args: ["COIN.gas", 0.02]],
+    [name: "transfer", args: ["COIN.transfer", "key_1", 50, "key_2"]]
+  ])
+
+
+secret_key = "secret_key_value"
+{:ok, %Kadena.Types.KeyPair{} = keypair} = Kadena.Cryptography.KeyPair.from_secret_key(secret_key)
+
+keypair_with_clist = Kadena.Types.KeyPair.add_caps(keypair, clist)
+```
+
+#### SignersList
+
+There are two ways to create a list of signers:
+
+```elixir
+# with Keywords
+signer1 = [pub_key: "pub_key_1"]
+signer2 = [pub_key: "pub_key_2"]
+
+# with Signer structs
+signer1 = Kadena.Types.Signer.new([pub_key: "pub_key_1"])
+signer2 = Kadena.Types.Signer.new([pub_key: "pub_key_2"])
+
+Kadena.Types.SignersList.new([signer1, signer2])
+```
+
+---
+
 ## Development
 
 - Install any Elixir version above 1.13.

lib/pact/command/command.ex

@@ -0,0 +1,45 @@
+defmodule Kadena.Pact.Command do
+  @moduledoc """
+  Specifies contracts to build PACT command requests.
+  """
+
+  alias Kadena.Pact.ExecCommand
+  alias Kadena.Types.{ChainID, Command, KeyPair, MetaData, NetworkID, Signer, SignersList}
+
+  @type cmd :: Command.t()
+  @type network_id :: NetworkID.t()
+  @type chain_id :: ChainID.t()
+  @type cont_request :: struct()
+  @type exec_request :: ExecCommand.t()
+  @type cmd_request :: cont_request() | exec_request()
+
+  @type string_value :: String.t()
+  @type meta_data :: MetaData.t()
+  @type keypair :: KeyPair.t()
+  @type keypairs_list :: list(keypair())
+  @type signer :: Signer.t()
+  @type signers_list :: list(signer()) | SignersList.t()
+  @type hash :: String.t()
+
+  @callback new() :: cmd_request()
+  @callback set_network(cmd :: cmd_request(), network :: atom()) :: cmd_request()
+  @callback set_data(cmd :: cmd_request(), data :: map()) :: cmd_request()
+  @callback set_nonce(cmd :: cmd_request(), nonce :: string_value()) :: cmd_request()
+  @callback set_metadata(cmd :: cmd_request(), meta_data :: meta_data()) :: cmd_request()
+  @callback add_keypair(cmd :: cmd_request(), keypair :: keypair()) :: cmd_request()
+  @callback add_keypairs(cmd :: cmd_request(), keypairs :: keypairs_list()) :: cmd_request()
+  @callback add_signer(cmd :: cmd_request(), signer :: signer()) :: cmd_request()
+  @callback add_signers(cmd :: cmd_request(), signers :: signers_list()) :: cmd_request()
+  @callback set_code(cmd :: exec_request(), code :: string_value()) :: exec_request()
+  @callback set_pact_tx_hash(cmd :: cont_request(), hash :: hash()) :: cont_request()
+  @callback set_step(cmd :: cont_request(), step :: integer()) :: cont_request()
+  @callback set_proof(cmd :: cont_request(), proof :: string_value()) :: cont_request()
+  @callback set_rollback(cmd :: cont_request(), rollback :: boolean()) :: cont_request()
+  @callback build(cmd :: cmd_request()) :: cmd()
+
+  @optional_callbacks set_code: 2,
+                      set_pact_tx_hash: 2,
+                      set_step: 2,
+                      set_proof: 2,
+                      set_rollback: 2
+end