Digital Agreement Signing¶

Self provides a secure digital agreement signing workflow that allows users to cryptographically sign documents using their digital identity. This workflow ensures document integrity, non-repudiation, and tamper-proof signatures that can be verified independently. The digital signing process is designed to be scalable and can be used in a variety of scenarios, such as:

• Legal contract signing for business applications
• Terms of service acceptance for web and mobile platforms
• Document approval workflows in enterprise systems
• Regulatory compliance documentation
• Financial agreement signing
• Healthcare consent forms

How to build a digital agreement signing workflow¶

You can build a secure digital agreement signing workflow with Self using verification requests and responses. Let's break down the process into steps:

1. Server: Verification Request¶

Once we have the user's address (userAddress) and the document to be signed, we can send a verification request. This request contains the document details and signing requirements. For more details on verification requests, check out the Verification guide.

2. Client: Handle Verification Request¶

You need to listen to the verification request in the account's callback and then check the incoming message for its type and details. If the request is for document signing, display the document content to the user for review and signature.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

var verificationRequest: VerificationRequest? = null 
account.setOnRequestListener { msg ->
      when (msg) {
          is VerificationRequest -> {
              if (msg.types().contains("DocumentSigning") && msg.subject() == "document_signature") {                    
                  verificationRequest = msg

                  // Extract document content from the request
                  val documentContent = String(msg.attachment())
                  val documentHash = msg.obj()

                  // Navigate to document signing UI
                  navController.navigate("documentSigningRoute") 
              }
          }
      }
  }

  // Integrate document signing UI flow into Navigation
  addDocumentSigningRoute(navController, route = "documentSigningRoute", selfModifier = selfModifier, 
      document = { documentContent },
      onFinish = { accepted ->
          if (verificationRequest != null) {
              // Send the verification response after user decision
              sendVerificationResponse(accepted)               
          }            
      }
  )

  fun sendVerificationResponse(accepted: Boolean) {       
      val status = if (accepted) ResponseStatus.accepted else ResponseStatus.rejected

      val verificationResponse = VerificationResponse.Builder()
          .setRequestId(verificationRequest.id())
          .setTypes(verificationRequest.types())
          .setToIdentifier(verificationRequest.toIdentifier())
          .setFromIdentifier(verificationRequest.fromIdentifier())
          .setStatus(status)
          .setObject(verificationRequest.obj()) // Include document hash
          .setSubject(verificationRequest.subject())
          .build()

      account.send(verificationResponse)       
  }

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109

// 1. Handle verification request in your request listener
account.setOnRequestListener { [weak self] requestMessage in
    guard let self = self else { return }

    if let verificationRequest = requestMessage as? VerificationRequest {
        print("Verification request received from: \(verificationRequest.fromIdentifier())")

        Task { @MainActor in
            await self.handleVerificationRequest(verificationRequest)
        }
    }
}

// 2. Handle verification request with proper filtering and thread safety
private func handleVerificationRequest(_ verificationRequest: VerificationRequest) async {
    let types = verificationRequest.types()
    let subject = verificationRequest.subject()

    print("Verification request types: \(types)")
    print("Verification request subject: \(subject)")

    // Check if this is a document signing request
    if types.contains("DocumentSigning") && subject == "document_signature" {
        print("✅ Processing document signing request")
        await handleDocumentSigning(verificationRequest)
    } else {
        print("❌ Unsupported verification request type")
    }
}

// 3. Handle document signing with proper thread management
private func handleDocumentSigning(_ verificationRequest: VerificationRequest) async {
    // Extract document details
    let documentHash = verificationRequest.obj()
    let documentDescription = verificationRequest.description()

    // Extract document content if available
    var documentContent: String = ""
    if let attachment = verificationRequest.attachment() {
        documentContent = String(data: attachment, encoding: .utf8) ?? ""
    }

    print("Document to sign:")
    print("Hash: \(documentHash)")
    print("Description: \(documentDescription)")
    print("Content preview: \(String(documentContent.prefix(100)))...")

    // Store the request for later response
    currentVerificationRequest = verificationRequest

    // Navigate to document signing UI on main thread
    await MainActor.run {
        // Update UI to show document signing screen
        currentScreen = .documentSigning
    }
}

// 4. Send verification response after user makes signing decision
private func sendVerificationResponse(
    to request: VerificationRequest,
    accepted: Bool
) async {
    let status = accepted ? ResponseStatus.accepted : ResponseStatus.rejected

    do {
        let response = VerificationResponse.Builder()
            .withRequestId(request.id())
            .withTypes(request.types())
            .toIdentifier(request.toIdentifier())
            .fromIdentifier(request.fromIdentifier())
            .withStatus(status)
            .withObject(request.obj()) // Include document hash
            .withSubject(request.subject())
            .build()

        try await account.send(message: response, onAcknowledgement: { messageId, error in
            if let error = error {
                print("❌ Verification response failed: \(error)")
            } else {
                print("✅ Document signing response sent successfully")
            }
        })
    } catch {
        print("Error building verification response: \(error)")
    }
}

// 5. User interface methods for accepting/rejecting signature
private func acceptDocumentSigning() {
    guard let request = currentVerificationRequest else { return }

    Task {
        await sendVerificationResponse(to: request, accepted: true)
        await MainActor.run {
            currentScreen = .signatureResult(success: true)
        }
    }
}

private func rejectDocumentSigning() {
    guard let request = currentVerificationRequest else { return }

    Task {
        await sendVerificationResponse(to: request, accepted: false)
        await MainActor.run {
            currentScreen = .signatureResult(success: false)
        }
    }
}

See full examples

3. Server: Processing Signature Response, Document Integrity and Audit Trail¶

After receiving the verification response, we need to process the signature. This involves validating the response, checking the signature status, and storing the signed document record. For more information on verification validation, see the Verification Validation guide.

Security Considerations¶

When implementing digital agreement signing, consider these important security aspects:

Document Integrity¶

• Always use cryptographic hashes (SHA-256 or stronger) to ensure document integrity
• Store the original document hash with the signature record
• Verify document hash before displaying to users

Non-Repudiation¶

• Each signature is cryptographically linked to the signer's Self identity
• Signature records include timestamps and metadata for audit trails
• Digital signatures cannot be forged or denied by the signer

Legal Validity¶

• Self's digital signatures meet legal standards for electronic signatures in many jurisdictions
• Maintain comprehensive audit logs for compliance requirements
• Consider jurisdiction-specific requirements for digital signature validity

Best Practices¶

• Implement signature expiration policies based on your use case
• Store signature records in immutable audit logs
• Provide clear consent mechanisms for users
• Include document version control in your signing workflow

Conclusion¶

This example demonstrates how to build a comprehensive digital agreement signing workflow with Self. We've seen how to send verification requests for document signing, handle the signing process on mobile clients, validate signature responses, and maintain audit trails for compliance.

The Self SDK provides a secure, legally-compliant foundation for digital document signing that ensures: - Identity verification: Signers are authenticated using their Self digital identity - Document integrity: Cryptographic hashes prevent document tampering - Non-repudiation: Signatures cannot be denied or forged - Audit compliance: Comprehensive logging for regulatory requirements

💻 Complete Working Examples¶

For complete, runnable implementations that you can test immediately, explore our official examples repository:

🚀 Self SDK Examples Repository¶

Quick Start:

1
2

# Clone with all submodules
git clone --recurse-submodules https://github.com/joinself/self-sdk-examples.git

Platform-Specific Examples: - Android: android/SelfExamples/verification/ - Complete verification and document signing flow - iOS: ios/Example/ - Native iOS verification response implementation - Golang: golang/examples/ - Server-side verification request handling - Java: java/ - Enterprise server implementations

Key Features Demonstrated: - Document Hashing: Cryptographic document integrity verification - Signature Workflows: Complete request/response patterns for document signing - Audit Trails: Comprehensive logging and signature record management - Legal Compliance: Best practices for electronic signature validity

By leveraging these Self features, you can create a robust, secure, and legally-compliant digital signing system that streamlines agreement processes while maintaining the highest security standards.