Clients CLI
Client's CLI is intended to be used as terminal tool to interact with the protocol so you can expect to do following things:
- Obtain providers list: you can ask current providers list to deal with
- Create deals: you can create deals with providers by passing a data uri or reading a local file
- Retrieve files: you can retrieve files from provider and download them
- Make appeals: you can make appeals for a specific deal, asking the referees to check file and eventually get a refund
- Withdraw funds: you can withdraw funds if they got unlocked by the protocol
Build CLI from source
CLI is written in NodeJS so we assume you have git, NodeJS >= 16 and YARN installed.
You will also need a web3 provider (we suggest Infura) to interact with blockchain.
After you've met all required dependencies you can start following those steps:
git clone https://github.com/protocol/retriev
cd clients-cli
yarn
Now you need to configure your node following those steps:
cp .env.sepolia .env
nano .env
you will see something like:
CONTRACT_ADDRESS=0x6A530F53428736Bd198811Dc28DCb6033936357d
WEB3_PROVIDER=https://rpc.ankr.com/base_sepolia
API_URL=https://api-sepolia.retr.dev
You're ready to interact with retrieval pinning protocol!
Compile binaries
Optionally you can also compile binaries and use the package as a native application for your operating system. To compile the client you will just need to prompt:
yarn compile
you should obtain a response like:
yarn run v1.22.17
$ pkg . --out-path bin
> [email protected]
> Targets not specified. Assuming:
node16-linux-x64, node16-macos-x64, node16-win-x64
Done in 6.91s.
you will find compiled binaries in clients-cli/bin folder.
Start for the first time
At first start the CLI will create a new blockchain identity for you so please now run:
yarn identity
client will print something like:
Can't find configs for node rpp-client, creating.
Generating new identity for node.
New identity is: 0xF941940Df2191B1354dBCF9160C2782bfF638378
0xF941940Df2191B1354dBCF9160C2782bfF638378
Done in 0.35s.
In this case: 0xF941940Df2191B1354dBCF9160C2782bfF638378 is your identity and you will be able to find generated private key (or insert your private key) in configs folder:
nano $HOME/.rpp/rpp-client/configs.json
Please make sure to make a backup of this key and never share it. You will be able to import it in Metamask or other wallets. You will probably need some spare rETH and you can ask them from Alchemy's goerli faucet.
Interact with protocol
Now we'll explain deeply how any command works. If you need any support you can also enter our Slack channel and ask for support!
Providers list
This command will return and print the list of current active providers:
yarn providers
will print out something like following table, if you see it "strange" please simply open the window a little bit more.
Asking deals to API..
Found 1 providers.
┌─────────┬─────────────────────────────┬──────────────────────────────────────────────┬───────────┬──────────┬───────────────────────────┬──────────────┐
│ (index) │ endpoint │ address │ min_price │ max_size │ max_collateral_multiplier │ max_duration │
├─────────┼─────────────────────────────┼──────────────────────────────────────────────┼───────────┼──────────┼───────────────────────────┼──────────────┤
│ 0 │ 'https://provider.retr.dev' │ '0x4C0Fb89b2506B2E286D8F0cc05913CD3eBb68682' │ 1 │ 20000000 │ 1000 │ 90 │
└─────────┴─────────────────────────────┴──────────────────────────────────────────────┴───────────┴──────────┴───────────────────────────┴──────────────┘
Done in 1.02s.
As you can see there is also provider's strategy like min_price or max_duration. You will need to pay attention to those values if you want to successful create deals.
Make deal
This is core command, you can use it in two different ways:
- Basic: by passing minimal informations of
file,providerandduration. - *Advanced: by passing also
value,collateralanddealuri.
Basic mode can be tested using following command (make sure you are inside clients-cli folder):
yarn deal --file=../shared/vps.txt --provider='0x2489c48090523f37028f1e42454b7DD04943d0Bf' --duration=60
it will print out something like:
💽 Checking if provider is valid..
📝 Reading state from contract..
💳 Creating deal from address: 0xF941940Df2191B1354dBCF9160C2782bfF638378
⏱️ Deal duration is: 60 days.
💾 File size is: 200 byte
☁️ Uploading file to cache node..
🤙 Creating deal with URI: ipfs://bafkreidtskz64q2len4yzdkn2qxcxlwdh42wjtlpohydyjstboinepceya
💸 Paying 1036800000 wei for the deal.
💰 Wallet's balance is: 10000000000000000 wei
⌛ Pending transaction at: 0x3e27337abe1e760d0ef8d372050547c93a302de85edf0eecd235f9cff963c264
🎉 Deal created at 0x3e27337abe1e760d0ef8d372050547c93a302de85edf0eecd235f9cff963c264!
Done in 23.22s.
Advanced mode can be tested using following command (please remember you can use file or dealuri in both modes, just be sure provided dealuri is available for retrieval):
yarn deal --dealuri='ipfs://bafkreidlrmxrhd45dljz34f54txu7affj27xv2fmbqv7oumpnlptljpcuu' --provider='0x2489c48090523f37028f1e42454b7DD04943d0Bf' --duration=60 --value=0 --collateral=0
it will print something similar to the previous response, so there's no need to show again the example. The only difference is that it will not automatically calculate deal price and will not upload the file to protocol's cache node.
Obtaining deals
You can see your deals list by using following command:
yarn deals
it will print something like (please make sure window has enough width or reduce font size):
Asking deals to API..
Found 2 deals.
┌─────────┬───────────┬──────────────────────────────────────────────────────────────────────┬──────────────┬──────────────────────────────────────────────┬──────────────────────────┬──────────────────────────┐
│ (index) │ dealIndex │ dealUri │ value │ provider │ start_at │ end_at │
├─────────┼───────────┼──────────────────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────────┼──────────────────────────┼──────────────────────────┤
│ 0 │ 57 │ 'ipfs://bafkreidtskz64q2len4yzdkn2qxcxlwdh42wjtlpohydyjstboinepceya' │ '1036800000' │ '0x2489c48090523f37028f1e42454b7DD04943d0Bf' │ 2022-08-30T04:57:43.000Z │ 2022-10-29T04:57:43.000Z │
│ 1 │ 58 │ 'ipfs://bafkreidlrmxrhd45dljz34f54txu7affj27xv2fmbqv7oumpnlptljpcuu' │ '0' │ '0x2489c48090523f37028f1e42454b7DD04943d0Bf' │ 2022-08-30T04:59:43.000Z │ 2022-10-29T04:59:43.000Z │
└─────────┴───────────┴──────────────────────────────────────────────────────────────────────┴──────────────┴──────────────────────────────────────────────┴──────────────────────────┴──────────────────────────┘
Done in 1.03s.
Retrieve files
You can download files from providers by using following command:
yarn retrieve 57
or using following command:
yarn retrieve --dealuri=ipfs://bafkreidlrmxrhd45dljz34f54txu7affj27xv2fmbqv7oumpnlptljpcuu
As you can see you can use dealIndex or dealUri as parameters to download files. File will be downloaded in protocol's folder:
$HOME/.rpp/rpp-client/retrievals
Make appeals
To make appeals you can run following command:
yarn appeal <DEAL_INDEX>
Please remember that any appeal will cost you some ETH so be 100% sure file is not retrievable or you will basically lose money.
You will receive something like:
🚩 Making appeal to deal #57
Fee for appeal is: 0.0000000002592
⌛ Pending transaction at: 0xb771322f3e9816fc357966197cc0419768b321b0103d9664c5c31fc4bc252b78
🎉 Appeal created at 0xb771322f3e9816fc357966197cc0419768b321b0103d9664c5c31fc4bc252b78!
Done in 20.34s.
Withdraw from contract
If one (or more) appeals end with a "slash" (please read paper for extended explanation) you will be refunded and you'll be able to withdraw funds back from contract to your account by using:
yarn withdraw
Use dApp at retriev.org
You will also able to use the protocol by interacting with retriev.org dApp. Of course you will need to import the private key to Metamask to see the same deals.
Contributions and support
Feel free to open issues or PR to contribute the project.