Once you've thoroughly tested your participant, you'll want to put it to work in the real PolySwarm marketplace!
At a high level, plugging into the PolySwarm marketplace is a simple matter of:
- determining which Community(ies) you'd like to join
- pointing your participants to the hosted instance of
polyswarmdfor those Communities
There are a few items to be aware of when doing this; we discuss below.
PolySwarm is built on top of Ethereum, a programmable world computer fueled by a native cryptocurrency called Ether (ETH). When an Ethereum user executes a transfer of ETH or conducts a call into an Ethereum "smart contract" (e.g. PolySwarm's Relay contracts), the user must pay the Ethereum network to carry out this transaction in the form of "Gas". Gas is deducted from the user's ETH balance.
PolySwarm operates on Nectar (NCT) - an application-layer cryptocurrency token built on top of Ethereum. NCT is essential for participating in the PolySwarm marketplace.
Your participant, acting as your representative on the PolySwarm marketplace, must have access to both ETH and NCT.
As with all cryptocurrencies (e.g. Bitcoin), funds are maintained in "wallets". Technically, a wallet is simply a cryptographic keypair and some metadata that describes the keypairs' usage. Wallets are uniquely identified by a cryptographic hash of the public portion of this cryptographic keypair. Possession / control of a wallet (and all funds contained therein) is analogous to possession of the private portion of the wallet's keypair.
In PolySwarm, as with all cryptocurrency applications, an attacker with access to your wallet's private key can steal all your cryptocurrency (ETH & NCT) and impersonate you in the marketplace.
It is absolutely essential that you protect the secrecy of your wallet's private key.
Means to secure your private key are outside of the scope of this document.
In order for your participant to participate in the PolySwarm marketplace (and place transactions on your behalf), your participant must have the ability to sign transactions with your wallet's private key.
This means the participant must either have direct access to the key (less secure) or have the ability to request signatures of a device / process that has access to the key (more secure).
The direct keyfile access method is supported by
Support for offloading transaction signing to another device will arrive in a future
During integration testing, we told our participants where to find a "keyfile" that contains our encrypted private key via the
--keyfile argument to the
polyswarm-client programs (i.e.
All keyfiles distributed with
polyswarm-client (and other PolySwarm projects) are encrypted with a trivial password:
password, specified via the
keyfile's path and
password are stored in
Production / marketplace keyfiles must be treated differently than keyfile used for testing.
Never use any keyfile included in any public PolySwarm project (e.g.
polyswarm-client) when connecting to the PolySwarm marketplace.
Never fund a wallet that may have had its private key disclosed to untrusted parties or devices. The aformentioned keyfiles in
polyswarm-clientcertainly match this requirement; their private keys are available for all to see.
Wallets holding real NCT and/or ETH and are used when participating to the PolySwarm marketplace ("Production" or "Marketplace" wallets) must be securely generated and must be unique among participants.
Production wallets' private keys must be protected at rest and in use against external and insider threats.
The official Ethereum client (
geth for short) has instructions for securely generating a keyfile.
See Managing your accounts in geth.
Follow this guide on a trustworthy device to create a new keyfile that you'll use to connect to the PolySwarm marketplace.
Once you've generated your own keyfile, you'll need to fund your wallet with ETH and NCT.
Generally, there are three funding avenues available:
- Purchase ETH and NCT on a cryptocurrency exchange and transfer them to the address corresponding to your participant's wallet. Methods to purchase & transfer cryptocurrencies are outside the scope of this document.
- Subscribe to PolySwarm Direct - an upcoming service with configurable auto-refills that ensure your participant is funded. This service is in development, stay tuned!
- Initial partners have received a NCT seedling in their production wallet per our published distribution schedule.
The PolySwarm marketplace is made up of a patchwork of Communities. Communities are groups of individuals and corporations that share a particular malware interest or mutually agree to maintain the confidentiality of artifacts exchanged within the Community.
Unless overridden, participants based on
polyswarm-client will connect to the current default public community.
To connect to a different community, use the
--polyswarmd-addr argument or associated environment value to override this default.
The default public community is a "proving ground" of sorts for security experts to build a reputation via their participant(s). Once security experts build a reputation, they may want to engage in additional Communities.
As more communities come online, they'll appear in on the PolySwarm Communities page:
polyswarm-clientbased participants currently only support communicating with a single Community at a given time.
Support for multiple Communities will be included in a future release.
In the interim, please run a distinct instance of your participant (and supporting services like
balancemanager) per Community.
We will customize your participant's
docker/marketplace.env file and then use your participant's
docker/marketplace.yml file to connect to the PolySwarm marketplace.
marketplace.envwere added to
participant-templateon Oct 12th, 2019.
If your participant lacks these files, you will need to rebase your participant on a more recent
marketplace.yml is responsible for launching everything you need to connect to the marketplace: your participant's
worker backend and
This YAML relies on values contained within
marketplace.env, which we'll customize now.
marketplace.yml relies on
marketplace.env for the following information:
- The in-container file path of your participant's marketplace
passwordused to decrypt your participant's marketplace
- A valid API key for the community you wish to join.
Place your newly generated production keyfile in a location that will be accessible to containers launched from your participant's Docker image.
For simplicity, we'll assume you place this
keyfile in the root of your participant's directory:
Launch your favorite text editor and edit
KEYFILE= variable to point to the container-accessible path you chose for your participant's
marketplace.envmust not be enclosed in single or double quotations.
Don't do this:
PASSWORD= variable with the encryption password you chose when creating your
To obtain your API key for the default public community, sign up at PolySwarm, click your name in the top right corner and select Settings. Your API key(s) will be displayed in the API Keys tab.
API_KEY= variable with your API key.
marketplace.env configured, connecting to the marketplace is as simple as running the following from the root directory of your participant:
$ docker-compose -f docker/marketplace.yml up
You should see various log output indicating connection to the marketplace.
If you're running a microengine, check that everything is running smoothly by uploading an artifact to the marketplace and looking for your engine's
keyfile address in the scan results set.
If you haven't already, you'll want to claim your microengine so that you can name it.
Congratulations, you're connected to the PolySwarm marketplace!
Recall that each community has a distinct sidechain where PolySwarm transactions occur. In order to participate, you'll need to maintain a balance of NCT (ETH not required) on the Community's sidechain.
We've made this easy: you can use
You'll need to run both your participant and a
balancemanager to maintain a balance of NCT on the Community sidechain.
Windows users will recall running
balancemanager from the integration testing instructions.
Linux users had
balancemanager handled for them by Docker transparently.
balancemanager can be run in three modes:
deposit: deposit the configured amount of NCT onto the Community and exit
withdraw: withdraw the configured amount of NCT from the Community and exit
maintain: continually ensure a configurable balance of NCT in the Community
Most users will want to simply
maintain a balance - we'll dive into using this functionality below.
Advanced users may want to manually