Skip to content

Commit 4febeb3

Browse files
marcocastignolimarcocastignoli
authored
Add Vyper documentation (#27)
* Add Vyper documentation * update styles for AvailableOnlyForSolidityAdmonition * update styles for AvailableOnlyForSolidityAdmonition content * Enhance documentation for immutables and Vyper verification processes * update transformations support in vyper page
1 parent 1ae7cd2 commit 4febeb3

11 files changed

+163
-4
lines changed

‎docs/3. Verification/1.howToVerify.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,12 @@ title: How to Verify Contracts
44
slug: /how-to-verify
55
---
66

7+
import AvailableOnlyForSolidityAdmonition from "../AvailableOnlyForSolidityAdmonition";
8+
79
# How to Verify Contracts
810

11+
<AvailableOnlyForSolidityAdmonition description="Vyper contracts are verifiable only using the dedicated /verify/vyper API enpoint. UI, frameworks and tools don't support Vyper verification via Sourcify yet."/>
12+
913
## Using the UI (legacy)
1014

1115
1. Drag and drop the folder containing your source files and metadata, or add them seperately.

‎docs/3. Verification/2 .fullVsPartialMatch.md

+4
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ title: Full vs Partial Match
44
slug: /full-vs-partial-match
55
---
66

7+
import AvailableOnlyForSolidityAdmonition from "../AvailableOnlyForSolidityAdmonition";
8+
79
# Matches
810

911
A Sourcify match in summary works as follows:
@@ -21,6 +23,8 @@ If the bytecode from recompiling the contract with the given source code files a
2123

2224
## Full (Perfect) Matches
2325

26+
<AvailableOnlyForSolidityAdmonition description="Vyper contracts don't support full matches because Vyper doesn't include the metadata hash in the bytecode."/>
27+
2428
Full matches (sometimes referred as _perfect matches_) refer to the cases when the bytecode of the deployed contract is byte-by-byte the same as compilation output of the given source code files under the compilation settings defined in the [metadata file](/docs/metadata).
2529

2630
This means the contents of the source code files and the compilation settings are exactly the same as when the contract author compiled and deployed the contract. Not even a byte! If you were to add a comment, change a variable or function name, the full match will be broken.

‎docs/3. Verification/3. libraries.md

+4
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,12 @@ title: Libraries
44
slug: /libraries
55
---
66

7+
import AvailableOnlyForSolidityAdmonition from "../AvailableOnlyForSolidityAdmonition";
8+
79
# Verification with Libraries
810

11+
<AvailableOnlyForSolidityAdmonition description="Vyper contracts don't support libraries."/>
12+
913
Normally when a contract has linked libraries these are noted in the `libraries` field in the metadata:
1014

1115
[/partial_match/1/0x2fefbeF4d1445F523941c56349C2414cd5e9675d/metadata.json](https://repo.sourcify.dev/contracts/partial_match/1/0x2fefbeF4d1445F523941c56349C2414cd5e9675d/metadata.json)

‎docs/3. Verification/4. immutables.md

+29-2
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,13 @@ slug: /immutables
66

77
# Verification with Immutable Varibles
88

9-
While Sourcify can verify contracts containing immutable variables, the process is more intricate than verifying contracts that don't have immutables. First, Sourcify recompiles the contract, which produces the runtime bytecode and the `immutableReferences` object. This object indicates the specific position within the execution bytecode where the immutable variables are located. After obtaining these, the next step is to replace all instances of the immutables in both the runtime and deployed bytecodes with zeros. Finally, a direct comparison is made between the two bytecodes to get a full or a partial match.
9+
## Solidity
10+
11+
While Sourcify can verify **Solidity** contracts containing immutable variables, the process is more intricate than verifying contracts that don't have immutables. First, Sourcify recompiles the contract, which produces the runtime bytecode and the `immutableReferences` object. This object indicates the specific position within the execution bytecode where the immutable variables are located. After obtaining these, the next step is to replace all instances of the immutables in both the runtime and deployed bytecodes with zeros. Finally, a direct comparison is made between the two bytecodes to get a full or a partial match.
1012

1113
More details on how immutables affect verification below:
1214

13-
## Immutable variables
15+
### Immutable variables
1416

1517
It is not as straightforward to verify contracts with immutable variables because of their nature. Quoting from the [Solidity docs](https://docs.soliditylang.org/en/v0.8.14/contracts.html#constant-and-immutable-state-variables):
1618

@@ -30,3 +32,28 @@ For example in the bytecode excerpt from the Görli contract 0xbdde4d595f2cdda92
3032
...282565b5050565b7f000000000000000000000000000000000000000000000000000000000000000281565b828054600181600116156101...
3133
☝️
3234
```
35+
36+
## Vyper
37+
38+
Sourcify supports verification of Vyper contracts containing immutable variables. Here's how it works:
39+
40+
1. **CBOR auxdata**: Vyper appends an array in CBOR format at the end of the creation bytecode. This array contains the following elements:
41+
```
42+
[
43+
integrity_hash, // Hash of the contract's source code, included starting with Vyper 0.4.1
44+
runtime_size, // Size of the runtime bytecode
45+
data_sizes, // Array of data section sizes
46+
immutable_size, // Total size of all immutable variables
47+
compiler // Compiler information, e.g. {"vyper": [0, 4, 0]}
48+
]
49+
```
50+
51+
Example CBOR data: `[167, [10], 96, {"vyper": [0, 4, 0]}]`
52+
53+
2. **Locating Immutables**: To find the immutable values:
54+
- Look at the deployed runtime bytecode
55+
- Take the last `immutable_size` bytes - these contain the actual values of the immutables
56+
57+
3. **Verification Process**: To verify the contract:
58+
- Remove the immutable values from the onchain runtime bytecode (by truncating the last `immutable_size` bytes)
59+
- Compare this with the recompiled bytecode

‎docs/3. Verification/8. Etherscan.mdx

+5-1
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,13 @@ title: Import from Etherscan
44
slug: /etherscan
55
---
66

7+
import EtherscanInstances from "./etherscanInstancesTable.tsx";
8+
import AvailableOnlyForSolidityAdmonition from "../AvailableOnlyForSolidityAdmonition";
9+
710
# Import from Etherscan
811

9-
import EtherscanInstances from "./etherscanInstancesTable.tsx";
12+
<AvailableOnlyForSolidityAdmonition description="Import for Etherscan is available only for Solidity contracts."/>
13+
1014

1115
It is possible to import contracts already verified on Etherscan instances.
1216

‎docs/3. Verification/9. vyper.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
id: vyper
3+
title: Vyper verification
4+
slug: /vyper
5+
---
6+
7+
# Vyper verification
8+
9+
Sourcify supports Vyper verification via the `/verify/vyper` API endpoint, you can find more information in the [APIs documentation](/docs/api/).
10+
11+
Vyper doesn't support [metadata](/docs/metadata/), so most of Sourcify features are not available for Vyper.
12+
13+
## Vyper Feature Support
14+
15+
- 🟢 **Partial match**: Sourcify uses the metadata hash as a compilation fingerprint (you can read more about it [here](/docs/full-vs-partial-match)), since Vyper doesn't support metadata, every Vyper match will result in a partial match. Starting from version 0.4.1 Vyper implements a similar concept called [integrity](https://docs.vyperlang.org/en/stable/compiling-a-contract.html#integrity-hash), but Sourcify doesn't support it yet.
16+
- 🟢 **Database transformations**: For more details, see the [Sourcify Database section](/docs/repository/sourcify-database/). Currently, Vyper verification supports `cborAuxdata`, `immutable` and `constructorArguments` transformations.
17+
- 🟢 **Generated metadata**: Sourcify generates a metadata file for Vyper contracts, but it's used only for compatibility with the [Sourcify File Repositories](/docs/repository/file-repositories/).
18+
- 🟡 **IPFS support**: Sourcify automatically uploads all verified contract's sources to IPFS. Even if the files are on IPFS, there is no link to them in the Vyper contract's bytecode. This is because Vyper doesn't include the metadata IPFS CID in the bytecode's auxdata.
19+
- 🔴 **Full match**: Not possible due to lack of metadata support.
20+
- 🔴 **Verification via UI**: Sourcify UI is based on the metadata and uses the statfull `/session/*` API endpoints, currently Sourcify support Vyper verification only via the stateless `/verify/vyper` API endpoint.
21+
- 🔴 **Monitoring**: Monitor listens for `create` operations on many chains. It attempts to fetch the sources of deployed contracts from IPFS using the metadata embedded in the bytecodes. Since Vyper doesn't support metadata, Sourcify can't fetch the sources from IPFS.

‎docs/6. monitoring.md

+4
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,12 @@ title: Monitoring Service
44
slug: /monitoring
55
---
66

7+
import AvailableOnlyForSolidityAdmonition from "./AvailableOnlyForSolidityAdmonition";
8+
79
# Monitoring Service
810

11+
<AvailableOnlyForSolidityAdmonition description="Sourcify monitoring service uses the metadata file to retrieve the source files. Vyper contracts don't support this."/>
12+
913
Sourcify runs a "monitor" that listens to certain chains and checks contract creations (currently only checking tx's with `tx.to === null` and can't catch evm level contract creations). You can see which chains are monitored in [Supported Chains](/docs/chains/) table under "Monitoring" column.
1014

1115
If the monitor notices a contract creation it checks the contract bytecode for the appended metadata hash and will try to fetch the metadata file from Swarm or IPFS. If it succeeds, it further tries to fetch the source files. The source files will be either embedded in the metadata file in text form, or they will have IPFS hashes in the metadata file. If all the files are found, the monitor tries to compile and verify the detected contract with the fetched files.

‎docs/9. metadata.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,12 @@ title: Contract Metadata
44
slug: /metadata
55
---
66

7+
import AvailableOnlyForSolidityAdmonition from "./AvailableOnlyForSolidityAdmonition";
8+
79
# Contract metadata
810

11+
<AvailableOnlyForSolidityAdmonition description="Vyper contracts don't support metadata."/>
12+
913
## Metadata
1014

1115
Since [v0.4.7](https://github.com/ethereum/solidity/releases/tag/v0.4.7) (2016-12-15) Solidity compiler generates an output file called metadata that contains information about the contract and the compilation ([see Solidity docs](https://docs.soliditylang.org/en/latest/metadata.html)). This includes the compiler settings, [contract ABI](https://docs.soliditylang.org/en/latest/abi-spec.html), [NatSpec contract documentation](https://docs.soliditylang.org/en/latest/natspec-format.html), and used source files and their hashes. Sourcify takes full advantage of this information to [fully verify](/docs/full-vs-partial-match) a deployed contract i.e. a byte-by-byte match of the contract. **Metadata file is required for the Sourcify verification** alongside the Solidity source files.

‎docs/98. F.A.Q..md

+1-1
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ Some resources on how it's done:
4747

4848
### Do you support other languages such as Vyper, Fe etc. ?
4949

50-
Sourcify is currently Solidity only.
50+
Sourcify supports Solidity and Vyper only.
5151

5252
### I want to download the complete Sourcify repository, is it possible?
5353

‎docs/AvailableOnlyForSolidityAdmonition.tsx

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
import React from "react";
2+
3+
const SolidityLogo = () => {
4+
return (
5+
<svg
6+
style={{
7+
width: "0.9rem",
8+
verticalAlign: "middle",
9+
marginLeft: "0.8rem",
10+
marginRight: "0.4rem",
11+
}}
12+
viewBox="0 0 100 160"
13+
focusable="false"
14+
>
15+
<path
16+
opacity="0.8"
17+
d="M50 44.3013L25 1L0 44.3013L25 87.6025L50 44.3013Z"
18+
></path>
19+
<path
20+
opacity="0.45"
21+
d="M50 44.3091L75 1.00781L25 1.00781L0 44.3091H50Z"
22+
></path>
23+
<path
24+
opacity="0.6"
25+
d="M75 1.00781L25 1.00781L50 44.3091H100L75 1.00781Z"
26+
></path>
27+
<path
28+
opacity="0.8"
29+
d="M50 115.699L75 159L100 115.699L75 72.3975L50 115.699Z"
30+
></path>
31+
<path
32+
opacity="0.45"
33+
d="M50 115.691L25 158.993H75L100 115.691L50 115.691Z"
34+
></path>
35+
<path
36+
opacity="0.6"
37+
d="M25 158.993H75L50 115.691L0 115.691L25 158.993Z"
38+
></path>
39+
</svg>
40+
);
41+
};
42+
43+
export default ({ description }: { description: string }) => {
44+
return (
45+
<div>
46+
<div
47+
className="theme-admonition theme-admonition-tip alert alert--info"
48+
style={{
49+
marginBottom: "1em",
50+
}}
51+
>
52+
<div
53+
style={{
54+
font: "var(--ifm-heading-font-weight) var(--ifm-h5-font-size)/var(--ifm-heading-line-height) var(--ifm-heading-font-family)",
55+
marginBottom: "0.3rem",
56+
textTransform: "uppercase",
57+
}}
58+
>
59+
<span
60+
style={{
61+
verticalAlign: "middle",
62+
}}
63+
>
64+
Available only for
65+
</span>
66+
<SolidityLogo />
67+
<span
68+
style={{
69+
fontSize: "1.1rem",
70+
verticalAlign: "middle",
71+
textTransform: "capitalize",
72+
color: "#1a1b1c",
73+
}}
74+
>
75+
Solidity
76+
</span>
77+
</div>
78+
<div>
79+
<p style={{ marginBottom: "0" }}>{description}</p>
80+
</div>
81+
</div>
82+
</div>
83+
);
84+
};

‎src/css/custom.css

+3
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,9 @@ html[data-theme="dark"] .navbar__title {
6868
justify-content: center;
6969
}
7070
@import url("https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;1,400&family=VT323&display=swap");
71+
/** Font for Solidity logo */
72+
@import url("https://fonts.cdnfonts.com/css/overpass");
73+
@import url("https://fonts.cdnfonts.com/css/overpass-mono");
7174

7275
.menu__link--active:not(.menu__link--sublist) {
7376
background: var(--ifm-color-primary-lightestest);

0 commit comments

Comments
 (0)