Acre SDK - staking module #106

r-czajkowski · 2024-01-01T13:01:04Z

Closes #147
Depends on: #91

This PR adds staking module to the Acre SDK. The Acre SDK is built on top of the tbtc-v2.ts lib and exposes interfaces that should be implemented for a given chain to communicate with Acre network. In this PR we add Ethereum implementation and developers can initialize the SDK for the Ethereum chain.

What has been done:

define SDK file structure,
create abstract interfaces that should depend on the chain implementation eg. TBTCDepositor, ChainEIP712Signer and ChainSignedMessage,
add Ethereum implementation of Acre smart contracts and typed data signer,
create staking module that initializes the staking flow,
add unit tests,
create necessary wrappers for interfaces from tbtc-v2.ts lib that are used in SDK and are exposed outside the SDK eg Hex, ChainIdentifier, EthereumAddress and BitcoinRawTxVectors.

The SDK file structure

`lib` - shared library components

Contains all components used to build Acre features eg. staking, inspired by tbtc-v2.ts lib.

bitcoin: Contains all interfaces to interact with Bitcoin chain,
contracts: Includes abstract interfaces to interact with Acre smart contracts. Should be implemented for a given chain eg. Ethereum.
eip712-signer: An abstract layer for typed structured data signer. The main idea is to hide the signing process under the exact implementation for a given chain and not expose the external library outside the SDK. For example, we can use ethers lib for Ethereum implementation, but different lib for other chains.
ethereum: Provides Ethereum implementation of Acre smart contract and signer interfaces. Should contain other implementation of components that should depend on the chain implementation.
utils: General utility functions.

`modules` - Acre network features

Provides access to the Acre network features such as staking.

staking - provides access to the staking flow for BTC stakers.

Staking module

`initializeStake`

Initializes the Acre staking flow and returns StakeInitialization object that exposes staking flow steps:

getBitcoinAddress - returns Bitcoin address corresponding to this deposit. The user should send BTC to this address to stake tokens.
signMessage - signs the staking message and stores it in object instance to use it in stake function. The signed message is required by Acre staking flow.
stake - Stakes BTC based on the Bitcoin funding transaction via TBTCDepositor contract. It requires signed staking message, which means stake should be called after message signing. By default, it detects and uses the outpoint of the recent Bitcoin funding transaction and throws if such a transaction does not exist. The staking message must be signed first otherwise throws an error.

Unit tests

Decided to switch from mocha and chain to jest. Jest testing framework has built-in support for mocks, stubs, and spies. Chai requires the installation of additional dependencies but most of them are no longer maintained. I also tried using the chai with ethereum-waffle package, which adds support for mocking contracts, but it only supports ethers in v5, we want to use the latest version of ethers - it is v6.

sdk/src/lib/messages/messages.ts

sdk/src/modules/staking/index.ts

sdk/src/modules/staking/staking.ts

sdk/src/lib/eip712-signer/eip712.ts

sdk/src/modules/staking/stake-initialization.ts

nkuba · 2024-01-16T10:32:54Z

sdk/src/modules/staking/stake-initialization.ts

+    }
+
+    const types: Types = {
+      Stake: [{ name: "receiver", type: "address" }],


Let's also add the Bitcoin refund account property.
And also leave a TODO note to revisit the message structure when working on unstaking messages.

sdk/src/modules/staking/stake-initialization.ts

sdk/src/lib/contracts/index.ts

sdk/src/index.ts

sdk/src/modules/staking/index.ts

sdk/src/modules/staking/stake-initialization.ts

nkuba · 2024-01-19T13:45:18Z

sdk/src/modules/staking/stake-initialization.ts

+    const { depositor: _, ...restDepositReceipt } = this.#deposit.getReceipt()
+
+    const revealDepositInfo = {
+      fundingOutputIndex: outputIndex,
+      ...restDepositReceipt,
+    }


Could you please explain what are we doing here with the depositor?

We want to get all deposit receipt fields w/o depositor. Since depositor is unused variable the eslint throws an error and to fix it we need to rename it _.

sdk/src/lib/eip712-signer/eip712.ts

ioay · 2024-01-22T10:18:40Z

sdk/test/lib/ethereum/eip712.test.ts

+  EthereumEIP712Signer,
+  EthereumAddress,
+} from "../../../src/lib/ethereum"
+import { EthereumSignedMessage } from "../../../src/lib/ethereum/eip712-signer/signed-message"


Can we use an absolute path in files that have such nesting?

What do you mean?

I'm just thinking about using absolute path, eg: "src/lib" instead of relative paths like "../../../src"

Hmm I can't do that, eslint throws an error Unable to resolve path to module 'src'. I can dig into it in spare cycles but now I improved imports so the paths are much simpler see 023a33d.

ioay · 2024-01-22T10:22:04Z

sdk/src/index.ts

+    _tbtc: TBTC,
+  ) {
+    this.contracts = _contracts
+    this.#tbtc = _tbtc


Just for confirmation of the naming convention, do we use the _ prefix for private class members and # for read-only/protected?

# is a hard private field in js/ts see https://www.typescriptlang.org/docs/handbook/2/classes.html#caveats.
I use _ in constructor just to indicate that it is a constructor parameter.

sdk/src/lib/eip712-signer/eip712.ts

sdk/src/lib/ethereum/contract.ts

sdk/src/lib/ethereum/tbtc-depositor.ts

sdk/src/acre.ts

sdk/src/lib/ethereum/index.ts

sdk/src/lib/ethereum/tbtc-depositor.ts

sdk/src/modules/staking/index.ts

sdk/src/modules/staking/stake-initialization.ts

Use `TbtcDeposit` alias for `Deposit` import and rename the field in the `StakeInitialization` class to `tbtcDepositor`. To indicate this is deposit from tbtc-v2.ts SDK.

The contract name is `TbtcDepositor` not `TBTCDepositor`.

The message should contain the Bitcoin recovery address instead of the public key hash of this address.

The latest version of the `tbtc-v2.ts` lib adds support for revealing deposit with extra data. We need this feature to stake BTC(tBTC) on user's behalf.

The `TBTCDepositor` should implement the `DepositorProxy` interface to reveal the deposit with extra data on user's behalf. Here we also add `encodeExtraData` and `decodeExtraData` functions to encodes and decodes extra data passed to the tBTC Bridge contract. The Acre extra data is staker address and referral number.

Adujst staking module to the new TBTCDepositor interface and the latest version of the `tbtc-v2.ts` lib. We need to initiate the deposit with extra data using the `tbtc-v2.ts` SDK by injecting our implementation of the `DepositorProxy`.

Adjust unit tests to the latest version of tbtc-v2.ts lib that adds support for revealing deposits with extra data via depositor proxy.

We can get the referral and staker from tBTC deposit object.

Expose shared components, feature modules and the `Acre` entry point class from the root `index.ts` file. The `Acre` entry point class currently provides static function to initialize the Acre SDK for Ethereum network.

Pass the `bitcoinRecoveryAddress` to the `StakeInitialization` class. Since we can't easily determine if we should use `true` or `false` in `BitcoinAddressConverter.publicKeyHashToAddress` to convert public key hash to `P2PKH` or `P2WPKH` we can use what the input was w/o doing a conversion. Here we also get rid of: - the bitcoin client from the `StakeInitailization` class because at least for now it is unnecessary, - `referral` field - it is decoded and passed to the contract function under the hood.

We need `build` and `typechain` artifacts from `core` package in `sdk` because we import artifacts and types generated by `typechain` in `sdk` package. To achieve this, we extract a reusable workflow that builds the `core` package and uploads necessary artifacts. Then we use this reusable workflow to run successfully the `sdk` jobs. Here we also update the `jest` config - we should ignore tests inside `dist` dir if exists.

We want to omit the `signerOrProvider` because it points to ethers v5. We use ethers v6 in Acre SDK.

Ignore `sdk` monorepo package - `sdk` package has own prettier config.

According to the contract source code, the referral should be `uint16`. Here we also add more unit tests to cover more cases eg. when a referral is `0` (min `uint16`) and `65535` (max `uint16`).

We do not expect to support it.

And create the ethereum contract instance based on this artifact.

`receiver` -> `ethereumStakerAddress`. Add more context to the name of field for clarity when user sees it on the device, so they know what the value means.

Check if the staker address is a valid ethereum and non-zero address.

Based on the #91. We need this contract to get types generated by `typechain` and import them in `sdk`. Currently our SDK uses only `initializeStakeRequest` function and there is no need to add more functions like in #91.

Pass the `staker` value the same as was used in this function input parameter and use it insied `StakeInitialization` constructor to initialize the value of `#staker` field, instead of recovering it from the ` _tbtcDeposit.getReceipt()` extra data, as this is an external library that can be compromised and return invalid value.

Depends on: #106 Added getting of tbtc deposit receipt for StakeInitialization.

We decided to rename receiver to staker in the Depositor contract and SDK. See: #106 (comment)

r-czajkowski added the 🔌 sdk TypeScript SDK Library label Jan 1, 2024

r-czajkowski requested a review from nkuba January 1, 2024 13:01

r-czajkowski self-assigned this Jan 1, 2024

r-czajkowski changed the title ~~Staking module in Acre SDK~~ Acre SDK - staking module Jan 2, 2024

nkuba reviewed Jan 3, 2024

View reviewed changes

r-czajkowski requested review from dimpar, kkosiorowska and ioay January 4, 2024 16:06

nkuba mentioned this pull request Jan 11, 2024

EPIC: Staking #146

Closed

nkuba reviewed Jan 16, 2024

View reviewed changes

r-czajkowski marked this pull request as ready for review January 17, 2024 18:15

r-czajkowski requested a review from nkuba January 18, 2024 08:02

nkuba reviewed Jan 19, 2024

View reviewed changes

ioay reviewed Jan 22, 2024

View reviewed changes

nkuba mentioned this pull request Jan 29, 2024

Submit initiated deposit data to Sentry (for tBTC minting recovery) #202

Closed

nkuba reviewed Jan 30, 2024

View reviewed changes

sdk/src/lib/eip712-signer/eip712.ts Show resolved Hide resolved

sdk/src/lib/ethereum/contract.ts Show resolved Hide resolved

sdk/src/lib/ethereum/tbtc-depositor.ts Outdated Show resolved Hide resolved

sdk/src/lib/ethereum/tbtc-depositor.ts Show resolved Hide resolved

r-czajkowski force-pushed the acre-sdk branch from c510412 to 2675078 Compare January 31, 2024 08:44

This was referenced Jan 31, 2024

Added getting of tbtc deposit receipt for StakeInitialization #207

Closed

Added getting of tbtc deposit receipt for StakeInitialization #208

Merged

r-czajkowski force-pushed the acre-sdk branch 5 times, most recently from 956d897 to 4d41223 Compare January 31, 2024 10:04

ioay mentioned this pull request Jan 31, 2024

Deposit receipt stake flow hook #210

Closed

This was referenced Feb 1, 2024

Improve Bitcoin deposit transaction detection #211

Open

EIP-712 signer - add primaryType #212

Closed

nkuba reviewed Feb 1, 2024

View reviewed changes

sdk/src/lib/ethereum/tbtc-depositor.ts Outdated Show resolved Hide resolved

nkuba reviewed Feb 6, 2024

View reviewed changes

r-czajkowski requested a review from nkuba February 6, 2024 16:40

r-czajkowski and others added 21 commits February 7, 2024 13:10

Rename import and class field

46fa436

Use `TbtcDeposit` alias for `Deposit` import and rename the field in the `StakeInitialization` class to `tbtcDepositor`. To indicate this is deposit from tbtc-v2.ts SDK.

Set correct contract name in typed message

239d6ec

The contract name is `TbtcDepositor` not `TBTCDepositor`.

Update the staking message format

05a22f6

The message should contain the Bitcoin recovery address instead of the public key hash of this address.

Bump tbtc-v2.ts lib to the latest version

1c24521

The latest version of the `tbtc-v2.ts` lib adds support for revealing deposit with extra data. We need this feature to stake BTC(tBTC) on user's behalf.

Adjust staking module

968bdf7

Adujst staking module to the new TBTCDepositor interface and the latest version of the `tbtc-v2.ts` lib. We need to initiate the deposit with extra data using the `tbtc-v2.ts` SDK by injecting our implementation of the `DepositorProxy`.

Update staking module unit test

bbf93ff

Adjust unit tests to the latest version of tbtc-v2.ts lib that adds support for revealing deposits with extra data via depositor proxy.

Simplify class constructor

54dabd2

We can get the referral and staker from tBTC deposit object.

Improve imports in Acre SDK

a59aa37

Expose shared components, feature modules and the `Acre` entry point class from the root `index.ts` file. The `Acre` entry point class currently provides static function to initialize the Acre SDK for Ethereum network.

Add comment to describe why we omit field

565a0a1

We want to omit the `signerOrProvider` because it points to ethers v5. We use ethers v6 in Acre SDK.

Update root .prettierignore file

10d4bec

Ignore `sdk` monorepo package - `sdk` package has own prettier config.

Fix variable type in encodeExtraData fn

d846701

According to the contract source code, the referral should be `uint16`. Here we also add more unit tests to cover more cases eg. when a referral is `0` (min `uint16`) and `65535` (max `uint16`).

Remove Goerli from supported Ethereum networks

06b7617

We do not expect to support it.

Add artifacts deployed on Sepolia to SDK

8b202b8

And create the ethereum contract instance based on this artifact.

Rename receiver -> staker

e037f64

Imporve the stake message template

ef9d7ee

`receiver` -> `ethereumStakerAddress`. Add more context to the name of field for clarity when user sees it on the device, so they know what the value means.

Validate if staker is a valid ethereum address

96101e2

Check if the staker address is a valid ethereum and non-zero address.

Update reference to @keep-network/tbtc-v2

4bba1bd

Add initial implementation of TbtcDepositor

faa487c

Based on the #91. We need this contract to get types generated by `typechain` and import them in `sdk`. Currently our SDK uses only `initializeStakeRequest` function and there is no need to add more functions like in #91.

r-czajkowski force-pushed the acre-sdk branch from 8cc8ca3 to faa487c Compare February 7, 2024 13:28

r-czajkowski changed the base branch from tbtc-depositor to main February 7, 2024 13:30

nkuba approved these changes Feb 7, 2024

View reviewed changes

nkuba merged commit 2b0d3ba into main Feb 7, 2024
12 checks passed

nkuba deleted the acre-sdk branch February 7, 2024 14:12

r-czajkowski added a commit that referenced this pull request Feb 8, 2024

Added getting of tbtc deposit receipt for StakeInitialization (#208)

94628d9

Depends on: #106 Added getting of tbtc deposit receipt for StakeInitialization.

r-czajkowski mentioned this pull request Feb 16, 2024

Initial implementation of Bitcoin depositor (tBTC Depositor) #91

Merged

nkuba added a commit that referenced this pull request Feb 21, 2024

Rename receiver to staker

005435d

We decided to rename receiver to staker in the Depositor contract and SDK. See: #106 (comment)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Acre SDK - staking module #106

Acre SDK - staking module #106

r-czajkowski commented Jan 1, 2024 •

edited

Loading

nkuba Jan 16, 2024

r-czajkowski Jan 16, 2024

nkuba Jan 19, 2024

r-czajkowski Jan 25, 2024

ioay Jan 22, 2024

r-czajkowski Jan 25, 2024

ioay Jan 30, 2024

r-czajkowski Feb 6, 2024

ioay Jan 22, 2024

r-czajkowski Jan 25, 2024

Acre SDK - staking module #106

Acre SDK - staking module #106

Conversation

r-czajkowski commented Jan 1, 2024 • edited Loading

What has been done:

The SDK file structure

lib - shared library components

modules - Acre network features

Staking module

initializeStake

Unit tests

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

r-czajkowski commented Jan 1, 2024 •

edited

Loading

`lib` - shared library components

`modules` - Acre network features

`initializeStake`