Manager

The PlasmaRifle Root-chain Manager

The PlasmaRifle Root-chain Manager contract manages the bridge between Ethereum and the Gunero network. It creates a public signal that the child-chain follows to manage entries and exits from the zero-knowledge trading system that the validating nodes manage through their consensus protocol. It also allows network participants the ability to retain control over their assets in the child-chain by exiting from the chain's control and returning their tokens back into their own control if the network is ultimately experiencing consensus failure or transaction censorship.

The functionality described below enables owners of tokenized firearms to perform these actions.

Entry (aka Locking)

Property	Value
API	deposit(tokenId, txnIdHash) (note: onERC721Received(data))
Who can do it?	owner of tokenId (must be Auth'd)
When can they do it?	Anytime
Can they be challenged?	Yes, see challengeDeposit(...) below

The Deposit function allows the token's owner to transfer control of the token into the child chain network, which unlocks zero-knowledge transfers according to the rules of the Gunero network. This assumes that the Manager contract can assume control of tokenId from the current owner at the time the function was called. Note that only currently authorized accounts can access this functionality. This only applies to the deposit(...) functionality, exits can be initiated even if the user is not currently able to trade the underlying token.

We provide this functionality directly through onERC721Received(data) in the manager contract, which can be called via the safeTransferFrom() function in the Token contract. Note that the deposit() function is private due to this reason.

Due to re-tokenization of the underlying asset in case of loss of access to that token, this deposit process may be duplicating a token for a firearm already in circulation in Gunero. This duplicate is undesirable, and represents a disconnect in the provenance chain of that firearm. Since GunClear has no advanced knowledge of ownership in the system, proclaiming a token to be a duplicate opens a potential griefing attack of current token owners in the Gunero network; therefore, no assumptions are made about ownership. Dispute of this duplication is managed through this contract with the duplicate(...)/remove(...) and challengeDeposit(...) workflow, described below.

tokenId and txnIdHash are broadcast to the validators of the Gunero network, who modify the token database entry for tokenId to txnIdHash if the current entry is empty (according to consensus rules).

Declare a Duplicate

Property	Value
API	duplicate(newTokenId, oldTokenId)
Who can do it?	only the GunClear Authority
When can they do it?	Only if newTokenId and oldTokenId are locked
Can they be challenged?	Yes, see challengeDeposit(...) below

The GunClear Authority, who manages a list of serial numbers to tokenIds in order to manage token minting, detects a serial number with 2 conflicting tokenIds representing it locked into the Gunero network. This actually happens prior to GunClear minting a new token that is deposited into the contract using deposit(...). It is therefore assumed that GunClear has done their due diligence in verifying the new owner's attestation that they own that firearm, and made a decision to allow it by minting them a token. By executing the duplicate(...) function, GunClear is placing the onus on the owner of the oldTokenId to make a rebuttal through challengeDeposit(...) to this claim, which reveals partial ownership information to GunClear so it can conduct a further investigation of the two parties involved and their claims.

The duplicate(...) function sets a timer for the 28-day dispute period. If the claim goes unchallenged for that time period, then GunClear is allowed to finalize the claim and burn the orphaned token using the remove(...) function.

Remove a Duplicate

Property	Value
API	remove(tokenId)
Who can do it?	only the GunClear Authority
When can they do it?	After the dispute period for tokenId expires
Can they be challenged?	No

As noted above, after the 28 day dispute period from when the duplicate was logged, if the claim goes unchallenged then the GunClear Authority can destroy tokenId, removing that token from the Gunero trading network permanently.

It is therefore important that clients listen and respond to duplicate claims against tokens in their owner's possession, as it may indicate a failure of GunClear Authority to properly manage the platform, or someone attempting to leverage stolen records from that individual.

Exit (aka Unlocking)

Property	Value
API	exit(tokenId, txnBlkNum, plasmaProof)
Who can call?	last owner of tokenId in plasma-chain before burning
When can they call?	One Plasma sync cycle after a "burn" Plasma txn
Who can challenge?	No one

The Exit function allows the token's current owner in the Gunero network to exit their token from the Gunero network, removing it's ability to be transferred according to the rules of the network. Due to the "Zero Knowledge" property of Gunero it is not possible to know who the owner is of the token directly, but thanks to the usage of the Simple Merkle Tree (SMT) data structure for the database that Plasma Cash uses (which Gunero is derived from), it is possible to prove the current state of token ownership directly via a Merkle proof. This assumes that the consensus management does not make invalid modifications to the tree (there is no current mitigation for this). Assuming that, finality is a strong feature of the Plasma Cash formulation, which we rely on.

The first step in conducting an exit is to have the user "burn" their token by sending it to a predefined address with a stored private key, with a corresponding key that is authorized to "trade" but cannot actually hold tokens. This private key is special because our SNARK is designed to reject spending from a key with that particular value, therefore a proof of spend-ability is never possible after sending using this key. The exit procedure must occur at least one sync cycle after this burn transaction is conducted. The user will provide the tokenId they wish to exit, the txnBlkNum of when that that transaction occurred, and a plasmaProof showing the merkle branch to that transaction is consistent with the data provided for tokenId. It should go without saying, but do not use this key for anything else!

Because the private key is known, TXNID=keccak(s_b, P_a, A, T) is directly computable: s_b is that private key, P_a must be the public key recovered from the transaction signature for the exit, A is the authorization tree root stored from when the transaction was performed (at txnBlkNum), and T is the tokenId the user wishes to exit. TXNID is then used to validate the Merkle root from the last synchronized Plasma root using plasmaProof. If all succeeds, ownership of the token will be transferred to the transaction submitter. A successful exit procedure will then have the Gunero validators remove it from tracking in the Gunero SMT.

If the tokenId being exited is currently claimed to be a duplicate, the process will actually burn both the exited token and it's duplicate, immediately removing both from the circulating supply. GunClear will use this opportunity to review the documentation provided by both participants, minting a new token for the owner that is confirmed through GunClear's review process, and potentially removing the authorization status of the user who is proven to have been acting malevolently. The fact that ownership history is partially revealed through this process (only to GunClear, who knows each participant and firearm separately) we believe mitigates malevolent usage of our review process as much as possible.

We believe this process is maximally fair to both participants, and gives GunClear the widest set of options when resolving complex documentation claims, without revoking an individual's right to digital sovereignty and conserving ownership privacy as much as is possible.

---

A primary use case of the exit procedure in PlasmaRifle is actually an attestation of loss or theft of the physical firearm. This allows a user to burn their token, which GunClear may use to blacklist that firearm from future tokenization unless that user re-discovers the firearm. Any exit can be "canceled" by the attestor by re-tokenizing the firearm, allowing trading of the firearm on the Gunero chain again after an additional data review process to re-mint the token.

Another use case is to allow moving the token to the platforms of any competitors GunClear may have, or to simply allow public, unsanctioned trading of that firearm token, which we don't disallow. An authorized user can deposit their token back into the system at any time, acknowledging that the trading history outside of the GunClear system is publicly available, which we may reject if the firearm's public-chain history is questionable.

The use-cases of the token may be more than we can envision at this time. Tokenization of the firearm could be leveraged in other ways we don't anticipate, and we take a cautious but optimistic approach to innovation in this regard.

"Hot Potato!" or Forwarded Exit (aka release of ownership) [MVP Only]

To be determined...