Greenfield Contracts

Greenfield Contracts is the bridge between Greenfield and BSC for cross-chain communication.

Overview

The Greenfield Blockchain provides a comprehensive set of resources that can be mirrored on the BNB Smart Chain (BSC). This includes buckets, objects, and groups, which can be stored and managed on the BSC as non-fungible tokens (NFTs) conforming to the ERC-721 standard.

A bucket is a logical container for storing objects in Greenfield. An object, on the other hand, is a fundamental unit of storage in Greenfield that represents a file consisting of data and its associated metadata. Lastly, a group is a collection of accounts with the same permissions.

These resources can be mirrored on the BSC as ERC-721 NFTs, along with the members within a group, which represent permissions to specify resources, that can be mirrored as ERC-1155 token. At present, the NFTs are not transferable, but the transferability feature will be added in the near future.

Once these resources are mirrored on BSC, they can be directly managed by smart contracts on BSC. These operations will directly affect the storage format, access permissions, and other aspects of the data on greenfield. In other words, any changes made to the decentralized application on BSC will also reflect changes on Greenfield. This integration between Greenfield Blockchain and BNB Smart Chain allows for greater flexibility and accessibility when it comes to accessing and manipulating data, ultimately leading to a more streamlined and efficient data management process.

Key Contract

1. CrossChain. The underlying cross-chain communication protocol. This contract is responsible for handling all aspects of cross-chain communication packages, including verification, encoding, decoding, routing, reward distribution.
2. GovHub. This contract oversees all aspects of contract upgrades, parameter adjustments, and handles governance requests originating from the Greenfield. Additionally, it validates and executes governance proposals as required.
3. TokenHub. This contract is tasked with handling cross-chain transactions, encompassing both transferIn and transferOut. Upon initiating a cross-chain transfer from the Greenfield to the BSC, tokens are initially locked within the TokenHub, subsequently triggering a cross-chain transfer event.
4. GroupHub. This contract is responsible for managing the Greenfield group, including the addition and removal of members.
5. BucketHub. This contract is responsible for managing the Greenfield buckets.
6. ObjectHub. This contract is responsible for managing the Greenfield objects.

Resource Operating Primitives

A number of cross-chain primitives have been defined on BSC to enable developers to manage greenfield resources on the BSC directly, without the need for intermediaries.

BNB:

• transfer BNB bidirectionally between BSC and Greenfield

Bucket:

• create a bucket on BSC
• delete a bucket on BSC
• mirror bucket from Greenfield to BSC

Object:

• delete an object on BSC
• mirror object from Greenfield to BSC
• grant/revoke permissions of objects on BSC to accounts/groups
• create an object on BSC (pending)
• copy objects on BSC (pending)
• Kick off the execution of an object on BSC (pending)

Group:

• create a group on BSC
• delete a group on BSC
• change group members on BSC
• mirror group from Greenfield to BSC

Users can also approve smart contracts to operate the aforementioned resources instead, check the design for more details.

Requirement

set environment

# require Node.js 14+
cp .env.example .env
# modify the env variable `DeployerPrivateKey` to your own private key

# make sure the address corresponding to the private key has enough tBNB in the BSC Testnet

Install foundry:

curl -L https://foundry.paradigm.xyz | bash
foundryup

Install dependencies:

make install-dependencies

Lint

yarn lint:check
yarn lint:write

Build

make build

Deploy

# modify the env variable `DeployerPrivateKey` to your own private key on BSC Testnet
npm run deploy:testnet

# modify the env variable `DeployerPrivateKey` to your own private key on BSC
npm run deploy:bsc

Deployment

Greenfield Contracts on BSC

• BSC ChainID: 56

• BSC RPC: https://bsc-dataseed1.binance.org

• BSC Explorer: https://bscscan.com/

• Greenfield ChainID: greenfield_1017-1

• Greenfield RPC: https://greenfield-chain.bnbchain.org:443

• Greenfield GRPC swagger: https://greenfield-chain.bnbchain.org/openapi

• Greenfield Storage dApp: https://dcellar.io/

• Greenfield Explorer: http://greenfieldscan.com/

Greenfield Contracts on BSC Testnet

• BSC Testnet ChainID: 97

• BSC Testnet RPC: https://data-seed-prebsc-1-s1.binance.org:8545/

• BSC Testnet Explorer: https://testnet.bscscan.com/

• Greenfield ChainID: greenfield_5600-1

• Greenfield RPC: https://gnfd-testnet-fullnode-tendermint-us.bnbchain.org

• Greenfield GRPC swagger: https://gnfd-testnet-fullnode-tendermint-us.bnbchain.org/openapi

• Greenfield Storage dApp: https://dcellar.io/

• Greenfield Explorer: http://greenfieldscan.com/

ERC2771Forwarder

The eip-2771 defines a contract-level protocol for Recipient contracts to accept meta-transactions through trusted Forwarder contracts. No protocol changes are made. Recipient contracts are sent the effective msg.sender (referred to as _erc2771Sender()) and msg.data (referred to as _msgData()) by appending additional calldata.

The trusted ERC2771_FORWARDER contract is deployed from: https://github.com/bnb-chain/ERC2771Forwarder.git

TrustedForwarder Address on All Chains: 0xdb7d0bd38D223048B1cFf39700E4C5238e346f7F

More details, refer to

• eip-2771
• Openzeppelin ERC2771Forwarder

Contract Entrypoint

Mainnet

contract name	address
CrossChain	0x77e719b714be09F70D484AB81F70D02B0E182f7d
TokenHub	0xeA97dF87E6c7F68C9f95A69dA79E19B834823F25
BucketHub	0xE909754263572F71bc6aFAc837646A93f5818573
ObjectHub	0x634eB9c438b8378bbdd8D0e10970Ec88db0b4d0f
GroupHub	0xDd9af4573D64324125fCa5Ce13407be79331B7F7

Extra:

contract name	address
Deployer	0x4763c12b21a548BCbD22a682fb15930565e27C43
ProxyAdmin	0xf9010DC773eE3961418C96dc67Fc5DcCB3EA2C08
LightClient	0x433bB48Bd86c089375e53b2E2873A9C4bC0e986B
RelayerHub	0x31C477F05CE58bB81A9FB4b8c00560f1cBe185d1

for full list of contracts, please refer to: Deployment on BSC

Testnet

contract name	address
CrossChain	0xa5B2c9194131A4E0BFaCbF9E5D6722c873159cb7
TokenHub	0xED8e5C546F84442219A5a987EE1D820698528E04
BucketHub	0x5BB17A87D03620b313C39C24029C94cB5714814A
ObjectHub	0x1b059D8481dEe299713F18601fB539D066553e39
GroupHub	0x50B3BF0d95a8dbA57B58C82dFDB5ff6747Cc1a9E

Extra:

contract name	address
Deployer	0x79aC4Ce73Cf5c4896a311CD39d2EB47E604D18E3
ProxyAdmin	0xdD1c0a54a9EDEa8d0821AEB5BE54c51B79fa4c2e
LightClient	0xa9249cefF9cBc9BAC0D9167b79123b6C7413F50a
RelayerHub	0x91cA83d95c8454277d1C297F78082B589e6E4Ea3

for full list of contracts, please refer to: Deployment on BSC Testnet

Verify on BSCScan

# modify the env variable `BSCSCAN_APIKEY` to your own api-key created on https://bscscan.com/myapikey
npm run verify:testnet
npm run verify:bsc

Cross-Chain Transfer to GreenField

# make sure the foundry dependency are installed 
# 1. add private-key, receiver and BNB amount to ./foundry-scripts/transferOut.sh
# 2. run shell command
# cross-chain transfer 0.2 BNB (amount = 2 * 10 ^ 17) to your receiver on GreenField
forge script foundry-scripts/TokenHub.s.sol:TokenHubScript \
--private-key ${your private key} \
--sig "transferOut(address receiver, uint256 amount)" \
${the receiver you transfer to} 200000000000000000  \
-f https://data-seed-prebsc-1-s1.binance.org:8545/  \
--legacy --ffi --broadcast
# More examples please refer to ./foundry-scripts/examples/transferOut.sh

Cross-Chain Operation to GreenField

# make sure the foundry dependency are installed 
# group operation - add member to the group
forge script foundry-scripts/GroupHub.s.sol:GroupHubScript \
--private-key ${your private key} \
--sig "addMember(address operator, uint256 groupId, address member)" \
${the owner of the group} ${your group id} ${the member address to add} \
-f https://data-seed-prebsc-1-s1.binance.org:8545/ \
--legacy --ffi --broadcast
# More examples please refer to ./foundry-scripts/examples/updateGroup.sh

# bucket operation - delete a bucket
forge script foundry-scripts/BucketHub.s.sol:BucketHubScript \
--private-key ${your private key} \
--sig "deleteBucket(uint256 bucketId)" \
${bucketId to delete} \
-f https://data-seed-prebsc-1-s1.binance.org:8545/ \
--legacy --ffi --broadcast
# More examples please refer to ./foundry-scripts/examples/bucketHub.sh

# object operation - delete an object
forge script foundry-scripts/ObjectHub.s.sol:ObjectHubScript \
--private-key ${your private key} \
--sig "deleteObject(uint256 id)" \
${object id to delete} \
-f https://data-seed-prebsc-1-s1.binance.org:8545/ \
--legacy --ffi --broadcast

Inspect Transactions

# 1. add your txHash to `InspectTxHashes` on `scripts/3-decode-events.ts`
# 2. run script on BSC testnet
npx hardhat run scripts/3-decode-events.ts --network bsc-testnet

# run script on BSC
npx hardhat run scripts/3-decode-events.ts --network bsc

Test

# start a local chain
anvil -b 1

# run test on another terminal
npm run deploy:local
forge t -vvv --ffi

Large Transfer Unlock

npm install typescript ts-node -g

cp .env.example .env
# set RPC_URL, OPERATOR_PRIVATE_KEY, UNLOCK_RECEIVER to .env

ts-node scripts/6-claim-unlock-bot.ts

Contribution

Thank you for considering helping with the source code! We appreciate contributions from anyone on the internet, no matter how small the fix may be.

If you would like to contribute to Greenfield, please follow these steps: fork the project, make your changes, commit them, and send a pull request to the maintainers for review and merge into the main codebase. However, if you plan on submitting more complex changes, we recommend checking with the core developers first via GitHub issues (we will soon have a Discord channel) to ensure that your changes align with the project's general philosophy. This can also help reduce the workload of both parties and streamline the review and merge process.

License

The greenfield contracts (i.e. all code inside the contracts directory) are licensed under the GNU Affero General Public License v3.0, also included in our repository in the COPYING file.