Skip to content

Commit

Permalink
docs: Migrate Precompiles chapter to inline .sol API docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@matevz
matevz committed Dec 18, 2023
1 parent 7c4fe94 commit 16d8498
Show file tree
Hide file tree
Showing 12 changed files with 478 additions and 469 deletions.
13 changes: 11 additions & 2 deletions contracts/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,24 @@ $ pnpm install @oasisprotocol/sapphire-contracts
Once installed, you can import Sapphire contracts.

```solidity
import {Enclave} from "@oasisprotocol/sapphire-contracts/contracts/OPL.sol";
pragma solidity ^0.8.13;
import "oasisprotocol/sapphire-contracts/contracts/Sapphire.sol";
contract Test {
constructor() {}
function test() public view returns (bytes32) {
return Sapphire.deriveSymmetricKey("public key as bytes32", "private key as bytes32");
}
}
```

## Documentation

See the user's guide for [Sapphire](https://docs.oasis.io/dapp/sapphire/) and
[OPL](https://docs.oasis.io/dapp/opl/).

API reference is available at [api.docs.oasis.io](https://docs.oasis.io/sol/sapphire-contracts).
API reference is available at [api.docs.oasis.io](https://api.docs.oasis.io/sol/sapphire-contracts).

## Contribute

Expand Down
29 changes: 16 additions & 13 deletions contracts/contracts/ConsensusUtils.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,20 +12,23 @@ type StakingSecretKey is bytes32;

/**
* @title Consensus-level utilities
* @dev Generate Oasis wallets for use with staking at the consensus level
* @notice Generate Oasis wallets for use with staking at the consensus level.
*/
library ConsensusUtils {
/// The unique context for v0 staking account addresses.
/// https://github.com/oasisprotocol/oasis-core/blob/master/go/staking/api/address.go#L16
/**
* @notice The unique context for v0 staking account addresses.
* @custom:see @oasisprotocol/oasis-core :: go/staking/api/address.go
*/
string private constant ADDRESS_V0_CONTEXT_IDENTIFIER =
"oasis-core/address: staking";
uint8 private constant ADDRESS_V0_CONTEXT_VERSION = 0;

/**
* @dev Generate a random Ed25519 wallet for Oasis consensus-layer staking
* @param personalization Optional user-specified entropy
* @return publicAddress Public address of the keypair
* @return secretKey Secret key for the keypair
* @notice Generate a random Ed25519 wallet for Oasis consensus-layer
* staking.
* @param personalization Optional user-specified entropy.
* @return publicAddress Public address of the keypair.
* @return secretKey Secret key for the keypair.
*/
function generateStakingAddress(bytes memory personalization)
internal
Expand All @@ -47,8 +50,8 @@ library ConsensusUtils {
}

/**
* @dev Derive the staking address from the public key
* @param ed25519publicKey Ed25519 public key
* @notice Derive the staking address from the public key.
* @param ed25519publicKey Ed25519 public key.
*/
function _stakingAddressFromPublicKey(bytes32 ed25519publicKey)
internal
Expand All @@ -64,10 +67,10 @@ library ConsensusUtils {
}

/**
* @dev Derive an Oasis-style address
* @param contextIdentifier Domain separator
* @param contextVersion Domain version
* @param data Public point of the keypair
* @notice Derive an Oasis-style address.
* @param contextIdentifier Domain separator.
* @param contextVersion Domain version.
* @param data Public point of the keypair.
*/
function _addressFromData(
string memory contextIdentifier,
Expand Down
23 changes: 12 additions & 11 deletions contracts/contracts/EIP155Signer.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@ library EIP155Signer {
}

/**
* Encode a signed EIP-155 transaction
* @param rawTx Transaction which was signed
* @param rsv R, S & V parameters of signature
* @notice Encode a signed EIP-155 transaction.
* @param rawTx Transaction which was signed.
* @param rsv R, S & V parameters of signature.
*/
function encodeSignedTx(EthTx memory rawTx, SignatureRSV memory rsv)
internal
Expand All @@ -43,10 +43,11 @@ library EIP155Signer {
}

/**
* Sign a raw transaction, which will then need to be encoded to include the signature
* @param rawTx Transaction to sign
* @param pubkeyAddr Ethereum address of secret key
* @param secretKey Secret key used to sign
* @notice Sign a raw transaction, which will then need to be encoded to
* include the signature.
* @param rawTx Transaction to sign.
* @param pubkeyAddr Ethereum address of secret key.
* @param secretKey Secret key used to sign.
*/
function signRawTx(
EthTx memory rawTx,
Expand All @@ -64,10 +65,10 @@ library EIP155Signer {
}

/**
* Sign a transaction, returning it in EIP-155 encoded form
* @param publicAddress Ethereum address of secret key
* @param secretKey Secret key used to sign
* @param transaction Transaction to sign
* @notice Sign a transaction, returning it in EIP-155 encoded form.
* @param publicAddress Ethereum address of secret key.
* @param secretKey Secret key used to sign.
* @param transaction Transaction to sign.
*/
function sign(
address publicAddress,
Expand Down
62 changes: 35 additions & 27 deletions contracts/contracts/EthereumUtils.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,9 @@ library EthereumUtils {
error k256DeriveY_Invalid_Prefix_Error();

/**
* Recover Y coordinate from X coordinate and sign bit
* @param prefix 0x02 or 0x03 indicates sign bit of compressed point
* @param x X coordinate
* @notice Recover Y coordinate from X coordinate and sign bit.
* @param prefix 0x02 or 0x03 indicates sign bit of compressed point.
* @param x X coordinate.
*/
function k256DeriveY(uint8 prefix, uint256 x)
internal
Expand All @@ -73,10 +73,10 @@ library EthereumUtils {
error k256Decompress_Invalid_Length_Error();

/**
* Decompress SEC P256 k1 point
* @param pk 33 byte compressed public key
* @return x coordinate
* @return y coordinate
* @notice Decompress SEC P256 k1 point.
* @param pk 33 byte compressed public key.
* @return x X coordinate.
* @return y Y coordinate.
*/
function k256Decompress(bytes memory pk)
internal
Expand All @@ -101,10 +101,10 @@ library EthereumUtils {
}

/**
* Convert SEC P256 k1 curve point to Ethereum address
* @param x coordinate
* @param y coordinate
* @custom:see https://gavwood.com/paper.pdf (212)
* @notice Convert SEC P256 k1 curve point to Ethereum address.
* @param x X coordinate.
* @param y Y coordinate.
* @custom:see https://gavwood.com/paper.pdf (pp. 212)
*/
function toEthereumAddress(uint256 x, uint256 y)
internal
Expand All @@ -119,17 +119,22 @@ library EthereumUtils {
error DER_Split_Error();

/**
* Extracts the `r` and `s` parameters from a DER encoded ECDSA signature.
* @notice Extracts the `r` and `s` parameters from a DER encoded ECDSA
* signature.
*
* The signature is an ASN1 encoded SEQUENCE of the variable length `r` and `s` INTEGERs.
* The signature is an ASN1 encoded SEQUENCE of the variable length `r` and
* `s` INTEGERs.
*
* ```
* | 0x30 | len(z) | 0x02 | len(r) | r | 0x02 | len(s) | s | = hex value
* | 1 | 1 | 1 | 1 | 1-33 | 1 | 1 | 1-33 | = byte length
* ```
*
* If the highest bit of either `r` or `s` is set, it will be prefix padded with a zero byte
* There is exponentially decreasing probability that either `r` or `s` will be below 32 bytes.
* There is a very high probability that either `r` or `s` will be 33 bytes.
* This function only works if either `r` or `s` are 256bits or lower.
* If the highest bit of either `r` or `s` is set, it will be prefix padded
* with a zero byte. There is exponentially decreasing probability that
* either `r` or `s` will be below 32 bytes. There is a very high
* probability that either `r` or `s` will be 33 bytes. This function only
* works if either `r` or `s` are 256bits or lower.
*
* @param der DER encoded ECDSA signature
* @return rsv ECDSA R point X coordinate, and S scalar
Expand Down Expand Up @@ -214,13 +219,15 @@ library EthereumUtils {
}

/**
* Convert a Secp256k1PrehashedKeccak256 signature to one accepted by ecrecover
* @param pubkey 33 byte compressed public key
* @param digest 32 byte pre-hashed message digest
* @param signature ASN.1 DER encoded signature, as returned from `Sapphire.sign`
* @return pubkeyAddr 20 byte Ethereum address
* @return rsv Ethereum EcDSA RSV signature values
* @custom:see https://gavwood.com/paper.pdf (206)
* @notice Convert a Secp256k1PrehashedKeccak256 signature to one accepted
* by ecrecover.
* @param pubkey 33 byte compressed public key.
* @param digest 32 byte pre-hashed message digest.
* @param signature ASN.1 DER encoded signature, as returned from
* [`Sapphire.sign`](../Sapphire.sol/library.Sapphire.md#sign).
* @return pubkeyAddr 20 byte Ethereum address.
* @return rsv Ethereum EcDSA RSV signature values.
* @custom:see https://gavwood.com/paper.pdf (pp. 206)
*/
function toEthereumSignature(
bytes memory pubkey,
Expand Down Expand Up @@ -252,9 +259,10 @@ library EthereumUtils {
}

/**
* Generates an Ethereum compatible SEC P256 k1 keypair and corresponding public address
* @return pubkeyAddr Ethereum address
* @return secretKey Secret key used for signing
* @notice Generate an Ethereum compatible SEC P256 k1 keypair and
* corresponding public address.
* @return pubkeyAddr Ethereum address.
* @return secretKey Secret key used for signing.
*/
function generateKeypair()
internal
Expand Down
36 changes: 8 additions & 28 deletions contracts/contracts/RLPWriter.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,17 @@
pragma solidity ^0.8.0;

/**
* @custom:attribution https://github.com/bakaoh/solidity-rlp-encode
* @custom:attribution https://raw.githubusercontent.com/Maia-DAO/solidity-rlp-encoder/main/src/rlp/RLPWriter.sol
* @title RLPWriter
* @author RLPWriter is a library for encoding Solidity types to RLP bytes. Adapted from Bakaoh's
* RLPEncode library (https://github.com/bakaoh/solidity-rlp-encode) with minor
* modifications to improve legibility.
* RLPEncode library (https://github.com/bakaoh/solidity-rlp-encode) with minor
* modifications to improve legibility.
* @custom:attribution https://github.com/bakaoh/solidity-rlp-encode
* @custom:attribution https://raw.githubusercontent.com/Maia-DAO/solidity-rlp-encoder/main/src/rlp/RLPWriter.sol
*/
library RLPWriter {
/**
* @notice RLP encodes a byte string.
*
* @param _in The byte string to encode.
*
* @return The RLP encoded string in bytes.
*/
function writeBytes(bytes memory _in) internal pure returns (bytes memory) {
Expand All @@ -31,9 +29,7 @@ library RLPWriter {

/**
* @notice RLP encodes a list of RLP encoded byte byte strings.
*
* @param _in The RLP encoded byte strings.
*
* @return The RLP encoded list of items in bytes.
*/
function writeList(bytes memory _in) internal pure returns (bytes memory) {
Expand All @@ -42,9 +38,7 @@ library RLPWriter {

/**
* @notice RLP encodes a list of RLP encoded byte byte strings.
*
* @param _in The list of RLP encoded byte strings.
*
* @return The RLP encoded list of items in bytes.
*/
function writeList(bytes[] memory _in)
Expand All @@ -58,9 +52,7 @@ library RLPWriter {

/**
* @notice RLP encodes a string.
*
* @param _in The string to encode.
*
* @return The RLP encoded string in bytes.
*/
function writeString(string memory _in)
Expand All @@ -73,9 +65,7 @@ library RLPWriter {

/**
* @notice RLP encodes an address.
*
* @param _in The address to encode.
*
* @return The RLP encoded address in bytes.
*/
function writeAddress(address _in) internal pure returns (bytes memory) {
Expand All @@ -84,9 +74,7 @@ library RLPWriter {

/**
* @notice RLP encodes a uint.
*
* @param _in The uint256 to encode.
*
* @return The RLP encoded uint256 in bytes.
*/
function writeUint(uint256 _in) internal pure returns (bytes memory) {
Expand All @@ -95,9 +83,7 @@ library RLPWriter {

/**
* @notice RLP encodes a bool.
*
* @param _in The bool to encode.
*
* @return The RLP encoded bool in bytes.
*/
function writeBool(bool _in) internal pure returns (bytes memory) {
Expand All @@ -107,11 +93,10 @@ library RLPWriter {
}

/**
* @notice Encode the first byte and then the `len` in binary form if `length` is more than 55.
*
* @notice Encode the first byte and then the `len` in binary form if
* `length` is more than 55.
* @param _len The length of the string or the payload.
* @param _offset 128 if item is string, 192 if item is list.
*
* @return RLP encoded bytes.
*/
function _writeLength(uint256 _len, uint256 _offset)
Expand Down Expand Up @@ -144,9 +129,7 @@ library RLPWriter {

/**
* @notice Encode integer in big endian binary form with no leading zeroes.
*
* @param _x The integer to encode.
*
* @return RLP encoded bytes.
*/
function _toBinary(uint256 _x) private pure returns (bytes memory) {
Expand All @@ -168,12 +151,11 @@ library RLPWriter {
}

/**
* @custom:attribution https://github.com/Arachnid/solidity-stringutils
* @notice Copies a piece of memory to another location.
*
* @param _dest Destination location.
* @param _src Source location.
* @param _len Length of memory to copy.
* @custom:attribution https://github.com/Arachnid/solidity-stringutils
*/
function _memcpy(
uint256 _dest,
Expand Down Expand Up @@ -204,12 +186,10 @@ library RLPWriter {
}

/**
* @custom:attribution https://github.com/sammayo/solidity-rlp-encoder
* @notice Flattens a list of byte strings into one byte string.
*
* @param _list List of byte strings to flatten.
*
* @return The flattened byte string.
* @custom:attribution https://github.com/sammayo/solidity-rlp-encoder
*/
function _flatten(bytes[] memory _list)
private
Expand Down
Loading

0 comments on commit 16d8498

Please sign in to comment.