many-protocol / specification Goto Github PK

Seems like the file cannot be found but it's not failing the build. Gotta investigate.

we have blockchain.block to return a single block but not an api to retrieve a list of blocks.

the list api should take bound-block-query and return a list of block's maybe

Still learning here, but noticed that the echo function is mentioned in the asciidoc, but not present in the cddl. I think it should look like this. Not sure how else to describe the signed data envelope besides a struct. Looking for feedback. Thank you @hansl .

; tag::echo[]
echo@param = bstr
echo@return = echo

echo = {
    ; Argument bytes sent back
    echo: echo@param,
    ; Signature
    signature: bstr,
}
; end::echo[]

The network was initially named OMNI, so we used o as a prefix for textual serialization of identities. This is not very relevant anymore, so we should change it to m.

• list
• request
• response

Clippy is complaining in the reftests

Checking spectests v0.1.0 (/home/fmorency/dev/specification/reftests)
error: single-character string constant used as pattern
  --> reftests/src/tests.rs:73:27
   |
73 |             .strip_prefix("/")
   |                           ^^^ help: try using a `char` instead: `'/'`
   |
   = note: `-D clippy::single-char-pattern` implied by `-D warnings`
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#single_char_pattern

error: single-character string constant used as pattern
  --> reftests/src/tests.rs:75:37
   |
75 |         format!("{}::{}", p.replace("/", "::"), self.name)
   |                                     ^^^ help: try using a `char` instead: `'/'`
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#single_char_pattern

error: could not compile `spectests` due to 2 previous errors
warning: build failed, waiting for other jobs to finish...
error: build failed

Clarify the specification so those two fields are always optional, i.e., not only when the request/response is too large.

    ; The content of the transaction. This should be a MANY request.
    ; If this field is missing, the transaction was too large to fit here and
    ; should be queried separately. Use the `block.request` endpoint.
    ; If this field is there but empty (not a request), the transaction is
    ; empty or metadata-only (implementation specific).
    ? 1 => bstr .cbor request / bstr .size 0,

    ; The response for the transaction. This should be a MANY response.
    ; If this field is missing, the response might be too large to fit in a single
    ; response.  Use the `block.response` endpoint.
    ; If this field is empty, the transaction is empty or metadata-only
    ; (implementation specific).
    ? 2 => bstr .cbor response / bstr .size 0,

Two identities, really; a subresource identity that only has the subresource id. Let's call them dest-subresource and src-subresource. They fill in the public key hash part with the public key of the from/to identity it contacts (so it's contextual), but they contain only the sub resource id.

We should even encode the subid as a LEB128, so that shorter IDs can take less space.

This will be useful when doing large list of identities, for example with accounts.

I'm new to cddl, but it looks like based on this comment and the specification RFC 8610 there should be a "*" occurence modifier on line 40.

3.2. Occurrence

An optional occurrence indicator can be given in front of a group
entry. It is either (1) one of the characters "?" (optional), "*"
(zero or more), or "+" (one or more) or (2) of the form n*m, where n
and m are optional unsigned integers and n is the lower limit
(default 0) and m is the upper limit (default no limit) of
occurrences.

If no occurrence indicator is specified, the group entry is to occur
exactly once (as if 1*1 were specified). A group entry with an
occurrence indicator matches sequences of name/value pairs that are
composed by concatenating a number of sequences that the basic group
entry matches, where the number needs to be allowed by the occurrence
indicator.

3.5.1. Structs
...
If the addition of more entries not specified by the current
specification is desired, one can add this possibility explicitly:

                     PersonalData = {
                       ? displayName: tstr,
                       NameComponents,
                       ? age: uint,
                       * tstr => any
                     }

                     NameComponents = (
                       ? firstName: tstr,
                       ? familyName: tstr,
                     )

       Figure 7: Personal Data: Example for Extensibility

In the present form it would require one additional field with a text string as a key, and not allow many.

Commit 299a20f broke the rendering of the mint, send and burn CDDL of the Ledger specification, as well as the rendering of put and delete of the Kvstore specification.

We should update the spec to point to the updated CDDL document.

The ManyClient should really be async anyway, and we should not have a single class with all utility functions. Rather, I'd like to have a (e.g.) LedgerClient or EventsClient that contains the utility functions related to their attributes.

The world also doesn't need to contain all clients, only the ones being used, as an additional failure point (ie. if a test uses a client it shouldn't, it should panic and fail).

There is a missing specification and implementation in the blockchain attribute (1) for transaction listing (it only does block right now).

We are still running this project using GitHub Action.

We have a few places where we keep a human-readable and machine-readable memos. These should be streamlined in a single space.

To do:

• Create the specification changes
• Make the changes in many-rs and many-framework.
• Make the changes in albert and many-js.

Server, Neighborhoods, Network, etc. don't have a clear definition. They're also used interchangeably in the specification right now. Let's clarify that.

There should be a way to write tests with a minimum of Rust code or knowledge. This is to help specification writers write tests about their specification while writing the specification (in the same PR).

Cucumber seems to be the ideal framework for this. Tests are written in pre-conditions, actions and assertions, using a language that resembles plain english. This would allow us to write a test for example (not final):

# Requires ledger and ledger_command attributes.
@attribute-2 @attribute-6
Scenario: Ledger can send tokens
    Given an identity id1
    And an identity id2
    And a symbol sym1
    Given id1 has 100 sym1
    When id1 send 50 sym1 to id2
    then the balance of id1 should be 50 sym1
    then the balance of id2 should be 50 sym1

This tracking issue should track the work of writing the framework and the feature files for the current test suite (all the integration tests in https://github.com/liftedinit/many-framework).

And when type checking the CDDL, use the dependency order to build files in the right order.

This can be done in BASH using a bubble sort on dependencies when building the list of files. Or maybe have a special type checker instead of relying on Anweiss' cddl-check. Could depend on its crate.

The new gherkin/cucumber tests need to be added to CI.

The list of metrics that we need to support first:

• Number of accounts in a ledger.

Internal card: https://coda.io/d/Product-Roadmap_dy8ELW7g9Pn/Stories_suajg#Stories_tuL0Q/r51&view=modal

Requirements from Product:

• Should be achievable via node API.
• Should be able to limit the scope to a single network.
• Should return the total number of users for the requested network.
• Should not send additional information about the users.
• Should query at the current block height.

This address would not be able to sign messages, and every messages with this as source would be invalidated. Destination could still be used.

Use cases; putting this address as an owner would mean that nobody can change it (like null address).

MVP is to be able to record immutable data on the blockchain.

No ACL.

No delete.

Should we also provide the friendly human readable symbol in addition to the Identity in the response of ledger.balance?

Currently, we first call ledger.info to get the list of all symbols on the ledger with the friendly token names.
Then, we call ledger.balance with an empty list of symbol identities to retrieve all tokens belonging to one account.
With those two results, we map the identities from ledger.balance to the identities from ledger.info to get the friendly symbol names.

Not a big deal with a small amount of tokens on the ledger, but as the list of tokens grow, it could be concerning.

It would be great if we didn't have to load the full list of tokens before we could display an accounts balance.

Currently, to edit an existing account we have account.addFeatures, account.setDescription, account.addRoles, and account.removeRoles.

In a UI where the UX allows a user to modify multiple accounts' roles at a time before saving, it's possible that this user will be prompted to verify two transactions. Once for account.addRoles and one for account.removeRoles. To determine if account.addRoles and account.removeRoles is called, a diff between the existing data and edited data would have to be made.

Would it make sense to have an API where we could update description and roles in one shot so that a user will only be prompted once to verify the transaction?

Create an attribute spec for words/identity storage.

The attribute should contain endpoints for

• Storing a new words/identity in the storage
• Retrieve an identity from the storage using words