Similar to centralized exchanges where the administrators have full control over your balance, issuers of a User-Issuer asset on BitShares can decide to claim this control for their own assets. By this, they could technically reverse accidential transfers (probably at the loss of credibility). This article shows how this can be done from the technical perspective.

Special Permissions

The issuer of an asset has special permissions over his asset. More precisely: the issue can obtain special permissions. These special permissions are

• Require holders of the asset to be whitelisted (for advanced users)
• Transfer shares back to the issuer or somewhere else
• Require the issuer to approve all transfers (this requires the use of proposal, for advanced users)
• Disable confidential transactions so that all balances and amounts are always public

Permissions and Flags

As mentioned above, the issuer can obtain special permissions. This can be done by setting a so called flag to enable the special permission. As long as the special flags are or net, the blockchain wont allow the usage of these extra permissions. This is to publicly broadcast that the issuer is going to make use of this flag.

Since the issuer can set the flags at any time, how could one ever trust the issuer not to misuse his powers or, after an attack fear that an attacker has gained access over the asset? Well, this can be done by the permissions, which can be used by the issuer to defeinitely opt-out of one or more of these extra permissions! Once an issuer has removed the permission to transfer funds from any account, he will never again be able to obtain this privilege.

Reversing Transfers

As mentioned above (and I want to emphasis this here), the issuer can only reverse transfers for the assets he created!

Enabling the flag

First we need to enable the special permissions Issuer may transfer asset back to himself (technically called override-transfer) in the assets settings. Make sure to enable the flag and not disable the permission (better not even touch permissions unless you REALLY know what you are doing!!)
After enabling the flag, make sure to properly update your asset so that the blockchain knows about the change.

Constructing a Reversing Transfer Operation

To use the override-transfer feature, there is a special operation called oeverride-transfer-operation (how obvious). It takes the following form:

[
  38,{
    "issuer": "1.2.0",
    "from": "1.2.0",
    "to": "1.2.0",
    "amount": {
      "amount": 0,
      "asset_id": "1.3.0"
    },
    [...]
  }
]

It almost looks like a regular transfer operation with the differences that the operation id is 39 and an additional field issuer. If the parameters above are properly set, and the transaction is signed by the issuer, then the transaction is valid and will be added to the blockchain (after checking for double spends, permissions etc.).

The transaction history will show a new entry similar to:

Python Script

To simplify the usage of this feature, I wrote a simple script that only requires a few settings to be made:

issuer = "xeroc"
from_account = "maker"
to_account = "xeroc"
asset = "LIVE"
amount = 100.0
wifs = ["<active-wif-key-of-issuer>"]
witness_url = "ws://testnet.bitshares.eu/ws"

If you don't know what to do with witness_url, you shouldn't read this article :)

Before you can use this script, make sure you install a recent version of the python-grapehenlibs. If it complains about missing methods, try to install from the github develop branch!