@smartledger/bsv 3.2.2 → 3.3.3

package/docs/technical/trust_law.md

@@ -0,0 +1,142 @@
+Excellent. Below is the **Trust Protocol Mapping Document (Draft v1.0)** — a comprehensive bridge between *traditional common-law trust principles* (as represented in Weiss’s Concise Trustee Handbook and similar express-trust doctrines) and *SmartLedger’s modern digital legal architecture* (SmartLedger-BSV + LTP + GDAF + NotaryHash).
+
+---
+
+# 🧾 **Trust Protocol Mapping Document (v1.0)**
+
+### *Bridging Express Trust Law and the Legal Token Protocol (LTP)*
+
+---
+
+## ⚖️ 1. Core Legal–Digital Mapping
+
+| **Traditional Trust Element** | **Description (Common Law)**                                             | **Digital Representation (SmartLedger Framework)**                         | **Implemented In**                 |
+| ----------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ---------------------------------- |
+| **Settlor (Grantor)**         | Creator of the trust; provides property or rights to be held in trust.   | DID representing issuing authority (may be individual, corporation, DAO).  | `identity/` → `createDID()`        |
+| **Trustee(s)**                | Hold and manage property for benefit of beneficiary; owe fiduciary duty. | DID(s) with VC attestation of role and fiduciary obligations.              | `identity/`, `legal/ltp/`, `gdaf/` |
+| **Beneficiary(ies)**          | The party entitled to benefit from the trust corpus.                     | Subject DID(s) listed in claim or rights object.                           | `legal/ltp/`                       |
+| **Corpus (Res)**              | Property, asset, or rights being held.                                   | Tokenized “claim” object within Legal Token Protocol.                      | `ltp/`                             |
+| **Trust Instrument**          | Written or oral declaration establishing trust terms.                    | JSON-LD trust schema anchored via NotaryHash; cryptographically signed.    | `anchor/`, `gdaf/`                 |
+| **Purpose Clause**            | Lawful reason for trust (charitable, private, etc.).                     | `purpose` field in token schema (ISO 3166 jurisdictional & legal tags).    | `ltp/schema`                       |
+| **Jurisdiction (Situs)**      | Governing law and forum.                                                 | `jurisdiction` field in credential metadata (ISO country + legal system).  | `compliance/`                      |
+| **Trust Certificate**         | Document showing beneficial ownership or capital interest.               | Token credential (VC or NFT-style right token) anchored on-chain.          | `ltp/`, `gdaf/`                    |
+| **Minutes / Accounting**      | Trustee logs of actions, decisions, disbursements.                       | Verifiable “ActionLogCredential” anchored on-chain (audit trail).          | `anchor/`, `gdaf/`                 |
+| **Trustee Resolution**        | Decision or vote by trustees.                                            | Multi-sig or VC “ResolutionCredential” anchored + signed by quorum.        | `ltp/`, `identity/`                |
+| **Revocation / Termination**  | Ending or amending trust instrument.                                     | `revokeRightToken(tokenId)` + updated anchor proof in revocation registry. | `ltp/`                             |
+| **Liability & Indemnity**     | Limits trustee liability or defines indemnification.                     | Schema fields `trusteeIndemnity`, `liabilityLimit`, hashed in corpus.      | `ltp/schema`                       |
+| **Audit & Oversight**         | External or internal verification of compliance.                         | Chain-based audit credential + GDAF selective proof verification.          | `gdaf/`, `anchor/`                 |
+
+---
+
+## 🧱 2. Protocol Flow Example: Creation → Management → Termination
+
+1. **Declaration Phase**
+
+   ```js
+   const settlorDid = SmartLedgerBSV.GDAF.createDID(pubKey);
+   const trusteeDid = SmartLedgerBSV.GDAF.createDID(trusteeKey);
+   const trustSchema = SmartLedgerBSV.LTP.createRightToken(
+       'PrivateExpressTrust',
+       trusteeDid,
+       { corpus: 'DigitalAssetXYZ', purpose: 'Beneficiary Support', jurisdiction: 'US-VA' },
+       settlorKey
+   );
+   const txid = SmartLedgerBSV.Anchor.commitHash(trustSchema.rootHash, { purpose: 'trust-declaration' });
+   ```
+
+2. **Operation Phase**
+
+   * Trustees issue VC “TrusteeActionCredential” for each action (investment, distribution, amendment).
+   * Anchors created via NotaryHash.
+   * Beneficiaries view proofs using ZK disclosure of entitlement without revealing full corpus.
+
+3. **Termination Phase**
+
+   ```js
+   SmartLedgerBSV.LTP.revokeRightToken(trustSchema.id);
+   SmartLedgerBSV.Anchor.commitHash(revocationHash, { purpose: 'trust-termination' });
+   ```
+
+---
+
+## 🧩 3. Compliance & Legal Framework Overlay
+
+| **Principle**      | **SmartLedger Implementation**                                   | **Effect**                                   |
+| ------------------ | ---------------------------------------------------------------- | -------------------------------------------- |
+| *Lawful purpose*   | Schema validation forbids unlawful or undefined `purpose` field. | Ensures digital trusts are legally valid.    |
+| *Fiduciary duty*   | VC attestation + signature requirement for trustee actions.      | Enforceable accountability.                  |
+| *Privacy duty*     | HMAC/commitment model, zero-knowledge field proofs.              | GDPR & fiduciary confidentiality compliance. |
+| *Accounting duty*  | Immutable audit logs via anchor proofs.                          | Transparent stewardship.                     |
+| *Right to redress* | Dispute resolution VC + signature chain.                         | Legal recourse framework.                    |
+
+---
+
+## 🔐 4. Schema Alignment
+
+### TrustCredential (example)
+
+```json
+{
+  "@context": ["https://www.w3.org/2018/credentials/v1", "https://smartledger.org/ltp/trust/v1"],
+  "type": ["VerifiableCredential", "TrustCredential"],
+  "issuer": "did:smartledger:abcd1234",
+  "issuanceDate": "2025-10-22T00:00:00Z",
+  "credentialSubject": {
+    "trustName": "Ward Family Private Express Trust",
+    "settlor": "did:smartledger:settlor123",
+    "trustee": ["did:smartledger:trustee456"],
+    "beneficiary": ["did:smartledger:beneficiary789"],
+    "corpus": { "assetType": "DigitalProperty", "assetId": "hash:abcd" },
+    "purpose": "Estate Preservation",
+    "jurisdiction": "US-VA"
+  },
+  "proof": {
+    "type": "SmartLedgerSignature2025",
+    "created": "2025-10-22T00:00:00Z",
+    "proofPurpose": "assertionMethod",
+    "verificationMethod": "did:smartledger:abcd1234#keys-1",
+    "jws": "eyJhbGciOiJFUzI1NiIsInR5cCI6..."
+  }
+}
+```
+
+---
+
+## 🧩 5. Inter-Protocol Integration
+
+| **Component**                    | **Purpose**                                             | **Trust-Mapping Equivalent**                                    |
+| -------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------- |
+| **SmartLedger-BSV Crypto Layer** | Provides signature, Shamir recovery, canonical hashing. | Legal “seal” of trustee instrument.                             |
+| **GDAF (Identity)**              | Defines DID, VC issuance, selective proof.              | Identifies Settlor/Trustee/Beneficiary with attested authority. |
+| **LTP (Legal Tokens)**           | Encodes property, licenses, rights.                     | Defines trust corpus & certificates.                            |
+| **NotaryHash**                   | Anchors proofs on-chain.                                | Ledgered minutes, immutable recordkeeping.                      |
+| **Compliance Module**            | Applies GDPR/eIDAS/KYC filters.                         | Ensures lawful privacy & admissibility.                         |
+
+---
+
+## 🌐 6. Future Extensions
+
+| **Goal**                                    | **Description**                                                      |
+| ------------------------------------------- | -------------------------------------------------------------------- |
+| **Multi-jurisdiction Templates**            | Schema variants for US Common Law, UK Equity, EU Civil Trusts.       |
+| **Trustee Dashboard SDK**                   | UI toolkit to manage credentials, actions, audit logs.               |
+| **AI Compliance Auditor**                   | GDAF-linked AI validator for fiduciary & jurisdictional consistency. |
+| **Integration with National ID frameworks** | Optional verification with eIDAS/eID.                                |
+
+---
+
+## 🧭 7. Conclusion
+
+By aligning SmartLedger’s LTP & GDAF architecture with express trust law, the system transforms **trusts, contracts, and fiduciary duties** into **digitally verifiable legal primitives**.
+
+Every trustee signature, declaration, and action can now be:
+✅ Proven on-chain
+✅ Audited under jurisdiction
+✅ Recovered by lawful heirs
+✅ Compliant with privacy & fiduciary standards
+
+This makes SmartLedger’s infrastructure the **world’s first “Trust-as-Code” framework** — where **Law, Ledger, and Logic** converge.
+
+---
+
+Would you like me to extend this into a **formal Trust Protocol Specification (TPS 1.0)** — with detailed JSON schemas, method signatures, and governance model (Trust Registrar, Revocation Registry, Jurisdiction Tags, etc.) so your LTP developers can begin implementation directly?

package/gdaf-entry.js

@@ -0,0 +1,2 @@
+// GDAF module placeholder - will be implemented in future release
+module.exports = require('./lib/smart_contract');

package/index.js

@@ -48,6 +48,7 @@ bsv.crypto.Hash = require('./lib/crypto/hash')
 bsv.crypto.Random = require('./lib/crypto/random')
 bsv.crypto.Point = require('./lib/crypto/point')
 bsv.crypto.Signature = require('./lib/crypto/signature')
+bsv.crypto.Shamir = require('./lib/crypto/shamir')
 
 // SmartLedger security enhancements
 bsv.crypto.SmartVerify = require('./lib/crypto/smartledger_verify')
@@ -82,8 +83,14 @@ bsv.PrivateKey = require('./lib/privatekey')
 bsv.PublicKey = require('./lib/publickey')
 bsv.Script = require('./lib/script')
 bsv.Transaction = require('./lib/transaction')
+bsv.Input = require('./lib/transaction').Input
+bsv.Output = require('./lib/transaction').Output
+bsv.UnspentOutput = require('./lib/transaction').UnspentOutput
 bsv.Message = require('./lib/message')
+bsv.Mnemonic = require('./lib/mnemonic')
+bsv.ECIES = require('./lib/ecies')
 bsv.Signature = require('./lib/crypto/signature')
+bsv.Shamir = require('./lib/crypto/shamir')
 
 // SmartLedger security modules (top-level access)
 bsv.SmartLedger = {
@@ -119,5 +126,289 @@ if (typeof window === 'undefined' && typeof require === 'function') {
   }
 }
 
+// Global Digital Attestation Framework (GDAF)
+bsv.GDAF = require('./lib/gdaf')
+
+// GDAF Direct Access Methods (for easier developer experience)
+bsv.createDID = function(publicKey) {
+  var gdaf = new bsv.GDAF()
+  return gdaf.createDID(publicKey)
+}
+
+bsv.resolveDID = function(did) {
+  var gdaf = new bsv.GDAF()
+  return gdaf.resolveDID(did)
+}
+
+bsv.createEmailCredential = function(issuerDID, subjectDID, email, issuerPrivateKey) {
+  var gdaf = new bsv.GDAF()
+  return gdaf.createEmailCredential(issuerDID, subjectDID, email, issuerPrivateKey)
+}
+
+bsv.createAgeCredential = function(issuerDID, subjectDID, ageThreshold, birthDate, issuerPrivateKey) {
+  var gdaf = new bsv.GDAF()
+  return gdaf.createAgeCredential(issuerDID, subjectDID, ageThreshold, birthDate, issuerPrivateKey)
+}
+
+bsv.createKYCCredential = function(issuerDID, subjectDID, level, piiHashes, issuerPrivateKey) {
+  var gdaf = new bsv.GDAF()
+  return gdaf.createKYCCredential(issuerDID, subjectDID, level, piiHashes, issuerPrivateKey)
+}
+
+bsv.verifyCredential = function(credential, options) {
+  var gdaf = new bsv.GDAF()
+  return gdaf.verifyCredential(credential, options)
+}
+
+bsv.validateCredential = function(credential, schema) {
+  var gdaf = new bsv.GDAF()
+  return gdaf.validateCredential(credential, schema)
+}
+
+bsv.generateSelectiveProof = function(credential, revealedFields, nonce) {
+  var gdaf = new bsv.GDAF()
+  return gdaf.generateSelectiveProof(credential, revealedFields, nonce)
+}
+
+bsv.generateAgeProof = function(ageCredential, minimumAge, nonce) {
+  var gdaf = new bsv.GDAF()
+  return gdaf.generateAgeProof(ageCredential, minimumAge, nonce)
+}
+
+bsv.verifyAgeProof = function(proof, minimumAge, issuerDID) {
+  var gdaf = new bsv.GDAF()
+  return gdaf.verifyAgeProof(proof, minimumAge, issuerDID)
+}
+
+bsv.createPresentation = function(credentials, holderDID, holderPrivateKey, options) {
+  var gdaf = new bsv.GDAF()
+  return gdaf.createPresentation(credentials, holderDID, holderPrivateKey, options)
+}
+
+bsv.getCredentialSchemas = function() {
+  var gdaf = new bsv.GDAF()
+  return gdaf.getAllSchemas()
+}
+
+bsv.createCredentialTemplate = function(credentialType) {
+  var gdaf = new bsv.GDAF()
+  return gdaf.createTemplate(credentialType)
+}
+
+// Legal Token Protocol (LTP) - Primitives-Only Interface
+bsv.LTP = require('./lib/ltp')
+
+// LTP Right Token Primitives
+bsv.prepareRightToken = function(type, issuerDID, subjectDID, claim, issuerPrivateKey, options) {
+  return bsv.LTP.Right.prepareRightToken(type, issuerDID, subjectDID, claim, issuerPrivateKey, options)
+}
+
+bsv.prepareRightTokenVerification = function(token, options) {
+  return bsv.LTP.Right.prepareRightTokenVerification(token, options)
+}
+
+bsv.prepareRightTokenTransfer = function(token, newOwnerDID, currentOwnerKey, options) {
+  return bsv.LTP.Right.prepareRightTokenTransfer(token, newOwnerDID, currentOwnerKey, options)
+}
+
+bsv.prepareRightTypeValidation = function(type) {
+  return bsv.LTP.Right.prepareRightTypeValidation(type)
+}
+
+// LTP Obligation Token Primitives
+bsv.prepareObligationToken = function(type, issuerDID, obligorDID, obligation, issuerPrivateKey, options) {
+  return bsv.LTP.Obligation.prepareObligationToken(type, issuerDID, obligorDID, obligation, issuerPrivateKey, options)
+}
+
+bsv.prepareObligationVerification = function(token, options) {
+  return bsv.LTP.Obligation.prepareObligationVerification(token, options)
+}
+
+bsv.prepareObligationFulfillment = function(token, fulfillment, obligorKey, options) {
+  return bsv.LTP.Obligation.prepareObligationFulfillment(token, fulfillment, obligorKey, options)
+}
+
+bsv.prepareObligationBreachAssessment = function(token, breach, assessor) {
+  return bsv.LTP.Obligation.prepareObligationBreachAssessment(token, breach, assessor)
+}
+
+bsv.prepareObligationMonitoringReport = function(obligations, criteria) {
+  return bsv.LTP.Obligation.prepareObligationMonitoringReport(obligations, criteria)
+}
+
+// LTP Claim Validation Primitives
+bsv.prepareClaimValidation = function(claim, schemaName) {
+  return bsv.LTP.Claim.prepareClaimValidation(claim, schemaName)
+}
+
+bsv.prepareClaimAttestation = function(claim, schemaName, attestor) {
+  return bsv.LTP.Claim.prepareClaimAttestation(claim, schemaName, attestor)
+}
+
+bsv.prepareClaimDispute = function(claimHash, disputant, dispute) {
+  return bsv.LTP.Claim.prepareClaimDispute(claimHash, disputant, dispute)
+}
+
+bsv.prepareBulkClaimValidation = function(claims, schemaName) {
+  return bsv.LTP.Claim.prepareBulkClaimValidation(claims, schemaName)
+}
+
+bsv.prepareClaimTemplate = function(schemaName, options) {
+  return bsv.LTP.Claim.prepareClaimTemplate(schemaName, options)
+}
+
+// LTP Proof Generation Primitives
+bsv.prepareSignatureProof = function(token, privateKey, options) {
+  return bsv.LTP.Proof.prepareSignatureProof(token, privateKey, options)
+}
+
+bsv.prepareSignatureVerification = function(token, publicKey) {
+  return bsv.LTP.Proof.prepareSignatureVerification(token, publicKey)
+}
+
+bsv.prepareSelectiveDisclosure = function(token, revealedFields, nonce) {
+  return bsv.LTP.Proof.prepareSelectiveDisclosure(token, revealedFields, nonce)
+}
+
+bsv.prepareSelectiveDisclosureVerification = function(proof, expectedNonce) {
+  return bsv.LTP.Proof.prepareSelectiveDisclosureVerification(proof, expectedNonce)
+}
+
+bsv.prepareLegalValidityProof = function(token, jurisdiction, nonce) {
+  return bsv.LTP.Proof.prepareLegalValidityProof(token, jurisdiction, nonce)
+}
+
+bsv.prepareZeroKnowledgeProof = function(token, statement, nonce) {
+  return bsv.LTP.Proof.prepareZeroKnowledgeProof(token, statement, nonce)
+}
+
+// LTP Registry Management Primitives
+bsv.prepareRegistry = function(config) {
+  return bsv.LTP.Registry.prepareRegistry(config)
+}
+
+bsv.prepareTokenRegistration = function(token, registryConfig, options) {
+  return bsv.LTP.Registry.prepareTokenRegistration(token, registryConfig, options)
+}
+
+bsv.prepareTokenApproval = function(tokenId, approver, registryConfig) {
+  return bsv.LTP.Registry.prepareTokenApproval(tokenId, approver, registryConfig)
+}
+
+bsv.prepareTokenRevocation = function(tokenId, revocation, registryConfig) {
+  return bsv.LTP.Registry.prepareTokenRevocation(tokenId, revocation, registryConfig)
+}
+
+bsv.prepareTokenStatusQuery = function(tokenId, registryConfig) {
+  return bsv.LTP.Registry.prepareTokenStatusQuery(tokenId, registryConfig)
+}
+
+bsv.prepareTokenSearch = function(criteria, registryConfig) {
+  return bsv.LTP.Registry.prepareTokenSearch(criteria, registryConfig)
+}
+
+bsv.prepareStatisticsQuery = function(registryConfig) {
+  return bsv.LTP.Registry.prepareStatisticsQuery(registryConfig)
+}
+
+bsv.prepareAuditLogQuery = function(registryConfig, options) {
+  return bsv.LTP.Registry.prepareAuditLogQuery(registryConfig, options)
+}
+
+// LTP Blockchain Anchoring Primitives
+bsv.prepareTokenCommitment = function(token, options) {
+  return bsv.LTP.Anchor.prepareTokenCommitment(token, options)
+}
+
+bsv.prepareBatchCommitment = function(tokens, options) {
+  return bsv.LTP.Anchor.prepareBatchCommitment(tokens, options)
+}
+
+bsv.verifyTokenAnchor = function(token, txid, txData) {
+  return bsv.LTP.Anchor.verifyTokenAnchor(token, txid, txData)
+}
+
+bsv.formatRevocation = function(tokenId, revocationData) {
+  return bsv.LTP.Anchor.formatRevocation(tokenId, revocationData)
+}
+
+// Backward Compatibility: Direct LTP Functions (Wrapper Layer)
+// These functions provide the old-style direct API that demos expect
+
+bsv.createRightToken = function(rightData, privateKey, options) {
+  var ltp = new bsv.LTP()
+  return ltp.createRightToken(rightData, privateKey, options)
+}
+
+bsv.verifyLegalToken = function(token, publicKey) {
+  var ltp = new bsv.LTP()
+  return ltp.verifyToken(token, publicKey)
+}
+
+bsv.validateLegalClaim = function(claimData, schemaType) {
+  var ltp = new bsv.LTP()
+  return ltp.validateClaim(claimData, schemaType)
+}
+
+bsv.createSelectiveDisclosure = function(token, revealedFields, nonce) {
+  var ltp = new bsv.LTP()
+  return ltp.createSelectiveDisclosure(token, revealedFields, nonce)
+}
+
+bsv.createLegalRegistry = function(config) {
+  return bsv.LTP.Registry.prepareRegistry(config)
+}
+
+bsv.createLegalValidityProof = function(token, jurisdiction, nonce) {
+  var ltp = new bsv.LTP()
+  return ltp.createLegalValidityProof(token, jurisdiction, nonce)
+}
+
+// LTP Static Data Access (unchanged)
+bsv.getRightTypes = function() {
+  return bsv.LTP.Right.getRightTypes()
+}
+
+bsv.getObligationTypes = function() {
+  return bsv.LTP.Obligation.getObligationTypes()
+}
+
+bsv.getObligationPriority = function() {
+  return bsv.LTP.Obligation.getObligationPriority()
+}
+
+bsv.getObligationStatus = function() {
+  return bsv.LTP.Obligation.getObligationStatus()
+}
+
+bsv.getClaimSchemas = function() {
+  return bsv.LTP.Claim.getSchemas()
+}
+
+bsv.getClaimSchemaNames = function() {
+  return bsv.LTP.Claim.getSchemaNames()
+}
+
+bsv.getClaimSchema = function(schemaName) {
+  return bsv.LTP.Claim.getSchema(schemaName)
+}
+
+bsv.createClaimTemplate = function(schemaName) {
+  return bsv.LTP.Claim.createTemplate(schemaName)
+}
+
+// LTP Utility Functions
+bsv.canonicalizeClaim = function(claim) {
+  return bsv.LTP.Claim.canonicalize(claim)
+}
+
+bsv.hashClaim = function(claim) {
+  return bsv.LTP.Claim.hash(claim)
+}
+
+bsv.addCustomClaimSchema = function(name, schema) {
+  return bsv.LTP.Claim.addSchema(name, schema)
+}
+
 // Internal usage, exposed for testing/advanced tweaking
 bsv.Transaction.sighash = require('./lib/transaction/sighash')