Last updated: 2025-01-21 01:10:36.955195 File source: link on GitLab

Register an AI Agent

Actors

• Primary Actor: User

• Supporting Actors:

  • AI Agent Registry Service

  • DID Resolver

Goal in Context:

The user wants to register an AI agent (e.g., a bot or model) on a decentralized platform, securely linking it to their DID.

Preconditions:

• The user has a DID and wallet.

• The AI Agent Registry Service supports DID Auth.

Trigger:

The user requests to register a new AI agent.

Main Success Scenario:

1. Registration request:

   • The user sends a request to the AI Agent Registry Service, including metadata about the agent (e.g., public key, capabilities).

2. Authenticate user:

   • The Registry Service generates a cryptographic challenge and sends it to the user’s wallet.

   • The user signs the challenge with their DID private key and sends the signature back.

   • The Registry Service verifies the signature using the user’s DID Document.

3. Register agent:

   • The agent is registered with a new DID, linked to the user’s DID.

   • The agent’s metadata and public key are stored in the registry.

4. Confirm registration:

   • The Registry Service confirms the successful registration to the user.

Extensions:

1. Authentication failure:

   • If the user’s authentication fails, the Registry Service rejects the registration request.

2. Duplicate registration:

   • If an agent with the same metadata already exists, the service notifies the user and asks for confirmation to overwrite.

Functional Requirements

To be rewritten in Gherkin features as use-case specific regression tests and integrated into test-suite.

1. Register an AI Agent: As a user, I want to register an AI agent securely using my DID so that the agent can interact with decentralized services on my behalf.

   1. The AI Agent Registry Service must authenticate the user using DID Auth before registering the agent.

   2. The user must provide metadata (e.g., agent capabilities, public key) during registration.

   3. The system must link the agent’s DID to the user’s DID and store the metadata securely.

   4. The user must receive a confirmation message once the agent is registered.

2. Authenticate AI Agent: As a service provider, I want to authenticate an AI agent using its DID so that I can verify its identity before interaction.

   1. The AI Agent Registry Service must verify the agent’s DID ownership during authentication.

   2. The agent must sign a cryptographic challenge using its private key.

   3. The system must verify the signature using the agent’s DID Document before allowing interaction.

   4. If authentication fails, the system must deny access and notify the service.

3. Update Agent Metadata: As a user, I want to update the metadata of my AI agent so that I can modify its capabilities or public key.

   1. The AI Agent Registry Service must authenticate the user using DID Auth before processing the update request.

   2. The system must verify that the user owns the agent being updated.

   3. Updated metadata must be stored securely and linked to the agent’s DID.

   4. The user must receive a confirmation message once the update is complete.

4. Deactive AI Agent: As a user, I want to deactivate my AI agent so that it can no longer interact with decentralized services.

   1. The AI Agent Registry Service must authenticate the user using DID Auth before processing the deactivation request.

   2. The system must verify the user’s ownership of the agent and mark it as inactive.

   3. The system must archive the agent’s metadata securely.

   4. The user must receive a confirmation message once the agent is deactivated.

Last updated: 2025-01-21 01:10:35.050143 File source: link on GitLab

TBD

Last updated: 2025-01-21 01:10:37.492022 File source: link on GitLab

Submit a Compute Job

• Submit a Compute Job

  • Actors

  • Goal in Context:

  • Preconditions:

  • Trigger:

  • Main success scenario

  • Functional Requirements

  • Diagrams

Actors

• Primary Actor: AI Developer

• Supporting Actors:

  • Compute Provider

  • Service Provider

  • Result Storage Service

Goal in Context:

The user wants to submit a compute job to a decentralized compute platform, using DID Auth for secure authentication.

Preconditions:

• The user has a DID and wallet for signing challenges.

• The Compute Service and Service Providers are operational.

Trigger:

The user submits a compute job request.

Main success scenario

The main success scenario for this use case is described in nunet/device-management-service/dms/jobs package documentation as general nunet platform functionality (see the package documentation). The use-case is straightforward extension of the device-management-service functionality. We shall adapt this scenario to correspond to platform functionality and expose it to external users based on provided functional requirements and scenario from external user perspective.

Originally described scenario follows:

User submits job: The user sends a job request to the Compute Service, including their DID and job details.

1. Authenticate user:

2. The Compute Service generates a cryptographic challenge and sends it to the user.

3. The user signs the challenge with their DID private key and sends the signature back.

4. The Compute Service verifies the signature using the DID Document.

1. Allocate resources:

2. The Task Scheduler allocates resources for the job and tags it with the user’s DID for authorization.

3. Execute job: The compute job is executed on the allocated resources.

4. Store results: The Result Storage Service stores the output of the compute job, linked to the user’s DID.

1. Notify user:

2. The user is notified that the job has completed, with a link to the results.

Functional Requirements

To be rewritten in Gherkin features as use-case specific regression tests and integrated into test-suite. As noted above, most of these functionalities are implemented as general device-management-service functionality.

1. Submit a Compute Job: As a user, I want to submit a compute job securely using my DID so that I can process my data on the decentralized platform.

   1. The Compute Service must authenticate the user using DID Auth before accepting the job request.

   2. The Task Scheduler must allocate resources for the job and tag it with the user’s DID.

   3. The system must store job details and associate outputs with the user’s DID.

   4. The user must be notified when the job starts and when it is completed.

2. Retrieve Compute Results: As a user, I want to retrieve the results of my compute job securely so that I can access the output linked to my DID.

   1. The Result Storage Service must verify the user’s DID ownership before granting access to the job results.

   2. If authentication fails, access to the results must be denied.

   3. The user must receive a notification with a link to the results once they are authenticated.

3. Cancel Compute Job: As a user, I want to cancel a running compute job securely so that I can stop unnecessary resource usage.

   1. The Compute Service must verify the user’s DID ownership of the job before processing the cancellation request.

   2. The Task Scheduler must terminate the job and release resources upon successful authentication.

   3. The user must receive a confirmation message once the job is canceled.

4. Insufficient resources:

   1. If resources are unavailable, the Service Provider / Orchestrator queues the job or notifies the user of a delay.

Diagrams

Note: most probably we need to get rid of internal actors (orchestrator, allocation, etc), as these are not relevant from use-case perspective.

Last updated: 2025-01-21 01:10:35.602290 File source:

ASI node design / DID:Auth use-cases

Intro

We are working toward four use-cases identified for pursuing pilots and then design of ASI node authentication layer, for which we aim to use NuActor system and OCaps system featuring . Each use case is described and will be implemented / piloted in a separate sub-folder. For fostering collaboration between ASI node design component owners, we will do it via git development flow as per .

• The original google sheet which is the source of these descriptions can be found .

• Each use case description consists of scenario description, functional requirements and sequence diagrams;

• All auth use-cases and pilots must consider non-functional requirements that pertain to all auth layer functionality that we aim to propose/develop via pilots of these use-cases; non-functional requirements follow.

Non Functional requirements

These requirements shall be built into the test-suite of the api-node integration for running as regression test stage within the scope of NuNet's .

Performance

1. Optimize Response Time for API Services. As a user of the API, I want the system to respond quickly to my requests so that I experience minimal delays when performing operations (e.g., authentication, hosting deployment, compute job submission).

   1. API response time for authentication and resource requests must be less than 200? milliseconds for 95% of requests under normal load.

   2. Compute job submissions must not exceed 500? milliseconds, even under peak loads.

   3. Latency for DID Document resolution must not exceed 150? milliseconds.

2. Ensure High Throughput for API Requests: As a system admin, I want the API to handle a large number of concurrent requests so that it can support multiple users simultaneously without performance degradation.

   1. The API must support 1,000? concurrent authentication requests per second under normal conditions.

   2. The system must process at least 500? compute job submissions per second during peak usage.

   3. Hosting Service must handle 200? concurrent file uploads without significant performance degradation.

3. Deliver Notifications in Near Real-Time: As a user, I want to receive notifications for long-running operations (e.g., compute jobs, hosting updates) quickly so that I’m updated about the status of my tasks.

   1. Notifications for job completions must be delivered within 2 seconds of completion.

   2. Error notifications for failed operations must be sent to the user within 1 second of the failure.

Security

1. Enforce DID Auth for API requests: As a user, I want the API to enforce DID Auth for all operations so that unauthorized users cannot access my resources.

   1. Every API call must involve a cryptographic challenge-response mechanism using DID Auth.

   2. Only requests signed with a valid private key corresponding to the DID’s public key must be processed.

   3. Requests without valid DID Documents or signatures must be rejected with an HTTP 401 Unauthorized error.

2. Encrypt all communications: As a system admin, I want all data exchanged with the API to be encrypted so that sensitive information is protected from unauthorized access.

   1. All communications between clients and the API must use TLS 1.3 or higher.

   2. Sensitive data such as compute job details, payment transactions, and hosted files must be encrypted at rest using AES-256 encryption.

   3. The system must reject requests that are not made over HTTPS.

3. Implement RBAC: As a developer, I want RBAC implemented in the API so that users can only access resources they are authorized for.

   1. Users must only have access to resources associated with their DID.

   2. Admin roles must have elevated permissions to access system-level resources (e.g., logs, usage metrics).

   3. Unauthorized access attempts must return an HTTP 403 Forbidden error.

4. Prevent reply attacks: As a user, I want the API to ensure that cryptographic challenges cannot be reused so that my identity is protected from replay attacks.

   1. All cryptographic challenges must include a unique nonce or timestamp.

   2. The API must reject requests with expired or duplicate challenges and respond with an HTTP 401 Unauthorized error.

   3. Challenges must expire after 5 minutes from the time of issuance.

Scalability

1. Support horizontal scaling: As a system admin, I want the API to scale horizontally so that it can handle increased workloads by adding more service instances.

   1. Each microservice (e.g., Hosting Service, Compute Service) must support horizontal scaling by deploying additional instances dynamically.

   2. The system must handle sudden spikes in traffic without downtime, with a maximum latency increase of 10% during scaling events.

2. Ensure Availability: As a global user, I want the API to be available in multiple regions so that I can access services with low latency.

   1. API endpoints must be deployed in at least 3 global regions (e.g., North America, Europe, Asia).

   2. Latency for requests from any region must not exceed 300 milliseconds.

   3. The system must automatically route requests to the nearest region.

3. Implement Fault Tolerance: As a system admin, I want the API to remain operational even if individual services fail so that the system can continue providing core functionality.

   1. If an individual microservice (e.g., DID Resolver) fails, fallback mechanisms (e.g., secondary services) must ensure continued operation.

   2. Compute jobs and hosted content must be recoverable within 5 minutes after a failure.

   3. The system must retry failed requests to downstream services up to 3 times before returning an error.

Usability

1. Provide clear API documentation: As a developer, I want the API to include comprehensive documentation so that I can easily integrate it into my applications.

   1. The API must include OpenAPI (Swagger) documentation with detailed descriptions of endpoints, request/response formats, and error codes.

   2. Example requests and responses must be provided for each endpoint.

   3. Documentation must be accessible via a public developer portal.

2. Return Actionable Error Messages: As a user, I want the API to return clear error messages so that I can troubleshoot issues easily.

   1. Errors must include meaningful messages (e.g., "Invalid DID signature", "Rate limit exceeded").

   2. Errors must include an HTTP status code and contextual information (e.g., the DID involved, operation attempted).

   3. 4xx errors must provide guidance on how to resolve the issue.

3. Support Wallet Integration: As a user, I want the API to integrate with DID-compatible wallets so that I can easily sign authentication challenges.

   1. The API must support popular wallets such as MetaMask, uPort, and Trinsic for DID authentication.

   2. The cryptographic challenge must be presented in a wallet-compatible format (e.g., JSON-LD, JWT).

   3. Users must be notified if their wallet is incompatible with the API.

4. Optimize for Low Bandwidth Devices: As a mobile or IoT user, I want the API to minimize bandwidth usage so that I can interact with it efficiently on limited networks.

   1. API requests and responses must be lightweight, using optimized formats such as JSON or binary protocols where applicable.

   2. Large data transfers (e.g., file uploads, compute results) must be chunked to avoid timeouts or bandwidth overuse.

   3. The API must support pagination for large datasets.

Last updated: 2025-01-21 01:10:36.118330 File source:

Use Case: Create a Hosting Deployment

Table of Contents

Actors

• Primary Actor: AI Developer

• Supporting Actors:

  • Hosting Service

  • Storage Service

  • Billing Service

Goal in Context:

The user wants to deploy a new application on a decentralized hosting platform, using the NuActor framework for secure authentication.

Preconditions:

• The user has an application that is using working implementation of the the NuActor model (in our case DMS).

• The Hosting Service supports NuActor Auth and is functional (is running on DMS).

• The Storage Service is available for storing files.

Trigger:

• The user initiates a request to deploy a hosting environment.

Main Success Scenario:

User requests deployment: The user sends a deployment request to the Hosting Service, including their DID.

1. Authenticate user:

   • The user submits their DID to the hosting provider requesting permission deploy, along with a token addressed to the hosting providers DID that the hosting provider can use to authenticate (provide) their response back to the user. (the message is sent encrypted over the NuActor Substrate, libp2p)

   • The hosting provider creates an access token with the rights to deploy the application.and expiry timestamp and sends it back to the user, additionaly the hosting provider includes the token issued by the user additionally signed by them that proves they are who they say they are.

   • The user then saves this token and "provides" it in all future requests to the hosting provider. until such a time that it expires. The hosting provider will respect the capabilities in the certificate until its expiry (or any other certificates in it's chain) unless it is revoked.

2. Provision hosting: -The user submits the deployment request to the hosting service (this can be direct to the device/s that will run the application) The submission includes the token signed by the hosting provider that gives them access to launch the app.

   • Files are uploaded to the Storage Service and linked to the user’s DID.

3. Start billing:

   • The Nunet observability framework begins tracking hosting usage for the user.

   • Confirm deployment: The Hosting Service confirms successful deployment to the user.

Extensions:

1. Authentication failure:

   • If the token is invalid, the Hosting Service denies the request and notifies the user.

2. Storage failure:

   • If the Storage Service is unavailable, the Hosting Service retries or returns an error.

Functional Requirements

1. Create a Hosting Deployment: As a user, I want to deploy an application on a decentralized platform so that I can host my data securely using my DID for authentication.

   1. The Hosting Service must send a cryptographic challenge to the user's wallet upon a deployment request.

   2. The user must be able to sign the challenge with their DID private key.

   3. The Hosting Service must verify the signed challenge using the DID Document.

   4. Upon successful verification, the system must provision a hosting environment and store the user's files via the Storage Service.

   5. The deployment must be linked to the user’s DID, and a confirmation message must be sent to the user.

2. Access Hosted Content: As a user, I want to securely access my hosted content so that I can manage or view it without unauthorized access.

   1. The Hosting Service must require DID Auth for all access requests.

   2. A cryptographic challenge must be generated and verified before granting access.

   3. The Storage Service must retrieve the user’s files only if the DID Auth process is successful.

   4. If authentication fails, the system must deny access and notify the user.

3. Update Hosting Deployment: As a user, I want to update my hosted application so that I can modify its content securely.

   1. The Hosting Service must authenticate the user using DID Auth before any update request is processed.

   2. Updated files must be securely uploaded to the Storage Service and linked to the user’s DID.

   3. A confirmation message must be sent after the update is complete.

Diagrams

The following diagrams are added from from manually rendered source files in ./specs/ folder relative to this file. Current diagrams are just placeholders for further collaborative work aimed at reflecting actual design of the use-case.

Sequence Diagram

Deployment diagram

Last updated: 2025-01-21 01:10:36.669346 File source:

Make a Payment

Actors

• Primary Actor: AI Developer

• Supporting Actors:

  • Payment Service

  • Billing Microservice

  • DID Resolver

Goal in Context:

The user wants to make a crypto payment for services (e.g., hosting, compute) securely using their DID.

Preconditions:

• The user has a DID and a wallet capable of signing transactions.

• The Payment Service supports DID Auth and crypto payments.

• The Billing Microservice has generated a payment request.

Trigger:

The Billing Microservice generates a payment request for the user.

Main Success Scenario:

1. Payment request:

• The Payment Service notifies the user of a pending payment request.

1. Authenticate user:

   • The Payment Service generates a cryptographic challenge and sends it to the user.

   • The user signs the challenge using their DID private key and sends it back.

   • The Payment Service verifies the signature using the DID Document.

2. Process payment:

   • The user sends the payment transaction via their wallet.

   • The Payment Service verifies the payment and updates the user’s account status.

3. Confirm payment:

   • The Payment Service confirms the successful payment to the user and the Billing Microservice.

Extensions:

1. Authentication failure:

   • If the user fails to sign the challenge correctly, the Payment Service rejects the payment request.

2. Payment failure:

   • If the crypto payment fails (e.g., insufficient funds), the service notifies the user to retry.

3. Timeout:

   • If payment is not completed within a specified time, the request expires.

Functional Requirements

1. Make a payment: As a user, I want to make a crypto payment for services securely using my DID so that I can pay for my usage without exposing sensitive credentials.

   1. The Payment Service must authenticate the user using DID Auth before processing the payment.

   2. The user must be able to sign the payment request with their wallet.

   3. The system must verify the payment transaction and update the user’s account status upon successful payment.

   4. The user must receive a confirmation message once the payment is processed.

2. Verify Payment Status: As a user, I want to check the status of my payment so that I can confirm whether it has been processed successfully.

   1. The Payment Service must authenticate the user using DID Auth before providing payment status information.

   2. The user must be able to view the current status (e.g., pending, completed, failed) of their payment.

   3. If authentication fails, the system must deny the request and notify the user.

3. Request a Refund: As a user, I want to request a refund for an overpayment or unused service so that I can recover my funds securely.

   1. The Payment Service must authenticate the user using DID Auth before processing the refund request.

   2. The system must verify the user’s wallet ownership and ensure that the refund amount is valid.

   3. The user must receive a confirmation message once the refund is processed.