Skip to content

feat: Add Contract Metadata Standard #330

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
10d9e merged 8 commits into from
Mar 29, 2022
Merged

feat: Add Contract Metadata Standard #330

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
8802cb5
Initial implementation of contract metadata standard
BenKurrek Mar 3, 2022
27a855d
bumped NEP version and fixed minor typo
BenKurrek Mar 3, 2022
89f044c
removed setter function
BenKurrek Mar 3, 2022
9617b09
Apply suggestions from code review
BenKurrek Mar 4, 2022
1bd0767
Merge branch 'master' into ContractMetadataStandard
BenKurrek Mar 29, 2022
657dd68
Updated to new templates and standard formatting
BenKurrek Mar 29, 2022
4add736
Added example implementation for contract metadata view function
BenKurrek Mar 29, 2022
63c3267
Added more fleshed out implementation
BenKurrek Mar 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions specs/Standards/ContractMetadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Contract Metadata

## [NEP-330](https://github.com/near/NEPs/discussions/329)

Version `1.0.0`

## Summary

The contract metadata is a standard interface to allow for auditing and viewing source code for a deployed smart contract. Implementation of this standard is purely optional but is recommended for developers whose contracts are open source.

## Motivation

There is no trivial way of finding the source code or author of a deployed smart contract. By having a standard that outlines how to view the source code of an arbitrary smart contract, an environment of openness and collaboration is created.

The initial discussion can be found [here](https://github.com/near/NEPs/discussions/329).

## Interface

Metadata applies at the contract level (`ContractMetadata`):

```ts
type ContractMetadata = {
version: string|null, // optional, commit hash being used for the currently deployed wasm. If the contract is not open-sourced, this could also be a numbering system for internal organization / tracking such as "1.0.0" and "2.1.0".
link: string|null, //optional, link to open source code such as a Github repository or a CID to somewhere on IPFS.
Copy link

@agileurbanite agileurbanite Mar 9, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@BenKurrek @austinabell @MaximusHaximus what are your thoughts of adding a system field so we can get some info on what system helped generate the wasm as well. This way we can try to rebuild the wasm and compare the hashes for auditing purposes.

Copy link

@agileurbanite agileurbanite Mar 9, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

system: "local"|string,

Copy link
Contributor

@austinabell austinabell Mar 9, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean, you would need architecture and toolchain version at least. Would the purpose of this be human-readable so someone could try to replicate it? You would also need some commit or version since the link doesn't specify repo links to commit that it was built with

Copy link

@agileurbanite agileurbanite Mar 9, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah ideally i want to be able to reference the source code and source dependencies to help with auditing the contract. Here's what polygon does which is pretty cool: https://polygonscan.com/address/0x217cF04C783818E5b15Ae0723b22Ee2415Ab5fe3#code

Copy link
Contributor Author

@BenKurrek BenKurrek Mar 14, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was assuming that the toolchain version would be kept in the Github repo. I don't really see the need to add a system field but would love other people's opinions

Comment on lines +30 to +32
Copy link
Member

@mfornet mfornet Mar 16, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about adding some sort of organization contact link as well that points to the website of the application, or the developers; potentially with more contact information!

The difference between it and link is that one is to discover the source code, and the other is to discover what is the preferred way to reach developers/community behind this smart contract.

Copy link
Contributor Author

@BenKurrek BenKurrek Mar 16, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this information could be found by utilizing the link since you can open issues or PRs on Github and follow or view the developers' public profiles. The case where I think this might be useful, is if the link is a CID to somewhere on IPFS since you don't have the same ability to reach out or view the developers as you do using Github.

thoughts? @austinabell @agileurbanite

Copy link
Member

@mfornet mfornet Mar 16, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would actually go even further and provide three different fields (similar to crates.io): Homepage, Documentation and Repository + version (to pin the exact version and allow reproducing the exact same binary).

Some services like npm only have Homepage and Repository. (Maybe documentation is a bit too much).

}
```

A new function for querying the metadata must be supported on each smart contract implementing the standard:

```ts
function contract_metadata(): ContractMetadata {}
```

It is up to the author of the contract to keep the version and link up to date when new code is deployed. They can choose to update the metadata with a setter, have it static on the contract, or any other way of their choosing.

### An implementing contract MAY include the following fields on-chain

- `version`: a string that references the specific commit hash or version of the code that is currently deployed on-chain. This can be included regardless of whether or not the contract is open-sourced and can also be used for organizational purposes.
- `link`: a string that references the link to the open source code. This can be anything such as Github or a CID to somewhere on IPFS.

## Future possibilities

- By having a standard outlining metadata for an arbitrary contract, any information that pertains on a contract level can be added based on the requests of the developer community.