AIP: x/cw-registry module

[zanicar]

Discussed in https://github.com/orgs/archway-network/discussions/16

^{Originally posted by spoo-bar September 15, 2023}

Abstract

We propose a new module called x/cw-registry which can be used by contract deployers to provide metadata about their contracts.
The module would store contract metadata such as source code, schema, developer contact info.

Context

Cosmwasm does not provide any way for a Cosmwasm smart contract developer to provide any metadata regarding their contracts. This has been explored in x/wasm before ¹, where during contract binary upload, a developer could provide the source code url. This feature was deprecated by Confio due to

1. Field was often unfilled or had erroneous values
2. No tooling to verify the contracts match the given information
   Due to the nature of wasm, it is also not possible to take a look at the source code of a deployed contract.

Once a contract is deployed, it is not easy for external parties to get the contract schema and endpoints², especially so in the case when the contract is closed source or source URL not available. Having this information available on chain would enable the following

1. Make third party tooling of contracts easier to develop, such as code gen for UI
2. General purpose contract interaction tools
3. Indexers and block exploreres could use this information to better display the contract state.
4. CW based multisigs and DAOs can perform contract interactions knowing what the contarct expects.

Currently, there is no way for a user/another developer to know who deployed a contract. In case they would like to contact the developer, there isnt any way to do it beyond the deployer address. Adding a field for security contact would help others report issues.

Most of the Cosmwasm chains run as permissioned Cosmwasm, which allows for the contract source to be connected to the binary in the governance proposal. However, in the permissionless approach of Archway, there is no builtin way to establish this connection.

Architecture

The solution proposed is to develop a new sdk module x/cw-registry which will store the relevant information.
The feature will be an opt in where developers can choose to provide only the necessary info that they deem important. e.g A developer might want to share the schema but might not want to share their source code url as their code is closed source.

Why module instead of modifying archway-wasmd?

1. To keep the archway-wasmd fork as simple in diff as possible so that its easier to upgrade to later versions of wasmd.
2. x/wasmd is purpose scoped to be a contract execution engine. Expanding the module to include code registry features will be beyond its scope.

Why module instead of a name service contract?

The features required for the contract registry could be built either as a chain module or a smart contract. However, going by the philosophy of what a smart contract is, which is to build dapps, it does not make sense to put this feature in a smart contract as this is meant to be a metadata service which augments on the existing smart contract functionality provided by the chain. This feature is tighly coupled with the on chain contract management to be deployed as a smart contract.

Technical Specification

The module would store the following state for Code which has been deployed on chain:

message CodeMetadata {
    // The Code ID of the deployed contract
    uint64 code_id = 1;
    // The information regarding the contract source codebase
    SourceMetadata source = 2;
    // The information regarding the image used to build and optimize the contract binary
    SourceBuilder source_builder = 3;
    // The JSON schema which specifies the interaction endpoints of the contract
    string schema = 4;
    // The contacts of the developers or security incidence handlers 
    repeated string contacts = 5;
}

message SourceMetadata {
    // The link to the code repository. e.g https://github.com/archway-network/archway
    string repository = 1;
    // The tag of the commit message at which the binary was built and deployed. e.g v1.0.2
    string tag = 2;
    // The software license of the smart contract code. e.g Apache-2.0
    string license = 3;
}

message SourceBuilder {
    // Docker image. e.g cosmwasm/rust-optimizer
    string image = 1; 
    // Docker image tag. e.g 0.12.6
    string tag = 2;
    // Name of the generated contract binary. e.g counter.wasm
    string contract_name = 3;
}

This information can only be modified by the user who uploaded the contract binary. Even though Code IDs are unique to binary, we should make these fields modifyable over time to allow for fixing erroneous values and updating contacts.

Consequences

Backwards compatibility

Since the feature is being added as a new module, this should not cause any backwards compatibility issues.

Positive

1. Sets the groundwork for more comprehensive developer tooling
2. Contracts that have registered with source code tag might be given more trusted access in the future.
3. Easier to contact the developers of the contract if a vulnerability is discovered.

Negative

1. The total storage of the chain would increase, especially when storing the contract schema, whick tends to be in 10s of KB.
2. The image builder is not executed to test if the source code matches the given input. This would mean the responsiblity to test if the provided information matches will be provided by off-chain tooling.

Neutral

1. Tools like archwaycli would have to be modified to support this feature and encourage developers to submit these details for their contracts.

Footnotes

1. Question: Why was StoreCode.url removed from the tx msg? ↩

2. Upload JSON schema alongside code contract

↩

[suhasagg]

Kindly some additions to x/cw-registry Module with some kool new features in context of Dapp semantics, transaction traffic metric analysis, customer queries support!

Additions to x/cw-registry Module:

Types:

• ContractMeta: Contains metadata about the contract, like code_id, description, source, source_builder, etc.
• Tag: Represents a tag assigned to a contract, e.g., DeFi, NFT, Gaming.
• Review: Contains user reviews for contracts.
• Rating: Contains user ratings for contracts.

Msg Types:

1. MsgRegisterContract

   Parameters:

   • ContractAddr: Address of the contract.
   • OwnerAddr: Address of the contract owner.
   • Metadata: Metadata related to the contract, such as its description, purpose, and source.
   • ContractName (Optional): The name for the contract. Should be unique.

   Keeper:

   Check if the contract with the given ContractName or ContractAddr is already registered.
   If no conflicts, store the contract details with ContractAddr as the key.

2. MsgAddReview

   Parameters:

   • ContractAddr: Address of the contract.
   • ReviewerAddr: Address of the user adding the review.
   • Comment: The actual review content.
   • Date: date format indicating when the review was added.

   Keeper:

   Ensure that the ContractAddr is registered.
   Verify that the ReviewerAddr hasn't already left a review for the given contract.
   Add the review details to the store with a combination of ContractAddr and ReviewerAddr as the key.

3. MsgRateContract

   Parameters:

   • ContractAddr: Address of the contract.
   • RaterAddr: Address of the user giving the rating.
   • Rating: Numeric rating value (e.g., 1 to 5).
   • Date: date format indicating when the rating was given.

   Keeper:

   Validate that the ContractAddr exists.
   Ensure that the RaterAddr hasn't previously rated the contract.
   Validate the Rating value (within allowed range).
   Store the rating using a composite key of ContractAddr and RaterAddr.

4. MsgAddTag

   Parameters:

   • ContractAddr: Address of the contract.
   • TagName: The tag being added to the contract.

   Keeper:

   Validate the ContractAddr and ensure it's registered.
   Check if the tag already exists for the contract.
   If not, add the tag to the contract's existing tags in the store.

5. MsgSearch

   Parameters:

   • Criteria: Search criteria which can be a combination of tags, reviews, ratings, and other parameters.

   Keeper:

   Parse the Criteria.
   Use an efficient search algorithm(details to be provided) to fetch contracts that match the criteria.
   Return the list of matching contracts.

Queries:

QueryResolveContract
Parameters: ContractName
Handler: Returns the address for the provided contract name.

QueryGetContractRecord
Parameters: ContractAddr
Handler: Returns the details of the given contract address.

Keeper:

• RegisterContract(keeper Keeper, ctx sdk.Context, msg MsgRegisterContract) sdk.Result: Handles the logic for registering a contract.
• ResolveContract(keeper Keeper, ctx sdk.Context, name string) (addr sdk.AccAddress, err Error): Gets the contract address from its name.
• GetContractRecord(keeper Keeper, ctx sdk.Context, addr sdk.AccAddress) (ContractMeta, err Error): Retrieves contract details using its address.
• AddTag(keeper Keeper, ctx sdk.Context, tag Tag) sdk.Result: Assigns a tag to a contract.
• AddReview(keeper Keeper, ctx sdk.Context, review Review) sdk.Result: Adds a review for a specific contract.
• RateContract(keeper Keeper, ctx sdk.Context, rating Rating) sdk.Result: Assigns a rating to a contract.
• SearchContracts(keeper Keeper, ctx sdk.Context, criteria SearchCriteria) ([]ContractMeta, err Error): Searches for contracts based on the given criteria.

Features:
a. Search Function:
Implemented using the MsgSearch message type. Users can query based on tags, name, ratings, etc.

b. Tagging System:
Tags are stored in the keeper with the contract address as the key. Users can add tags using the MsgAddTag message.

c. Rating System:
Ratings are stored in the keeper using a combination of contract address and user address to prevent multiple ratings by the same user for the same contract. The MsgRateContract message handles the addition of ratings.

d. Review System:
Reviews are stored in the keeper using a combination of contract address and user address to prevent multiple reviews by the same user for the same contract. Reviews can be added using the MsgAddReview message.

Errors:

• ErrAlreadyRegistered: Returned if a contract is already registered.
• ErrInvalidNameFormat: For invalid contract name format.

Store Prefixes:

• contractAddrKeyPrefix: "reg_caddr"
• contractRecordKeyPrefix: "reg_crec"

Event:

1. EventContractRegistered
   Triggered when a new contract is registered.

Attributes:

contract_addr: Address of the newly registered contract.
owner_addr: Address of the contract owner.
contract_name: Name of the contract.

2. EventReviewAdded
   Triggered when a review is added to a contract.

Attributes:

contract_addr: Address of the contract being reviewed.
reviewer_addr: Address of the reviewer.
comment: Brief snippet of the review comment

3. EventContractRated
   Triggered when a contract is rated.

Attributes:

contract_addr: Address of the rated contract.
rater_addr: Address of the user who provided the rating.
rating_value: The numeric value of the rating.

5. EventTagAdded
   Triggered when a new tag is added to a contract.

Attributes:

contract_addr: Address of the contract being tagged.
tag_name: The name of the tag added.

metadata.json:
{
"code_id": ,
"description": "MatrixBrainBattery - P2E game and NFT Minting – Ultimate choice for Archway Rewards and Photosynthesis Liquid Staking Algorithm",
"purpose": "E.g. DeFi, NFT, Gaming",
"source": {
"repository": "https://github.com/archway-network/archway",
"tag": "v1.0.2",
"license": "Apache-2.0"
},
"source_builder": {
"image": "cosmwasm/rust-optimizer",
"tag": "0.12.6",
"contract_name": "matrixbrainbattery.wasm"
},
"schema": "",
"contacts": [
"[email protected]",
],
"last_updated": "",
"deployment_cost": "in the native token, e.g. 10 arch"
}

tags.json:
[
"DeFi",
"NFT",
"Gaming"
]

reviews.json:
[
{
"user": "address of the reviewer",
"comment": "Great Game!! Had around 20 gaming sessions this week itself!! :)",
"date": "date format"
}
]

ratings.json:
[
{
"user": "address of the rater",
"rating": 5,
"date": "date format"
}
]

[zanicar]

Excellent, well detailed discussion points, thank you!

Architectural Design Considerations

One thing we have to be very considerate of is the effect / implications of any feature on blockchain state and any potential of future mutability. Blockchain by its nature is immutable, or at least constrained to monotonic state updates, thus any on-chain feature needs to benefit from this attribute or have it as a requirement. Any features that do not are probably better implemented off-chain as a support / auxiliary service... however, these services / features may be another application specific blockchain.

For example, a search feature requires indexing to make search more efficient. Indexing, especially when combined with tags / ratings, are by its nature dynamic. This translates to inefficiency when expressed in on-chain state due to the high mutability of the data and would thus be better to implement as an off-chain service from an architectural perspective.

However, a full blown rating or reputation system is useful across many different scenarios and may possibly present an opportunity for an application specific blockchain, or smart contract complex, that is solely focused on this. Utilizing the protocol it can be coupled to numerous services (both contracts and even other chains) that require a censorship-resistant, verifiable, and pseudonymous rating and reputation system. But, it will come with some serious challenges of its own... scalability springs to mind!

Separate Necessary- from Convenience Features

A great exercise in this regard is to identify each feature as necessary or convenient. A simple way to distinguish this is to simply ask what it would take to achieve the desired outcome. For example, enhanced searching only requires additional indexing to be built or provided across already existing data, thus it can be classified as a convenience feature. Conversely, you may find that a specific convenience feature needs some additional state or metadata, which in turn makes this data a requirement. At this point, examine if it can be separated into distinct necessary and convenience features.

Opportunity: From a Business Perspective

Remember that services constitutes tertiary economic activity. Thus, if a specific convenience service could be of value to a larger number of users / developers within the ecosystem, it may well present an opportunity to build such a service for benefit, just as plumbers and electricians provide services to maintain and improve infrastructure.

This is exactly the reason why Archway provides rewards mechanisms to ensure that any such services, deployed as contracts, have the opportunity to benefit both creator / maintainer, as well as the larger Archway ecosystem.

Conclusion

Hopefully the above provides some additional pointers and insights to help inspire, as well as shape thoughts and designs from an architectural perspective.