@dashevo/document-history-contract 4.1.0-beta.2

package/.mocharc.yml

@@ -0,0 +1,2 @@
+require: test/bootstrap.js
+recursive: true

package/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "document-history-contract"
+description = "Document history data contract schema and tools"
+version.workspace = true
+edition = "2021"
+rust-version.workspace = true
+license = "MIT"
+
+[dependencies]
+thiserror = "2.0.12"
+platform-version = { path = "../rs-platform-version" }
+serde_json = { version = "1.0" }
+platform-value = { path = "../rs-platform-value" }

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Dash Core Group, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# Document History Contract
+
+[![Build Status](https://github.com/dashpay/platform/actions/workflows/release.yml/badge.svg)](https://github.com/dashpay/platform/actions/workflows/release.yml)
+
+System data contract recording document transfer, purchase, and price-change
+events for document types that opt in via the `keepsTransferHistory`,
+`keepsPurchaseHistory`, and `keepsPricingHistory` configuration flags.
+
+History documents are written by the protocol itself during document
+transfer, purchase, and price-update state transitions
+(`creationRestrictionMode: 2` — they can never be created directly), and are
+immutable and permanent once written.
+
+The document types carry provable aggregation trees:
+
+- `purchase` is doctype-averageable on `price` (O(1) provable all-time sale
+  count, total volume, and average sale price), and its `byContract` and
+  `byDocument` indices are range-averageable over `$createdAt` (provable
+  per-contract and per-document sale count / volume / average between dates).
+- `priceUpdate` is doctype-countable, and its `byContract` and `byDocument`
+  indices are range-averageable over `$createdAt` (provable average asking
+  price between dates). These are listing-event-weighted averages, not
+  time-weighted prices.
+- `transfer` is doctype-countable, and its `byContract` index is
+  range-countable over `$createdAt` (provable transfer counts per contract
+  and time window).
+
+## Table of Contents
+
+- [Contributing](#contributing)
+- [License](#license)
+
+## Contributing
+
+Feel free to dive in! [Open an issue](https://github.com/dashpay/platform/issues/new/choose) or submit PRs.
+
+## License
+
+[MIT](LICENSE) © Dash Core Group, Inc.

package/eslint.config.mjs

@@ -0,0 +1,10 @@
+import baseConfig from '../../eslint/base.mjs';
+import mochaTestConfig from '../../eslint/mocha-tests.mjs';
+
+export default [
+  ...baseConfig,
+  mochaTestConfig,
+  {
+    ignores: ['dist/**', 'node_modules/**'],
+  },
+];

package/lib/systemIds.js

@@ -0,0 +1,4 @@
+module.exports = {
+  ownerId: '11111111111111111111111111111111',
+  contractId: '6voHRaoiPcfmMhbqCA9dixH98xcgPQ9UEcuaXjpVu3LD',
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@dashevo/document-history-contract",
+  "version": "4.1.0-beta.2",
+  "description": "The document history contract",
+  "scripts": {
+    "lint": "eslint .",
+    "test": "yarn run test:unit",
+    "test:unit": "mocha 'test/unit/**/*.spec.js'"
+  },
+  "contributors": [
+    {
+      "name": "Samuel Westrich",
+      "email": "sam@dash.org",
+      "url": "https://github.com/quantumexplorer"
+    }
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@dashevo/wasm-dpp": "workspace:*",
+    "chai": "^4.3.10",
+    "dirty-chai": "^2.0.1",
+    "eslint": "^9.18.0",
+    "mocha": "^11.1.0",
+    "sinon": "^18.0.1",
+    "sinon-chai": "^3.7.0"
+  }
+}

package/schema/v1/document-history-contract-documents.json

@@ -0,0 +1,304 @@
+{
+  "transfer": {
+    "type": "object",
+    "documentsMutable": false,
+    "canBeDeleted": false,
+    "creationRestrictionMode": 2,
+    "documentsCountable": true,
+    "indices": [
+      {
+        "name": "byDocument",
+        "properties": [
+          {
+            "dataContractId": "asc"
+          },
+          {
+            "documentId": "asc"
+          },
+          {
+            "$createdAt": "asc"
+          }
+        ]
+      },
+      {
+        "name": "byContract",
+        "properties": [
+          {
+            "dataContractId": "asc"
+          },
+          {
+            "$createdAt": "asc"
+          }
+        ],
+        "countable": "countable",
+        "rangeCountable": true
+      },
+      {
+        "name": "from",
+        "properties": [
+          {
+            "$ownerId": "asc"
+          },
+          {
+            "$createdAt": "asc"
+          }
+        ]
+      },
+      {
+        "name": "to",
+        "properties": [
+          {
+            "toIdentityId": "asc"
+          },
+          {
+            "$createdAt": "asc"
+          }
+        ]
+      }
+    ],
+    "properties": {
+      "dataContractId": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 32,
+        "maxItems": 32,
+        "description": "The data contract of the transferred document",
+        "position": 0,
+        "contentMediaType": "application/x.dash.dpp.identifier"
+      },
+      "documentTypeName": {
+        "type": "string",
+        "maxLength": 64,
+        "description": "The document type of the transferred document",
+        "position": 1
+      },
+      "documentId": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 32,
+        "maxItems": 32,
+        "description": "The transferred document",
+        "position": 2,
+        "contentMediaType": "application/x.dash.dpp.identifier"
+      },
+      "toIdentityId": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 32,
+        "maxItems": 32,
+        "description": "The identity the document was transferred to",
+        "position": 3,
+        "contentMediaType": "application/x.dash.dpp.identifier"
+      }
+    },
+    "required": [
+      "dataContractId",
+      "documentTypeName",
+      "documentId",
+      "toIdentityId",
+      "$createdAt",
+      "$createdAtBlockHeight"
+    ],
+    "additionalProperties": false
+  },
+  "purchase": {
+    "type": "object",
+    "documentsMutable": false,
+    "canBeDeleted": false,
+    "creationRestrictionMode": 2,
+    "documentsAverageable": "price",
+    "indices": [
+      {
+        "name": "byDocument",
+        "properties": [
+          {
+            "dataContractId": "asc"
+          },
+          {
+            "documentId": "asc"
+          },
+          {
+            "$createdAt": "asc"
+          }
+        ],
+        "averageable": "price",
+        "rangeAverageable": true
+      },
+      {
+        "name": "byContract",
+        "properties": [
+          {
+            "dataContractId": "asc"
+          },
+          {
+            "$createdAt": "asc"
+          }
+        ],
+        "averageable": "price",
+        "rangeAverageable": true
+      },
+      {
+        "name": "buyer",
+        "properties": [
+          {
+            "$ownerId": "asc"
+          },
+          {
+            "$createdAt": "asc"
+          }
+        ]
+      },
+      {
+        "name": "seller",
+        "properties": [
+          {
+            "sellerId": "asc"
+          },
+          {
+            "$createdAt": "asc"
+          }
+        ]
+      },
+      {
+        "name": "byPrice",
+        "properties": [
+          {
+            "dataContractId": "asc"
+          },
+          {
+            "price": "asc"
+          }
+        ]
+      }
+    ],
+    "properties": {
+      "dataContractId": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 32,
+        "maxItems": 32,
+        "description": "The data contract of the purchased document",
+        "position": 0,
+        "contentMediaType": "application/x.dash.dpp.identifier"
+      },
+      "documentTypeName": {
+        "type": "string",
+        "maxLength": 64,
+        "description": "The document type of the purchased document",
+        "position": 1
+      },
+      "documentId": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 32,
+        "maxItems": 32,
+        "description": "The purchased document",
+        "position": 2,
+        "contentMediaType": "application/x.dash.dpp.identifier"
+      },
+      "sellerId": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 32,
+        "maxItems": 32,
+        "description": "The identity that sold the document",
+        "position": 3,
+        "contentMediaType": "application/x.dash.dpp.identifier"
+      },
+      "price": {
+        "type": "integer",
+        "description": "The price paid for the document in credits. Unbounded integer so the property is sum-aggregatable (i64); actual values are consensus-validated non-negative credit amounts written only by the protocol",
+        "position": 4
+      }
+    },
+    "required": [
+      "dataContractId",
+      "documentTypeName",
+      "documentId",
+      "sellerId",
+      "price",
+      "$createdAt",
+      "$createdAtBlockHeight"
+    ],
+    "additionalProperties": false
+  },
+  "priceUpdate": {
+    "type": "object",
+    "$comment": "Time-range aggregates over these records are weighted by listing events: a document relisted N times in the window contributes N records. They are activity-weighted averages, not time-weighted prices.",
+    "documentsMutable": false,
+    "canBeDeleted": false,
+    "creationRestrictionMode": 2,
+    "documentsCountable": true,
+    "indices": [
+      {
+        "name": "byDocument",
+        "properties": [
+          {
+            "dataContractId": "asc"
+          },
+          {
+            "documentId": "asc"
+          },
+          {
+            "$createdAt": "asc"
+          }
+        ],
+        "averageable": "price",
+        "rangeAverageable": true
+      },
+      {
+        "name": "byContract",
+        "properties": [
+          {
+            "dataContractId": "asc"
+          },
+          {
+            "$createdAt": "asc"
+          }
+        ],
+        "averageable": "price",
+        "rangeAverageable": true
+      }
+    ],
+    "properties": {
+      "dataContractId": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 32,
+        "maxItems": 32,
+        "description": "The data contract of the listed document",
+        "position": 0,
+        "contentMediaType": "application/x.dash.dpp.identifier"
+      },
+      "documentTypeName": {
+        "type": "string",
+        "maxLength": 64,
+        "description": "The document type of the listed document",
+        "position": 1
+      },
+      "documentId": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 32,
+        "maxItems": 32,
+        "description": "The listed document",
+        "position": 2,
+        "contentMediaType": "application/x.dash.dpp.identifier"
+      },
+      "price": {
+        "type": "integer",
+        "description": "The new asking price for the document in credits. Unbounded integer so the property is sum-aggregatable (i64); actual values are consensus-validated non-negative credit amounts written only by the protocol",
+        "position": 3
+      }
+    },
+    "required": [
+      "dataContractId",
+      "documentTypeName",
+      "documentId",
+      "price",
+      "$createdAt",
+      "$createdAtBlockHeight"
+    ],
+    "additionalProperties": false
+  }
+}

package/src/error.rs

@@ -0,0 +1,17 @@
+use platform_version::version::FeatureVersion;
+
+#[derive(thiserror::Error, Debug)]
+pub enum Error {
+    /// Platform expected some specific versions
+    #[error("platform unknown version on {method}, received: {received}")]
+    UnknownVersionMismatch {
+        /// method
+        method: String,
+        /// the allowed versions for this method
+        known_versions: Vec<FeatureVersion>,
+        /// requested core height
+        received: FeatureVersion,
+    },
+    #[error("schema deserialize error: {0}")]
+    InvalidSchemaJson(#[from] serde_json::Error),
+}

package/src/lib.rs

@@ -0,0 +1,37 @@
+mod error;
+pub mod v1;
+
+pub use crate::error::Error;
+use platform_value::{Identifier, IdentifierBytes32};
+use platform_version::version::PlatformVersion;
+use serde_json::Value;
+
+pub const ID_BYTES: [u8; 32] = [
+    88, 18, 140, 208, 179, 231, 242, 57, 225, 203, 4, 210, 245, 95, 136, 92, 160, 167, 112, 118,
+    173, 238, 83, 62, 234, 230, 222, 16, 231, 30, 99, 98,
+];
+
+pub const OWNER_ID_BYTES: [u8; 32] = [0; 32];
+
+pub const ID: Identifier = Identifier(IdentifierBytes32(ID_BYTES));
+pub const OWNER_ID: Identifier = Identifier(IdentifierBytes32(OWNER_ID_BYTES));
+pub fn load_definitions(platform_version: &PlatformVersion) -> Result<Option<Value>, Error> {
+    match platform_version.system_data_contracts.document_history {
+        1 => Ok(None),
+        version => Err(Error::UnknownVersionMismatch {
+            method: "document_history_contract::load_definitions".to_string(),
+            known_versions: vec![1],
+            received: version,
+        }),
+    }
+}
+pub fn load_documents_schemas(platform_version: &PlatformVersion) -> Result<Value, Error> {
+    match platform_version.system_data_contracts.document_history {
+        1 => v1::load_documents_schemas(),
+        version => Err(Error::UnknownVersionMismatch {
+            method: "document_history_contract::load_documents_schemas".to_string(),
+            known_versions: vec![1],
+            received: version,
+        }),
+    }
+}

package/src/v1/mod.rs

@@ -0,0 +1,45 @@
+use crate::Error;
+use serde_json::Value;
+
+pub mod document_types {
+    pub mod transfer {
+        pub const NAME: &str = "transfer";
+
+        pub mod properties {
+            pub const DATA_CONTRACT_ID: &str = "dataContractId";
+            pub const DOCUMENT_TYPE_NAME: &str = "documentTypeName";
+            pub const DOCUMENT_ID: &str = "documentId";
+            pub const TO_IDENTITY_ID: &str = "toIdentityId";
+        }
+    }
+
+    pub mod purchase {
+        pub const NAME: &str = "purchase";
+
+        pub mod properties {
+            pub const DATA_CONTRACT_ID: &str = "dataContractId";
+            pub const DOCUMENT_TYPE_NAME: &str = "documentTypeName";
+            pub const DOCUMENT_ID: &str = "documentId";
+            pub const SELLER_ID: &str = "sellerId";
+            pub const PRICE: &str = "price";
+        }
+    }
+
+    pub mod price_update {
+        pub const NAME: &str = "priceUpdate";
+
+        pub mod properties {
+            pub const DATA_CONTRACT_ID: &str = "dataContractId";
+            pub const DOCUMENT_TYPE_NAME: &str = "documentTypeName";
+            pub const DOCUMENT_ID: &str = "documentId";
+            pub const PRICE: &str = "price";
+        }
+    }
+}
+
+pub fn load_documents_schemas() -> Result<Value, Error> {
+    serde_json::from_str(include_str!(
+        "../../schema/v1/document-history-contract-documents.json"
+    ))
+    .map_err(Error::InvalidSchemaJson)
+}

package/test/bootstrap.js

@@ -0,0 +1,30 @@
+const sinon = require('sinon');
+const sinonChai = require('sinon-chai');
+
+const { expect, use } = require('chai');
+const dirtyChai = require('dirty-chai');
+
+const {
+  default: loadWasmDpp,
+} = require('@dashevo/wasm-dpp');
+
+use(dirtyChai);
+use(sinonChai);
+
+exports.mochaHooks = {
+  beforeAll: loadWasmDpp,
+
+  beforeEach() {
+    if (!this.sinon) {
+      this.sinon = sinon.createSandbox();
+    } else {
+      this.sinon.restore();
+    }
+  },
+
+  afterEach() {
+    this.sinon.restore();
+  },
+};
+
+global.expect = expect;

package/test/unit/documentHistoryContract.spec.js

@@ -0,0 +1,172 @@
+const crypto = require('crypto');
+const {
+  DashPlatformProtocol,
+  JsonSchemaError,
+} = require('@dashevo/wasm-dpp');
+const generateRandomIdentifier = require('@dashevo/wasm-dpp/lib/test/utils/generateRandomIdentifierAsync');
+const { expect } = require('chai');
+const documentHistoryContractDocumentsSchema = require('../../schema/v1/document-history-contract-documents.json');
+
+const expectJsonSchemaError = (validationResult, errorCount = 1) => {
+  const errors = validationResult.getErrors();
+  expect(errors).to.have.length(errorCount);
+
+  const error = validationResult.getErrors()[0];
+  expect(error).to.be.instanceof(JsonSchemaError);
+
+  return error;
+};
+
+describe('Document History Contract', () => {
+  let dpp;
+  let dataContract;
+  let identityId;
+
+  beforeEach(async () => {
+    dpp = new DashPlatformProtocol({ generate: () => crypto.randomBytes(32) });
+    identityId = await generateRandomIdentifier();
+    dataContract = dpp.dataContract.create(
+      identityId,
+      BigInt(1),
+      documentHistoryContractDocumentsSchema,
+    );
+  });
+
+  it('should have a valid contract definition', async () => {
+    const createContract = () => dpp.dataContract.create(
+      identityId,
+      BigInt(1),
+      documentHistoryContractDocumentsSchema,
+    );
+
+    expect(createContract).to.not.throw();
+  });
+
+  describe('documents', () => {
+    describe('transfer', () => {
+      let rawTransferDocument;
+
+      beforeEach(() => {
+        rawTransferDocument = {
+          dataContractId: crypto.randomBytes(32),
+          documentTypeName: 'domain',
+          documentId: crypto.randomBytes(32),
+          toIdentityId: crypto.randomBytes(32),
+        };
+      });
+
+      ['dataContractId', 'documentTypeName', 'documentId', 'toIdentityId'].forEach((property) => {
+        describe(property, () => {
+          it('should be defined', async () => {
+            delete rawTransferDocument[property];
+            const document = dpp.document.create(dataContract, identityId, 'transfer', rawTransferDocument);
+            const validationResult = document.validate(dpp.protocolVersion);
+            const error = expectJsonSchemaError(validationResult);
+            expect(error.keyword).to.equal('required');
+            expect(error.params.missingProperty).to.equal(property);
+          });
+        });
+      });
+
+      it('should not have additional properties', async () => {
+        rawTransferDocument.someOtherProperty = 42;
+        const document = dpp.document.create(dataContract, identityId, 'transfer', rawTransferDocument);
+        const validationResult = document.validate(dpp.protocolVersion);
+        const error = expectJsonSchemaError(validationResult);
+        expect(error.keyword).to.equal('additionalProperties');
+        expect(error.params.additionalProperties).to.deep.equal(['someOtherProperty']);
+      });
+    });
+
+    describe('purchase', () => {
+      let rawPurchaseDocument;
+
+      beforeEach(() => {
+        rawPurchaseDocument = {
+          dataContractId: crypto.randomBytes(32),
+          documentTypeName: 'domain',
+          documentId: crypto.randomBytes(32),
+          sellerId: crypto.randomBytes(32),
+          price: 100000,
+        };
+      });
+
+      ['dataContractId', 'documentTypeName', 'documentId', 'sellerId', 'price'].forEach((property) => {
+        describe(property, () => {
+          it('should be defined', async () => {
+            delete rawPurchaseDocument[property];
+            const document = dpp.document.create(dataContract, identityId, 'purchase', rawPurchaseDocument);
+            const validationResult = document.validate(dpp.protocolVersion);
+            const error = expectJsonSchemaError(validationResult);
+            expect(error.keyword).to.equal('required');
+            expect(error.params.missingProperty).to.equal(property);
+          });
+        });
+      });
+
+      describe('price', () => {
+        it('should be an integer', async () => {
+          rawPurchaseDocument.price = 'a lot';
+          const document = dpp.document.create(dataContract, identityId, 'purchase', rawPurchaseDocument);
+          const validationResult = document.validate(dpp.protocolVersion);
+          const error = expectJsonSchemaError(validationResult);
+          expect(error.keyword).to.equal('type');
+        });
+
+        // The schema deliberately has no `minimum`: the property stays an
+        // unbounded (sum-aggregatable i64) integer, and actual values are
+        // consensus-validated credit amounts written only by the protocol.
+        it('should accept negative values at the schema layer', async () => {
+          rawPurchaseDocument.price = -1;
+          const document = dpp.document.create(dataContract, identityId, 'purchase', rawPurchaseDocument);
+          const validationResult = document.validate(dpp.protocolVersion);
+          expect(validationResult.isValid()).to.be.true();
+        });
+      });
+
+      it('should not have additional properties', async () => {
+        rawPurchaseDocument.someOtherProperty = 42;
+        const document = dpp.document.create(dataContract, identityId, 'purchase', rawPurchaseDocument);
+        const validationResult = document.validate(dpp.protocolVersion);
+        const error = expectJsonSchemaError(validationResult);
+        expect(error.keyword).to.equal('additionalProperties');
+        expect(error.params.additionalProperties).to.deep.equal(['someOtherProperty']);
+      });
+    });
+
+    describe('priceUpdate', () => {
+      let rawPriceUpdateDocument;
+
+      beforeEach(() => {
+        rawPriceUpdateDocument = {
+          dataContractId: crypto.randomBytes(32),
+          documentTypeName: 'domain',
+          documentId: crypto.randomBytes(32),
+          price: 100000,
+        };
+      });
+
+      ['dataContractId', 'documentTypeName', 'documentId', 'price'].forEach((property) => {
+        describe(property, () => {
+          it('should be defined', async () => {
+            delete rawPriceUpdateDocument[property];
+            const document = dpp.document.create(dataContract, identityId, 'priceUpdate', rawPriceUpdateDocument);
+            const validationResult = document.validate(dpp.protocolVersion);
+            const error = expectJsonSchemaError(validationResult);
+            expect(error.keyword).to.equal('required');
+            expect(error.params.missingProperty).to.equal(property);
+          });
+        });
+      });
+
+      it('should not have additional properties', async () => {
+        rawPriceUpdateDocument.someOtherProperty = 42;
+        const document = dpp.document.create(dataContract, identityId, 'priceUpdate', rawPriceUpdateDocument);
+        const validationResult = document.validate(dpp.protocolVersion);
+        const error = expectJsonSchemaError(validationResult);
+        expect(error.keyword).to.equal('additionalProperties');
+        expect(error.params.additionalProperties).to.deep.equal(['someOtherProperty']);
+      });
+    });
+  });
+});