isabella232 / go-auctions-client

A Go client and CLI for Filecoin Storage Auctions.

go-auctions-client

A Go library and CLI to interact with Filecoin Storage Auctions.

Join us on our public Slack channel for news, discussions, and status updates. Check out our blog for the latest posts and announcements.

Table of Contents

• Installation
• Remote signing CLI
• Remote signing library
• Contributing
• Changelog
• License

Installation

Install Go 1.17, and run:

make install

This will compile the auc CLI tool and place it in your $GOPATH/bin folder.

Alternatively, you can run:

make build

The auc binary will be generated in your current folder.

Remote signing CLI

The auc binary lets you run a remote wallet daemon that your direct auctions API calls can target to sign deal proposals resulting from the auctions. Multiple wallet addresses can be configured.

The daemon should be publicly reachable, so it's recommended that if you can open firewall ports and provide open listen addresses, that's highly recommended. As an automatic fallback mechanism, we make the remote wallet daemon connect with a libp2p relay to have a baked in NAT traversal solution. The daemon will do its best-effort to keep a healthy connection with the relay automatically. For best results, please also consider providing direct open ports for your wallet address.

If you want to run a remote wallet that will be used to sign deal proposals:

$ auc wallet daemon --help
Run a remote wallet signer for auctions

Usage:
  auc wallet daemon [flags]

Flags:
      --auth-token string     Authorization token to validate signing requests
  -h, --help                  help for daemon
      --private-key string    Libp2p private key
      --relay-maddr string    Multiaddress of libp2p relay (default "/ip4/34.105.85.147/tcp/4001/p2p/QmYRDEq8z3Y9hBBAirwMFySuxyCoWwskrD1bxUEYKBiwmU")
      --wallet-keys strings   Wallet address keys; repeatable

Global Flags:
      --log-debug   Enable debug level log (default false)
      --log-json    Enable structured logging

A quick explanation of the relevant flags:

• --auth-token: Is a string value that will be sent in your direct auctions API calls to authenticate with the wallet address. Only requests that provide this auth token will be replied.
• --relay-maddr: This an optional flag. By default has value pointing to a libp2p relay we run to help clients solve NAT problems. If you want to disable this feature, can provide an empty string.
• --wallet-keys: Is a comma-separated string value of hex-encoded wallet addresses private keys. (The same format in the output of lotus wallet export <addr>).
• --listen-addresses: Is a list of multiaddresses to explicitly listen from. Use this flag if you want to provide open ports to the wallet address, which will help connectivity.

An example run of this command could be:

$ auc wallet daemon --debug --auth-token mysecrettk --wallet-keys 7b2254797065223a22626c73222c22507269766174654b6579223a226862702f794666527439514c43716b6d566171415752436f50556777314b776971716e73684e49704e57513d227d

If you want to have extra reliability regarding reachability and did port-forwarding configuration in your firewall, here's a possible run of the CLI:

$ auc wallet daemon --auth-token mysecrettk --debug --wallet-keys 7b2254797065223a22626c73222c22507269766174654b6579223a226862702f794666527439514c43716b6d566171415752436f50556777314b776971716e73684e49704e57513d227d --listen-addresses /ip4/0.0.0.0/tcp/9876

The first log lines of the daemon will help understanding which wallet public keys, listen addreses, and relayed addreses are configured:

2021-09-10T10:07:10.879-0300    INFO    auc     auc/walletCmd.go:48     Loaded wallet: f3rpskqryflc2sqzzzu7j2q6fecrkdkv4p2avpf4kyk5u754he7g6cr2rbpmif7pam5oxbme2oyzot4ry3d74q
2021-09-10T10:07:10.948-0300    INFO    auc     auc/walletCmd.go:92     libp2p peer-id: Qma7rzaZUYNgqSkhgrQ8dmBhPvBhuGk3W7gm1MnoK2Bj9U
2021-09-10T10:07:10.949-0300    INFO    auc     auc/walletCmd.go:94     Listen multiaddr: /ip4/192.168.1.30/tcp/41947
2021-09-10T10:07:10.949-0300    INFO    auc     auc/walletCmd.go:94     Listen multiaddr: /ip4/127.0.0.1/tcp/41947
2021-09-10T10:07:10.949-0300    INFO    auc     auc/walletCmd.go:94     Listen multiaddr: /ip6/::1/tcp/45457
2021-09-10T10:07:10.949-0300    INFO    relaymgr        relaymgr/relaymgr.go:110        connecting with relay...
2021-09-10T10:07:10.955-0300    INFO    relaymgr        relaymgr/relaymgr.go:116        connected with relay
2021-09-10T10:07:10.955-0300    INFO    auc     auc/walletCmd.go:70     Relayed multiaddr: /ip4/140.20.1.1/tcp/9898/p2p/QmfPveoYMS158VbkxNeizZ3ZrDWHb82R28xfkVT9QodcQA/p2p-circuit/Qma7rzaZUYNgqSkhgrQ8dmBhPvBhuGk3W7gm1MnoK2Bj9U
2021-09-10T10:07:30.956-0300    DEBUG   relaymgr        relaymgr/relaymgr.go:104        relay connection is healthy

The relay multiaddress circuit is useful to augment your reachable multiaddresses of the remote wallet

Remote signing direct-auction API

for the direct auctions API calls.

An example of the body for a direct-auction API call:

{
   "payloadCid":"...",
   "pieceCid":"...",
   "pieceSize":...,
   "repFactor":...,
   "deadline":"...",
   "carURL":{...},
   "remoteWallet":{
      # These three fields are mandatory.
      "peerID":"Qma7rzaZUYNgqSkhgrQ8dmBhPvBhuGk3W7gm1MnoK2Bj9U",
      "authToken":"mysecrettk",
      "walletAddr":"f3rpskqryflc2sqzzzu7j2q6fecrkdkv4p2avpf4kyk5u754he7g6cr2rbpmif7pam5oxbme2oyzot4ry3d74q",
      
      # This is an optional but *highly recommended* field.
      # If empty only the relayed address will be used, but for better reliability
      # is encouraged to open ports and provide additional reachable multiaddresses.
      "multiAddrs": ["...", "..."], 
   }

Remote signing library

This repository can also be used as a library, which allows the following use-cases:

• Incorporate a remote wallet in your existing applications.
• Provide your implementation of the wallet abstraction. This can be useful if you want fewer security assumptions, or have the wallet keys in a more constrained environment. The daemon will still be handling the protocol layer of remote signing and deferring signing to your implementation.

Contributing

Pull requests and bug reports are very welcome ❤️

This repository falls under the Textile Code of Conduct.

Feel free to get in touch by:

• Opening an issue
• Joining the public Slack channel
• Sending an email to [email protected]

Changelog

A changelog is published along with each release.

License

MIT