CLI Commands¶
Deploying Polaris¶
Implementing SEP 6, 24, or 31 requires more than a web server. Anchors must also stream incoming transactions to their asset’s distribution accounts, check for incoming deposits to their off-chain accounts, confirm off-chain transfers, and more.
To support these requirements, Polaris deployments must also include additional services to run alongside the web server. The SDF currently deploys Polaris using its CLI commands. Each command either periodically checks external state or constantly streams events from an external data source.
With the exception of watch_transactions
, every CLI command can be run once or repeatedly on some interval using the --loop
and --interval <seconds>
arguments. These commands should either be run by a job scheduler like Jenkins and CircleCI or run with the --loop
argument.
watch_transactions¶
This process streams transactions to and from each anchored asset’s distribution account. Outgoing transactions are filtered out, and incoming transactions are matched with pending SEP 6, 24, or 31 transactions in the database using the memo field. Matched transactions have their statuses updated to pending_receiver
for SEP-31 and pending_anchor
for SEP-6 and 24.
execute_outgoing_transactions¶
This process periodically queries for transactions that are ready to be executed off-chain and calls Polaris’ RailsIntegration.execute_outgoing_transaction
integration function for each one. “Ready” transactions are those in pending_receiver
or pending_anchor
statuses, among other conditions. Anchor are expected to update the Transaction.status
to completed
or pending_external
if initiating the transfer was successful.
poll_outgoing_transactions¶
Polaris periodically queries for transactions in pending_external
and passes them to the RailsIntegration.poll_outgoing_transactions
. The anchor is expected to update the transactions’ status depending on if the transfer has been successful or not.
poll_pending_deposits¶
Polaris periodically queries for transactions in pending_user_transfer_start
and pending_sender
and passes them to the RailsIntegration.poll_pending_deposits
integration function. The anchor is expected to update the transactions’ status depending on the if the funds have become available in the anchor’s off-chain account.
check_trustlines¶
And finally, Polaris periodically checks for transactions whose accounts don’t have trustlines for the asset the account is requesting using the pending_trust
status. Polaris will update Transaction.status
for each transaction that has a trustline to the relevant asset.
If you choose to deploy Polaris using this strategy, ensure the processes are managed and kept persistent using a process-control system like supervisorctl
.
Testnet Resets¶
If you’re running your anchor service on testnet, you’ll need to reset Polaris’ state every time the network resets. Polaris comes with a command that automates this process.
testnet¶
The testnet
command comes with two subcommands, issue
and reset
.
issue
allows users to create assets on the Stellar testnet network, porting the functionality originally offered by the create-stellar-token tool. When the test network resets, you’ll have to reissue your assets.
reset
calls the functionality invoked with issue
for each asset in the anchor’s database. Since the database does not store the issuing account’s secret key, the user must input each key as requested by the Polaris command. It also performs a couple other functions necessary to ensure your Polaris instance runs successfully after a testnet reset:
- Moves all
pending_trust
transactions toerror
This is done because all accounts have been cleared from the network. While its possible an account that required a trustline could be recreated and a trustline could be established, its unlikely. Polaris assumes a testnet reset makes in-progress transactions unrecoverable.
- Updates the
paging_token
of latest transaction streamed for each anchored asset
watch_transactions
streams transactions to and from each anchored asset’s distribution account. Specifically, it streams transactions starting with the most recently completed transaction’s paging_token
on startup. When the testnet resets, the paging_token
used for transactions prior to the reset are no longer valid. To fix this, Polaris updates the paging_token
of the most recently completed transaction for each anchored asset to "now"
.