v1.0

Polaris 1.0 Overview

Polaris' development has been incremental, so 1.0 does not introduce any major features or changes to the data model. Rather it serves as a benchmark of the software's maturity and completeness.

In general, Polaris offers support for full implementations of:

• SEP-1 TOML files
• SEP-6 Noninteractive Deposit and Withdrawal
• SEP-10 Authentication
• SEP-12 Customer KYC Information
• SEP-24 Interactive Deposit & Withdrawal
• SEP-31 Direct Fiat-to-Fiat Payments

Polaris implements the API's defined in each SEP, the processes needed for periodic tasks, and the core data model used to facilitate the protocols listed above. Polaris also provides an integration interface, or set of classes and functions, that allow anchors to implement logic specific to their organization and business needs.

Integrations

• DepositIntegration and WithdrawalIntegration
  • Used for SEP-6 and SEP-24 form and transaction processing
• SEP31ReceiverIntegration
  • Used for processing SEP-31 payments
• CustomerIntegration
  • Used for SEP-12 KYC/Customer information management
• RailsIntegration
  • Used for connecting to the anchor's off-chain banking or payment rails
• JavaScript integration
  • Used to add client-side JS code to HTML pages displayed to SEP-24 users
• TOML integration
  • Used to add attributes defined in SEP-1 to the stellar.toml file
• Fee integration
  • Used for calculating custom fee amounts for SEP-24 transactions

1.0 Changelog

Features

• A testnet command was added to make issuing assets and testnet resets easier
• Polaris now fully supports logging via the logging standard python package
• PolarisSameSiteMiddleware is no longer required for SEP-24 anchors
• All environment variables can be listed in settings.py by prepending the variable name with 'POLARIS_'
  • This strategy comes with security concerns. Ensure your secrets are never checked into source control
• SEP-12 PUT /customer requests can use the id parameter as recently added to the SEP

Breaking Changes

• All polaris-specific variables defined in settings.py must now be prepended with 'POLARIS_'
  • This applies to ACTIVE_SEPS and ENV_PATH
  • As well as any environment variables specified within the settings.py file
• The scripts integration function must now return a list of TemplateScript objects
  • TemplateScript objects contain a JS source file path and other meta data
• The SEP-12 .delete() integration function now must raise the Django exception ObjectDoesNotExist for 404 HTTP responses
  • This exception replaces ValueError
• SEP-31 GET /customer was updated to include a 404 response
  • Polaris' .get() integration function should raise ObjectDoesNotExist for 404, ValueError for 400

Database Changes

There are no schema changes from 0.13.2 to 1.0. However, 1.0 squashes all migrations files generated prior to this release. Make sure to update your database's django_migrations table by deleting all migrations after 0001_initial where app='polaris'. This will ensure the eventual second migration will be applied properly.

v0.13.2

Includes migrations, bug fixes, and a previously-missing feature.

Features

• SEP-24 has an optional amount parameter that can be specified in POST /transactions/interactive/deposit API calls. Polaris now supports this parameter.
  • Previously wallets would have to append the amount field to the provided interactive URL.

Migrations

• Increases the maximum character limit for Transaction.status from 30 to 31.
  • pending_transaction_info_update is 31 characters, so if this status were assigned it would raise an error, effectively blocking transaction info updates.
• Removes the default value for Asset.code and makes the column nullable

Bug Fixes

• The first migration mentioned above
• When information submitted in forms is invalid, the evaluated form is not re-rendered in the template. Now, forms are re-rendered as expected
  • This bug was introduced with the form_for_transaction() integration function.

v0.13.1

This patch release fixes a major SEP-31 bug released in versions 0.12 and 0.13.

SEP-31's old pending_info_update status was split into two new statuses here:

• pending_transaction_info_update
• pending_customer_info_update

However, Polaris continued to use pending_info_update. This makes SEP-31 Polaris anchors almost unusable by clients because they would have to watch for the old status and check both the SEP-12 GET /customer endpoint and the GET /transaction to determine what type of update is necessary. Developers using Polaris would also have to intentionally use the old status to remain consist with Polaris' behavior.

This release removes pending_info_update as a valid status and adds the pending_transaction_info_update and pending_customer_info_update statuses.

This release also corrects a small bug in the /transactions endpoint schema.

• Transaction.required_info_update --> Transaction.required_info_updates

Releases 0.12 and 0.13 will be removed from PyPi in the near future to prevent unassuming users from running a faulty SEP-31 service.

v0.13.0

This release contains many breaking changes, all in preparation for 1.0.

DB Changes

• Asset.withdraw_anchor_account and sender_anchor_account have been merged into receiving_anchor_account
• Transaction.deposit_memo, withdraw_memo, and send_memo have been merged into memo
• Transaction.deposit_memo_type, withdraw_memo_type, and send_memo_type have been merged into memo_type
• Asset.send_fee_percent and send_fee_fixed were given defaults of 0 instead of being nullable

Breaking Changes

General:

• Some keyword arguments for register_integrations() have been changed
  • toml_func --> toml
  • fee_func --> fee
  • scripts_func --> scripts,
  • info --> sep6_info
  • send --> sep31_receiver
• Transaction.amount_fee must be calculated by the anchor from poll_pending_deposits() or execute_outgoing_transactions()
  • Polaris will still attempt to calculate Transaction.amount_fee if there is no registered fee function
• PROJECT_ROOT is no longer used from settings.py. Polaris will now use BASE_DIR by default and ENV_PATH if specified.

SEP 6 & 24:

• content_for_transaction() has been replaced by two functions
  • form_for_transaction(): returns the next form to be served to the user during the interactive flow
  • content_for_template(): returns a dictionary containing customizable attributes for the template to be rendered to the user
  • This was implemented so content_for_template() could be called for requests to Polaris transaction/more_info endpoint
• Added icon_path field to the list of allowed keys-value pairs returned from content_for_template()
  • If not present, Polaris will try to use the ORG_LOGO URL returned from the anchor's registered toml function
  • This replaces the need to create a company_icon.svg file
• process_sep6_request() is now passed an unsaved Transaction object representing the transaction to be created
  • the transaction passed should only be saved if the request is valid

SEP31:

• The SEP-31 API itself was changed. See the changes to understand why some of the following Polaris changes were made
• SendIntegration has been renamed to SEP31ReceiverIntegration following related changes to the SEP
  • process_send_request() --> process_post_request()
  • process_update_request() --> process_patch_request()
• process_post_request() is now passed an unsaved Transaction object instead of the transaction ID
  • This mirrors the solution implemented for process_sep6_request()

Bug Fixes

• Added SEP-31 transactions query for most-recently completed transactions (used in watch_transactions)
• SEP-10 no longer attempts to decode request bodies manually (this was a problem when using charset in request headers)
• Polaris no longer uses hard-coded XDR error strings to detect errors when making SEP-24 deposits
• Polaris now uses the correct fee columns on the Transaction when users don't calculate the fee themselves

v0.12.0: SEP-31 Support

Features

• Full SEP-31 support. See the documentation on the integration constructs provided
• Updates to SEP-12. (See #588, #653, #669, #674, and #681)

Breaking Changes

• Moved DepositIntegration.poll_pending_deposits() to RailsIntegration.poll_pending_deposits()
• Replaced WithdrawalIntegration.process_withdrawal() with RailsIntegration.execute_outgoing_transaction()
  • SEP-6 and 24 transactions uses this function now instead of process_withdrawal
• Polaris no longer calls the registered_fee_function except when requests to /fee are made.
  • The anchor is now responsible for calculating the fee in poll_pending_deposits() and execute_outgoing_transaction()
• Removed Transaction.external_extra
• Removed Transaction.external_extra_text

DB Migrations

Added SEP-31 columns:

• Asset.sep31_enabled: a boolean for whether the asset can be received via SEP-31
• Asset.send_fee_percent: the 0-100 percentage value for fees on a transaction
• Asset.send_fee_fixed: the fixed fee charged per transaction
• Asset.send_min_amount: the minimum amount the anchor accepts in a transaction
• Asset.send_max_amount: the maximum amount the anchor accepts in a transaction
• Transaction.required_info_update: a text field for describing required updates to the transaction
• Transaction.required_info_message: a text field for a human-readable message about updates to the transaction
• Transaction.send_memo: the memo used when making the Stellar payment to the receiving anchor
• Transaction.send_memo_type: the memo type of the memo used
• Transaction.send_anchor_account: the anchor's Stellar address for receiving payments

Bug Fixes

• Fixed Polaris' validate_language() function to only allow supported languages
  • prior to this release Polaris would not automatically return 400 for requests in languages not supported by the anchor

v0.11.2

0.11.0 and 0.11.1 releases will be removed from PyPI, since they contain the bugs documented below.

Features

• Added endpoint and integrations for SEP-12's new GET /customer endpoint

Dependencies

• Upgrades stellar-sdk from 2.4 to 2.6.1

Breaking Changes

• CustomerIntegration.put integration now must return a customer ID (string)

Bug Fixes

• requests to SEP-12's DELETE /customer endpoint no longer causes a 500 Server Error
• removes the fee & total widget on interactive flow UI pages, unless amount field is displayed

v0.11.1

Features

• No longer requires HTTPS for local deployments
• No longer requires all-origin access to non-Polaris endpoints
• Displays fee amount in real time on SEP-24 transaction amount forms
• Encrypts Asset.distribution_seed in the database, decrypts when brought into memory

Dependencies

• Removes sslserver dependency (make sure to remove from INSTALLED_APPS)

Database Migrations

• Adds migrations to encrypt Asset.distribution_seed values
• Adds Asset.symbol for SEP-24 amount form field currency symbol

Bug Fixes

• No longer requires withdraw amounts sent to the anchor to match the amount specified in the SEP-24 interactive flow
• No longer returns 500 error for bad account string to SEP-10 /auth endpoint

Miscellaneous

• Removes authentication_required from SEP-24 /fee endpoint
• Creates withdrawal memo after SEP-24 interactive flow completes
• Adds amount_out field to more_info.html page (amount_in - fee)

v0.11.0: SEP-6 Support

The updated documentation

Features

• Adds SEP-6 and 12 support
• Deploy each supported SEP (1, 6, 10, 12, 24) independently.
  • For example, you could run Polaris strictly with SEP-1 and SEP-10

Dependencies

• Removes django-compressor, django-sass-processor, and libsass from requirements
  • sass_processor should no longer be listed in INSTALLED_APPS
  • SASS_PROCESSOR_ROOT and STATICFILES_FINDERS settings are no longer needed
• Upgrades stellar-sdk to 2.4.0
  • This is necessary to support Protocol 13

Breaking Changes

• ACTIVE_SEPS must be present in your settings file.
  • It must contain the SEPs you wish to run, ex. ["sep-1", "sep-10", "sep-24"]
• SIGNING_SEED environment variable is required
  • This used to default to the anchored asset's distribution account
• Custom static assets overriding static assets from Polaris must be placed under a polaris subdirectory within your static files directory

Database Migrations

• Adds distribution_seed column and distribution_account property to Asset model
  • When running migrations, these columns will be populated from the now unused ASSETS environment variables, if present
• sep24_enabled and sep6_enabled columns added to Asset model
  • All existing assets will be sep-24 enabled when running migrations
• protocol column added to Transaction model

Miscellaneous

• use of ASSETS, *_DISTRIBUTION_ACCOUNT_SEED, and *_ISSUER_ACCOUNT_ADDRESS environment variables are removed
  • These have been replaced by the distribution_seed and issuer database columns
• DEFAULT_PAGE_SIZE setting is no longer used
• All SEP-24 endpoints have been moved under a /sep24 argument path. This was done so they would not conflict with endpoints from SEP-6, which are under a /sep6 path

v0.10.4

Breaking Changes:

• The "form" key from content_for_transaction()'s return value must be an instance of django.forms.Form
• content_for_transaction() additionally accepts two keyword arguments, post_data and amount

These change was made so anchors could initialize their own forms. This is particularly useful for pre-populating form fields with values from SEP-9.

• TransactionForm.__init__() requires a Transaction instead of an Asset

This fixes a bug. TransactionForm was previously validating withdrawal amounts against deposit asset limits.

Features

• Adds the integration function save_sep9_fields() to both DepositIntegration and WithdrawalIntegration classes. This function allows anchors to store SEP-9 values passed by the wallet to the deposit/interactive and withdraw/interactive endpoints.

DB Changes

• Transaction.paging_token was added as a nullable text field

Bug Fixes

• Transaction.started_at and Transaction.completed_at are now recorded as datetimes in UTC.
  • Previously, they were recorded in the time zone specified by the anchor using Django's USE_TZ and TIME_ZONE settings.
• The watch_transactions management command now streams transactions from Horizon starting from the most recently completed withdraw.
  • Previously, watch_transactions started from "now", which means the anchor could've potentially missed incoming withdrawal transactions if the process went down.
• Transaction.stellar_transaction_id is now saved for withdrawal transactions. Previously, it was only saved for deposit transactions.

Miscellaneous

• Added TRANSFER_SERVER_0024 to the stellar.toml file
• Endpoints return 403 on bad or missing JWT tokens, instead of 400

v0.10.3

Breaking Changes:

• allows anchors to pass arguments for form initialization by adjusting content_for_transaction()'s return type

DB Changes:

• added the refunded column to the Transaction model
• fixed Transaction.to_address and Transaction.from_address population bug

Bug Fixes:

• Selecting the Submit button on forms no longer submits the request twice
• Decimal values are now always displayed with the correct number of decimal numbers

Miscellaneous:

• added human-readable (and translatable) strings for each Transaction.status value