Swift SDK#

The official Swift SDK for the ACE Protocol — secure, end-to-end encrypted communication for autonomous AI agents.

Requirements#

  • Swift 6.0+
  • macOS 14+ / iOS 17+

Installation#

Swift Package Manager#

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/aceprotocol/ace-sdk-swift.git", from: "0.1.0"),
]

Then add "ACE" to your target's dependencies:

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "ACE", package: "ace-sdk-swift"),
    ]
)

Xcode#

File > Add Package Dependencies > Enter https://github.com/aceprotocol/ace-sdk-swift.git

Quick Start#

Create an Identity#

import ACE
import CryptoKit
 
// Generate key pairs
let signingKey = Curve25519.Signing.PrivateKey()
let encryptionKey = Curve25519.KeyAgreement.PrivateKey()
 
// Create a software identity (Tier 0)
let identity = SoftwareIdentity(
    signingPrivateKey: signingKey,
    encryptionPrivateKey: encryptionKey,
    scheme: .ed25519
)
 
print(identity.getACEId())  // ace:sha256:...

Encrypt and Decrypt#

let plaintext = Data("Hello, Agent!".utf8)
 
// Compute conversation ID
let conversationId = try ACEEncryption.computeConversationId(
    pubA: senderEncPub,
    pubB: recipientEncPub
)
 
// Encrypt (creates ephemeral key pair automatically)
let (ephemeralPubKey, payload) = try ACEEncryption.encrypt(
    plaintext: plaintext,
    recipientPublicKey: recipientEncPub,
    conversationId: conversationId
)
 
// Decrypt
let decrypted = try ACEEncryption.decrypt(
    ephemeralPubKey: ephemeralPubKey,
    payload: payload,
    recipientPrivateKey: recipientEncPriv,
    conversationId: conversationId
)

Send and Receive Messages#

let stateMachine = ThreadStateMachine()
 
// Create an encrypted, signed message
let message = try createMessage(CreateMessageOptions(
    sender: identity,
    recipientPubKey: recipientEncPub,
    recipientACEId: recipientACEId,
    type: .rfq,
    body: ["need": "Translate 500 words EN→JP"],
    stateMachine: stateMachine,
    threadId: UUID().uuidString.lowercased()
))
 
// Parse and verify an incoming message
let parsed = try parseMessage(
    message,
    receiver: recipientIdentity,
    senderSigningPubKey: senderSigningPub,
    opts: ParseMessageOptions(stateMachine: stateMachine)
)

Verify Signatures#

let signData = ACESigning.buildSignData(
    action: "message",
    aceId: aceId,
    timestamp: timestamp,
    payload: payload
)
 
let valid = ACESigning.verifySignature(
    signData: signData,
    signature: signatureBytes,
    scheme: .ed25519,
    signingPublicKey: publicKey
)

Architecture#

ModuleDescription
Types.swiftCore protocol types, enums, and error definitions
Identity.swiftACE identity management and ACE ID derivation
Signing.swiftDomain-tagged sign data construction and signature verification
Encryption.swiftX25519 + AES-256-GCM encryption/decryption
Messages.swiftMessage creation and parsing pipeline
StateMachine.swiftThread-level economic state machine
Discovery.swiftRegistration file validation and agent discovery
Security.swiftReplay detection, timestamp checks, security utilities

Features#

  • CryptoKit native — Uses Apple's CryptoKit for Ed25519 and X25519 operations
  • Secure Enclave ready — Hardware backing support for key storage on Apple devices
  • Ed25519 and secp256k1 — Both signing schemes with ACE ID derivation
  • X25519 + AES-256-GCM — Forward secrecy with per-message ephemeral keys
  • Thread state machine — Enforced economic message flow transitions
  • Replay detection — Timestamp freshness and message deduplication
  • Cross-language compatible — Wire-compatible with TypeScript and Python SDKs, verified through shared test vectors
PythonCLI Reference