@stellar-agent-services/dev-mcp 0.0.0-stage → 0.1.1

package/repository/packages/protocol/schemas/manifest.schema.json

@@ -0,0 +1,272 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://algorialabs.github.io/stellar-agent-services/schemas/provider/1/manifest.schema.json",
+  "$comment": "The $id is provisional until the v1 freeze. Rule ids such as [M5] refer to docs/provider-standard.md.",
+  "title": "Provider Standard v1 manifest",
+  "description": "Describes a paid AI service on Stellar: its services, prices, payment option and job endpoints. Unknown fields are allowed and ignored [M8]. Some rules need code as well (§2.4): M1, M3, M5 (same origin), M7, S6, S9 and P11.",
+  "type": "object",
+  "required": ["standard", "provider", "baseUrl", "payment", "services"],
+  "properties": {
+    "standard": {
+      "description": "[M8] A manifest with a different major version is rejected.",
+      "const": "stellar-agent-services/provider@1"
+    },
+    "provider": { "$ref": "#/$defs/provider" },
+    "baseUrl": {
+      "description": "[M5] Job endpoints live under it. HTTPS, no user info, query, fragment, empty path segment or trailing slash. Same origin as the manifest URL, which is checked in code.",
+      "type": "string",
+      "maxLength": 300,
+      "pattern": "^https://[^\\s/?#@]+(/[^\\s/?#]+)*$"
+    },
+    "payment": { "$ref": "#/$defs/payment" },
+    "jobs": { "$ref": "#/$defs/jobs" },
+    "services": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 25,
+      "items": { "$ref": "#/$defs/service" }
+    },
+    "extensions": { "$ref": "#/$defs/extensions" }
+  },
+  "$defs": {
+    "provider": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "$ref": "#/$defs/line", "type": "string", "minLength": 1, "maxLength": 120 },
+        "description": { "$ref": "#/$defs/text", "type": "string", "maxLength": 500 },
+        "homepage": { "$ref": "#/$defs/httpsUrl" },
+        "agentId": {
+          "description": "Stellar 8004 agent id (u32), needed for the identity check (§7).",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295
+        },
+        "termsUrl": { "$ref": "#/$defs/httpsUrl" },
+        "dataUse": {
+          "type": "object",
+          "properties": {
+            "storesInputs": {
+              "description": "Whether inputs are kept after the job finishes.",
+              "type": "boolean"
+            },
+            "trainsOnInputs": {
+              "description": "Whether inputs are used to train models.",
+              "type": "boolean"
+            }
+          }
+        }
+      }
+    },
+    "payment": {
+      "type": "object",
+      "required": ["protocol", "x402Version", "accepts"],
+      "properties": {
+        "protocol": { "const": "x402" },
+        "x402Version": { "const": 2 },
+        "accepts": {
+          "description": "[P1] Exactly one payment option in v1.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "items": { "$ref": "#/$defs/paymentOption" }
+        }
+      }
+    },
+    "paymentOption": {
+      "description": "x402 v2 PaymentRequirements field names, without amount, which comes from each service's price [P1].",
+      "type": "object",
+      "required": ["scheme", "network", "asset", "payTo", "maxTimeoutSeconds", "extra"],
+      "properties": {
+        "scheme": { "const": "exact" },
+        "network": { "enum": ["stellar:testnet", "stellar:pubnet"] },
+        "asset": {
+          "description": "The USDC Stellar Asset Contract for the network.",
+          "type": "string"
+        },
+        "payTo": {
+          "description": "A G... account or C... contract address. Its checksum is checked in code [P11].",
+          "type": "string",
+          "pattern": "^[GC][A-D][A-Z2-7]{54}$"
+        },
+        "amount": false,
+        "maxTimeoutSeconds": { "type": "integer", "minimum": 30, "maximum": 300 },
+        "extra": {
+          "type": "object",
+          "required": ["areFeesSponsored"],
+          "properties": {
+            "areFeesSponsored": { "const": true }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "required": ["network"],
+            "properties": { "network": { "const": "stellar:testnet" } }
+          },
+          "then": {
+            "type": "object",
+            "properties": { "asset": { "const": "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA" } }
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "required": ["network"],
+            "properties": { "network": { "const": "stellar:pubnet" } }
+          },
+          "then": {
+            "type": "object",
+            "properties": { "asset": { "const": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75" } }
+          }
+        }
+      ]
+    },
+    "jobs": {
+      "type": "object",
+      "properties": {
+        "retentionSeconds": {
+          "description": "How long results stay retrievable.",
+          "type": "integer",
+          "minimum": 3600,
+          "default": 86400
+        }
+      }
+    },
+    "service": {
+      "type": "object",
+      "required": ["name", "description", "price", "inputSchema", "outputSchema"],
+      "properties": {
+        "name": {
+          "description": "Unique in the manifest [M7]. A URL path segment, an MCP tool name and an LLM function name.",
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+        },
+        "title": { "$ref": "#/$defs/line", "type": "string", "minLength": 1, "maxLength": 120 },
+        "description": { "$ref": "#/$defs/text", "type": "string", "minLength": 1, "maxLength": 1000 },
+        "price": {
+          "type": "object",
+          "required": ["amount"],
+          "properties": {
+            "amount": {
+              "description": "A positive integer in the asset's base units. USDC has 7 decimals, so \"100000\" is 0.01 USDC.",
+              "type": "string",
+              "pattern": "^[1-9][0-9]{0,37}$"
+            }
+          }
+        },
+        "charge": {
+          "description": "When the user is charged (§3.2).",
+          "enum": ["on-success", "upfront"],
+          "default": "upfront"
+        },
+        "expectedDurationSeconds": { "type": "integer", "minimum": 1 },
+        "inputSchema": { "$ref": "#/$defs/objectSchema" },
+        "outputSchema": { "$ref": "#/$defs/objectSchema" },
+        "examples": {
+          "description": "Each input and output must match the service's schemas, which is checked in code [S9].",
+          "type": "array",
+          "maxItems": 5,
+          "items": {
+            "type": "object",
+            "required": ["input", "output"],
+            "properties": {
+              "input": { "type": "object" },
+              "output": { "type": "object" }
+            }
+          }
+        },
+        "maxInputBytes": { "type": "integer", "minimum": 1, "maximum": 10485760, "default": 1048576 },
+        "tags": {
+          "type": "array",
+          "maxItems": 10,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[a-z0-9-]{1,32}$" }
+        },
+        "capacity": {
+          "description": "How much load the service takes (§5.8). Hints only: the provider's 429, 503 and queue answers are what count.",
+          "type": "object",
+          "properties": {
+            "concurrency": {
+              "description": "Jobs the service runs at the same time.",
+              "type": "integer",
+              "minimum": 1
+            },
+            "maxQueueWaitSeconds": {
+              "description": "Longest a new job may expect to wait in the queue; beyond it, create-job answers 503. 0 means no queue.",
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "extensions": { "$ref": "#/$defs/extensions" }
+      },
+      "if": {
+        "type": "object",
+        "required": ["charge"],
+        "properties": { "charge": { "const": "on-success" } }
+      },
+      "then": { "type": "object", "required": ["expectedDurationSeconds"] }
+    },
+    "objectSchema": {
+      "description": "[S4] A JSON Schema 2020-12 schema whose root is \"type\": \"object\". [S5] It references nothing outside itself. Its size is checked in code [S6].",
+      "allOf": [
+        { "$ref": "https://json-schema.org/draft/2020-12/schema" },
+        { "$ref": "#/$defs/localReferencesOnly" },
+        {
+          "type": "object",
+          "required": ["type"],
+          "properties": { "type": { "const": "object" } }
+        }
+      ]
+    },
+    "localReferencesOnly": {
+      "description": "[S5] Wherever they appear, $ref and $dynamicRef start with \"#\", and $schema is JSON Schema 2020-12. Deliberately conservative: it also applies inside const, enum, default and examples.",
+      "if": { "type": "object" },
+      "then": {
+        "type": "object",
+        "properties": {
+          "$ref": { "$ref": "#/$defs/localReference" },
+          "$dynamicRef": { "$ref": "#/$defs/localReference" },
+          "$schema": {
+            "if": { "type": "string" },
+            "then": { "type": "string", "const": "https://json-schema.org/draft/2020-12/schema" },
+            "else": { "$ref": "#/$defs/localReferencesOnly" }
+          }
+        },
+        "additionalProperties": { "$ref": "#/$defs/localReferencesOnly" }
+      },
+      "else": {
+        "if": { "type": "array" },
+        "then": { "type": "array", "items": { "$ref": "#/$defs/localReferencesOnly" } }
+      }
+    },
+    "localReference": {
+      "if": { "type": "string" },
+      "then": { "type": "string", "pattern": "^#" },
+      "else": { "$ref": "#/$defs/localReferencesOnly" }
+    },
+    "httpsUrl": {
+      "description": "[M6] An HTTPS URL of at most 300 characters, without user info.",
+      "type": "string",
+      "maxLength": 300,
+      "pattern": "^https://[^\\s/?#@]+([/?#]\\S*)?$"
+    },
+    "line": {
+      "description": "Text without control characters.",
+      "type": "string",
+      "pattern": "^[^\u0000-\u001f\u007f]*$"
+    },
+    "text": {
+      "description": "Text that may contain tabs and newlines but no other control characters.",
+      "type": "string",
+      "pattern": "^[^\u0000-\u0008\u000b-\u001f\u007f]*$"
+    },
+    "extensions": {
+      "description": "[X1] Fields outside this standard. Keys SHOULD be reverse-DNS names such as com.example.sla.",
+      "type": "object"
+    }
+  }
+}

package/repository/packages/protocol/test-vectors/README.md

@@ -0,0 +1,45 @@
+# Provider Standard v1 test vectors
+
+Known-answer tests for [Provider Standard v1](../../../docs/provider-standard.md). An implementation in any
+language can check itself against these files. `packages/protocol` runs all of them in its own tests.
+
+| File | What it pins | Spec |
+| --- | --- | --- |
+| `canonical-json.json` | RFC 8785 canonical JSON and its SHA-256, including the RFC's own examples | §5.3, verification receipts |
+| `binding-hash.json` | The job binding hash | §5.3 |
+| `headers.json` | `Idempotency-Key` and `Job-Token` formats | §5.2 |
+| `manifests.json` | Manifest validation: the JSON Schema and the rules it can't express | §2.4 |
+| `challenges.json` | Checking an x402 challenge against the approved manifest | §4.2 |
+| `job-states.json` | Allowed job state transitions and the `charged` value of each state | §5.6 |
+| `problems.json` | Error codes, their HTTP status and Retry-After, and job failure codes | §6 |
+| `validation-requests.json` | Validation request documents: their canonical bytes, `request_hash` and `data:` URI, and the JSON Schema | [verification.md](../../../docs/verification.md#stellar-8004-validation-registry) |
+
+## Conventions
+
+- **Patches.** `manifests.json` and `challenges.json` describe each case as a small change to a base document,
+  using the `add`, `replace` and `remove` operations of JSON Patch (RFC 6902). A last path segment of `-`
+  appends to an array.
+- **Violations.** Each `{ "rule", "pointer" }` is a rule id from the spec and a JSON Pointer (RFC 6901) to the
+  offending value, or to where a missing field belongs. Compare them as a set. Messages are not part of the
+  vectors.
+- **`checkedBy`.** In `manifests.json`, `"schema"` cases fail the
+  [manifest JSON Schema](../schemas/manifest.schema.json). `"code"` cases pass it and fail only the rules JSON
+  Schema can't express. If you validate in code only, every invalid case must still fail.
+- **Numbers** are IEEE 754 doubles, as I-JSON requires. Integers beyond ±(2^53 − 1) aren't interoperable, so the
+  vectors avoid them. Services should send such values as strings.
+- **Duplicate keys** make a document invalid I-JSON, but many parsers can't detect them, so no vector covers
+  them.
+
+## How they were made
+
+The expected values were generated once and checked before they were written:
+- canonical JSON against the independent [`canonicalize`](https://github.com/erdtman/canonicalize) package by an
+  RFC 8785 author;
+- the RFC 8785 examples (§3.2.2, §3.2.3, Appendix B) against the text of the RFC;
+- hashes against a second SHA-256 implementation;
+- every manifest and challenge case against Ajv with the JSON Schema, and against `packages/protocol`;
+- validation requests with Python's `json`, `hashlib` and `base64` modules, apart from `packages/protocol`, and the
+  hashes again with `shasum`;
+- job states and error codes by hand from the tables in §5.6 and §6.
+
+When you change a vector, run `npm test` and review the diff by hand.