Merge pull request #30 from coinbase/patrick/sync-status

Add Coin Model
coinbase · Jul 25, 2020 · 5c2ad99 · 5c2ad99
2 parents 0d12fa7 + 53c18a9
commit 5c2ad99
Show file tree

Hide file tree

Showing 7 changed files with 191 additions and 0 deletions.
diff --git a/api.json b/api.json
@@ -941,6 +941,9 @@
          "amount": {
            "$ref":"#/components/schemas/Amount"
           },
+         "coin_change": {
+           "$ref":"#/components/schemas/CoinChange"
+          },
          "metadata": {
            "type":"object",
            "example": {
@@ -1190,6 +1193,60 @@
          "ed25519"
         ]
       },
+     "CoinAction": {
+       "description":"CoinActions are different state changes that a Coin can undergo. When a Coin is created, it is coin_created. When a Coin is spent, it is coin_spent. It is assumed that a single Coin cannot be created or spent more than once.",
+       "type":"string",
+       "enum": [
+         "coin_created",
+         "coin_spent"
+        ]
+      },
+     "CoinIdentifier": {
+       "description":"CoinIdentifier uniquely identifies a Coin.",
+       "type":"object",
+       "required": [
+         "identifier"
+        ],
+       "properties": {
+         "identifier": {
+           "description":"Identifier should be populated with a globally unique identifier of a Coin. In Bitcoin, this identifier would be transaction_hash:index.",
+           "type":"string",
+           "example":"0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
+          }
+        }
+      },
+     "CoinChange": {
+       "description":"CoinChange is used to represent a change in state of a some coin identified by a coin_identifier. This object is part of the Operation model and must be populated for UTXO-based blockchains. Coincidentally, this abstraction of UTXOs allows for supporting both account-based transfers and UTXO-based transfers on the same blockchain (when a transfer is account-based, don't populate this model).",
+       "type":"object",
+       "required": [
+         "coin_identifier",
+         "coin_action"
+        ],
+       "properties": {
+         "coin_identifier": {
+           "$ref":"#/components/schemas/CoinIdentifier"
+          },
+         "coin_action": {
+           "$ref":"#/components/schemas/CoinAction"
+          }
+        }
+      },
+     "Coin": {
+       "description":"Coin contains its unique identifier and the amount it represents.",
+       "type":"object",
+       "required": [
+         "coin_identifier",
+         "amount"
+        ],
+       "properties": {
+         "coin_identifier": {
+           "$ref":"#/components/schemas/CoinIdentifier"
+          },
+         "amount": {
+           "$ref":"#/components/schemas/Amount"
+          }
+        }
+      },
      "AccountBalanceRequest": {
        "description":"An AccountBalanceRequest is utilized to make a balance request on the /account/balance endpoint. If the block_identifier is populated, a historical balance query should be performed.",
        "type":"object",
@@ -1227,6 +1284,13 @@
              "$ref":"#/components/schemas/Amount"
             }
           },
+         "coins": {
+           "type":"array",
+           "description":"If a blockchain is UTXO-based, all unspent Coins owned by an account_identifier should be returned alongside the balance. It is highly recommended to populate this field so that users of the Rosetta API implementation don't need to maintain their own indexer to track their UTXOs.",
+           "items": {
+             "$ref":"#/components/schemas/Coin"
+            }
+          },
          "metadata": {
            "description":"Account-based blockchains that utilize a nonce or sequence number should include that number in the metadata. This number could be unique to the identifier or global across the account address.",
            "type":"object",

diff --git a/api.yaml b/api.yaml
@@ -610,6 +610,14 @@ components:
       $ref: 'models/Signature.yaml'
     SignatureType:
       $ref: 'models/SignatureType.yaml'
+    CoinAction:
+      $ref: 'models/CoinAction.yaml'
+    CoinIdentifier:
+      $ref: 'models/CoinIdentifier.yaml'
+    CoinChange:
+      $ref: 'models/CoinChange.yaml'
+    Coin:
+      $ref: 'models/Coin.yaml'
 
     # Request/Responses
     AccountBalanceRequest:
@@ -647,6 +655,15 @@ components:
             A single account may have a balance in multiple currencies.
           items:
             $ref: '#/components/schemas/Amount'
+        coins:
+          type: array
+          description: |
+            If a blockchain is UTXO-based, all unspent Coins owned by an account_identifier
+            should be returned alongside the balance. It is highly recommended to
+            populate this field so that users of the Rosetta API implementation
+            don't need to maintain their own indexer to track their UTXOs.
+          items:
+            $ref: '#/components/schemas/Coin'
         metadata:
           description: |
             Account-based blockchains that utilize a nonce or sequence number

diff --git a/models/Coin.yaml b/models/Coin.yaml
@@ -0,0 +1,26 @@
+# Copyright 2020 Coinbase, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+description: |
+  Coin contains its unique identifier and the amount
+  it represents.
+type: object
+required:
+  - coin_identifier
+  - amount
+properties:
+  coin_identifier:
+    $ref: 'CoinIdentifier.yaml'
+  amount:
+    $ref: 'Amount.yaml'
diff --git a/models/CoinAction.yaml b/models/CoinAction.yaml
@@ -0,0 +1,23 @@
+# Copyright 2020 Coinbase, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+description: |
+  CoinActions are different state changes that a Coin can
+  undergo. When a Coin is created, it is coin_created. When a Coin is
+  spent, it is coin_spent. It is assumed that a single Coin
+  cannot be created or spent more than once.
+type: string 
+enum:
+  - coin_created 
+  - coin_spent
diff --git a/models/CoinChange.yaml b/models/CoinChange.yaml
@@ -0,0 +1,33 @@
+# Copyright 2020 Coinbase, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+description: |
+  CoinChange is used to represent a change in state of
+  a some coin identified by a coin_identifier. This object
+  is part of the Operation model and must be populated for
+  UTXO-based blockchains.
+
+  Coincidentally, this abstraction of UTXOs allows for supporting
+  both account-based transfers and UTXO-based transfers on the
+  same blockchain (when a transfer is account-based, don't
+  populate this model).
+type: object 
+required:
+  - coin_identifier
+  - coin_action
+properties:
+  coin_identifier:
+    $ref: 'CoinIdentifier.yaml'
+  coin_action:
+    $ref: 'CoinAction.yaml'
diff --git a/models/CoinIdentifier.yaml b/models/CoinIdentifier.yaml
@@ -0,0 +1,26 @@
+# Copyright 2020 Coinbase, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+description: |
+  CoinIdentifier uniquely identifies a Coin.
+type: object
+required:
+  - identifier 
+properties:
+  identifier:
+    description: |
+      Identifier should be populated with a globally unique identifier
+      of a Coin. In Bitcoin, this identifier would be transaction_hash:index.
+    type: string
+    example: "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
diff --git a/models/Operation.yaml b/models/Operation.yaml
@@ -59,6 +59,8 @@ properties:
     $ref: 'AccountIdentifier.yaml'
   amount:
     $ref: 'Amount.yaml'
+  coin_change:
+    $ref: 'CoinChange.yaml'
   metadata:
     type: object
     example: