diff --git a/conformance/docgo/requestflows/handler.go b/conformance/docgo/requestflows/handler.go deleted file mode 100644 index 4f3d1858..00000000 --- a/conformance/docgo/requestflows/handler.go +++ /dev/null @@ -1,259 +0,0 @@ -// Code generated from website/src/content/docs/components/exchange/request-flows.mdx -// ("Handler Implementation"). DO NOT EDIT. Regenerate with -// FORA_UPDATE_VECTORS=1 go test ./conformance -run TestDocHandlerExampleCompiles - -package requestflows - -import ( - "context" - "errors" - "time" - - "connectrpc.com/connect" - "google.golang.org/protobuf/proto" - - forav1 "github.com/FORA-Protocol/protocol/gen/go/fora/v1" - "github.com/FORA-Protocol/protocol/sdk/go/connectserver" - "github.com/FORA-Protocol/protocol/sdk/go/helpers" -) - -func (h *ExchangeHandler) DiscoverResources( - ctx context.Context, - req *connect.Request[forav1.ResourceQuery], -) (*connect.Response[forav1.ResourceResponse], error) { - // 1. Validate - if err := validate(req.Msg); err != nil { - return nil, connect.NewError(connect.CodeInvalidArgument, err) - } - - // 1b. Respect deadline field from ResourceQuery. - // If req.Msg.Deadline is set, use it as the context timeout. - // If absent, use a 500ms default timeout for the entire handler. - if req.Msg.Deadline != nil { - var cancel context.CancelFunc - ctx, cancel = context.WithTimeout(ctx, req.Msg.Deadline.AsDuration()) - defer cancel() - } else { - var cancel context.CancelFunc - ctx, cancel = context.WithTimeout(ctx, 500*time.Millisecond) - defer cancel() - } - - // 2. Requester identity. Verification already happened at the HTTP seam: - // the SDK's verify middleware checked the RFC 9421 signature of the - // party that sent the request — the agent, or a Broker that originated - // or re-packaged it (Authentication > Multi-hop forwarding) — resolving the signer's key - // by its signed keyid (an RFC 7638 thumbprint) in the key directory - // named by the `Signature-Agent` member that signature covers. The - // self-asserted Requester.domain field never drives request-signing key - // lookup. - // The handler consumes the proof from the context; it never re-fetches - // keys or re-verifies bytes, and it fails closed when the proof is - // absent (a route the middleware does not guard). - requester := req.Msg.Requester - verified := helpers.FromContext(ctx) // the first verified signature in header order; all of them via helpers.AllSignaturesFromContext - if verified == nil { - return nil, connect.NewError(connect.CodeUnauthenticated, - errors.New("request reached the handler without a verified signature")) - } - - // 2b. Direct or Broker-led ("Direct and relayed requests" in the protocol). - // Requester.domain is the host of the agent's key directory, never a - // free label. When it names the directory the signature resolved from - // (the host of the covered Signature-Agent URL, compared by the - // request-recipient identity rule: case-folded, an absent port the same - // as :443), the query is DIRECT: the agent signed it. When it names - // another directory, the query is one a Broker originated, which this - // Exchange acts on only when it admits the signer as a Broker; there the - // domain is the Broker's statement of whom it queries for, and nothing - // on this leg authenticates the agent. Any other mismatch is a signature - // that verifies, but not for the requester the body names. - host, err := helpers.HostOf(verified.SignatureAgent) - verdict := helpers.AudienceMalformed - if err == nil { - verdict, err = helpers.CheckAudience(host, requester.GetDomain()) - } - direct := err == nil && verdict == helpers.AudienceAccepted - brokerLed := err == nil && verdict == helpers.AudienceMismatch && - h.brokers.Admits(verified.SignatureAgent) - if !direct && !brokerLed { - return nil, connectserver.AttachDetail( - connect.NewError(connect.CodeUnauthenticated, errors.New("requester.domain is not the signing directory")), - helpers.RequestAuthFailureDetail("fora.v1.ExchangeService", "requester.domain is not the signing directory", - forav1.RequestAuthFailureReason_REQUEST_AUTH_FAILURE_REASON_SIGNATURE_INVALID)) - } - - // 2c. On a DIRECT query, resolve the agent's registered account from the - // directory the signature resolved from (verified.SignatureAgent; see - // "Accounts" on the authentication page). Every currently valid key that - // directory publishes acts for the account, so the key that verified - // does not select it, and neither does requester.id, a free label. A - // query a Broker originated authenticates no agent, so this Exchange - // consults no account for it (its own choice; the protocol leaves it - // open) and presents on the stated scopes alone. - var account *Account - if direct { - account, err = h.accounts.ForDirectory(ctx, verified.SignatureAgent) - if err != nil { - return nil, connect.NewError(connect.CodePermissionDenied, err) - } - } - - // 3. Resolve tenant - tenantCfg, err := h.tenants.ResolveFromURIs(req.Msg.Uris) - if err != nil { - return nil, connect.NewError(connect.CodeNotFound, err) - } - - // 3b. Verify the delegation (if present) on a DIRECT query, once per - // subscription record. Trust is per record: the SDK verifier is given - // the keys that record lists, so an issuer trusted for one subscription - // grants nothing on another. A record whose keys refuse the chain keeps - // its gated terms hidden; the refusal is journaled, never reported. The - // holder is the RFC 9421 signer's key from the HTTP proof of step 2, - // which stays separate from the delegation result. On a query a Broker - // originated the Broker signs alone, so nothing can pass the holder - // binding: the delegation is not honoured, and the query is answered - // as if none were present. A token over the size limit never gets - // here: step 1 refused the request. - grants := map[string]*helpers.VerifiedDelegation{} // subscription record ID -> verified grant - if direct && requester.GetDelegation() != nil { - holder, err := helpers.Thumbprint(verified.PublicKey) - if err != nil { - return nil, connect.NewError(connect.CodeInternal, err) - } - for _, record := range h.subscriptions.RecordsForTenant(ctx, tenantCfg.ID) { - grant, err := helpers.VerifyDelegation(helpers.DelegationInput{ - Token: requester.GetDelegation().GetToken(), - TrustedIssuers: record.TrustedIssuers, - Audience: tenantCfg.Identity, - Holder: holder, - Now: h.clock.Now(), - }) - if err != nil { - h.journal.DelegationRefused(ctx, record.ID, err) - continue - } - grants[record.ID] = grant - } - } - - // 4. Application-level abuse check (optional — volumetric rate limiting is at infra layer) - // The Exchange MAY return 429 for application-level abuse, e.g., query-to-transaction - // ratio too low (agent discovering but never buying). Volumetric rate limiting (per-IP, - // per-tenant RPS caps) belongs in HAProxy/Envoy/API Gateway in front of this service. - - // 5. Catalog lookup (lock-free read, scope-filtered) - // A non-gated term is filtered by requester.scopes, the requester's own - // statement — terms outside the stated scopes are not returned. A gated - // term (a subscription term) is presented only when the grant verified - // under the term's own subscription record covers the term's scopes, by - // the one matching rule on Requester.scopes; requester.scopes is ignored - // for it, and a record with no grant — every record on a query a Broker - // originated (3b) — keeps its gated terms hidden, as if they did not - // exist. The catalog bounds each gated offer's expires_at by its grant's - // ExpiresAt, so the offer never outlives the chain. - offers, err := h.catalog.FindOffers(ctx, tenantCfg.ID, req.Msg.Uris, requester.Scopes, grants) - if err != nil { - return nil, connect.NewError(connect.CodeInternal, err) - } - - // 5b. Check for active subscription, on a DIRECT query (step 2d). - // If the requester has an active subscription with this tenant, include a - // subscription offer variant (rate=0) for each catalog offer with - // SubscriptionQuotaInfo attached. Quota enforcement is deferred to - // ExecuteTransaction time — DiscoverResources checks subscription status - // and populates quota visibility. Subscription/entitlement is resolved - // from the registered account of step 2d (plus any delegation) — never - // from the caller-written requester.id. A query a Broker originated has - // no account here, so it gets no subscription variant. - var subStatus *SubscriptionStatus - if account != nil { - if sub, err := h.billing.CheckSubscription(ctx, account.BillingRef, tenantCfg.ID); err == nil && sub.Active { - subStatus = sub - } - } - - // Build subscription offer variants per catalog offer (if subscription active). - // Each subscription offer includes SubscriptionQuotaInfo so agents can see - // remaining quota before committing to a transaction. - if subStatus != nil { - var subOffers []*forav1.Offer - for _, offer := range offers { - subOffer := proto.Clone(offer).(*forav1.Offer) - // A subscription variant is a distinct offer, so it gets a fresh - // opaque offer_id — never one derived from the base offer's id. - subOffer.OfferId = "offer-" + newOpaqueID() - subOffer.SubscriptionId = proto.String(subStatus.SubscriptionID) - subOffer.Pricing = &forav1.Pricing{ - Model: offer.Pricing.Model, - Rate: "0", // zero marginal cost under subscription; money is a decimal string - Currency: offer.Pricing.Currency, - UnitCost: proto.String("0"), - EstimatedQuantity: offer.Pricing.EstimatedQuantity, - } - // Populate SubscriptionQuotaInfo for proactive quota signaling - subOffer.SubscriptionQuota = h.billing.SubscriptionQuota( - ctx, subStatus.SubscriptionID, tenantCfg.ID, - ) - subOffers = append(subOffers, subOffer) - } - offers = append(offers, subOffers...) - } - - // 6. Attach reporting obligations (per-tenant default, not per-offer lookup) - // Reporting obligation is set once in tenant config. All offers inherit the - // tenant's reporting obligation unless explicitly overridden (rare). - tenantReporting := h.reporting.GetPolicy(tenantCfg.ID) - for _, offer := range offers { - offer.Reporting = tenantReporting - } - - // 7. Ed25519-sign every offer (MANDATORY — enables stateless ExecuteTransaction) - // Ed25519 is the default for offers because agents and Brokers must - // verify signatures without holding the signing key. The Exchange signs - // with its Ed25519 private key; anyone verifies with the public key. - for _, offer := range offers { - sig, err := h.offerSigner.Sign(offer) - if err != nil { - return nil, connect.NewError(connect.CodeInternal, err) - } - offer.Signature = sig - offer.SignatureAlgorithm = "EdDSA" - } - - // 8. Build response — flat offers or OfferGroups depending on URI count. - // When the ResourceQuery contains multiple URIs, return OfferGroups - // (one per URI) so the caller knows which offers map to which resource. - // When a single URI is queried, use the flat offers field. - uris := req.Msg.Uris - if len(uris) > 1 { - // Batch mode: group offers by requested URI. - groups := make([]*forav1.OfferGroup, 0, len(uris)) - for _, uri := range uris { - var uriOffers []*forav1.Offer - for _, offer := range offers { - if offerMatchesURI(offer, uri) { - uriOffers = append(uriOffers, offer) - } - } - groups = append(groups, &forav1.OfferGroup{ - Uri: uri, - Offers: uriOffers, // empty slice = resource not available for this URI - }) - } - return connect.NewResponse(&forav1.ResourceResponse{ - Ver: helpers.ProtocolVersion, - Exchange: h.exchangeDomain, - OfferGroups: groups, - }), nil - // Correlation is not echoed in the body: it rides the X-Request-ID - // HTTP header, propagated across the request/response round-trip. - } - - return connect.NewResponse(&forav1.ResourceResponse{ - Ver: helpers.ProtocolVersion, - Exchange: h.exchangeDomain, - Offers: offers, - }), nil -} diff --git a/conformance/docgo/requestflows/scaffold.go b/conformance/docgo/requestflows/scaffold.go deleted file mode 100644 index 14d04877..00000000 --- a/conformance/docgo/requestflows/scaffold.go +++ /dev/null @@ -1,88 +0,0 @@ -// Package requestflows compiles the DiscoverResources handler example of the -// Exchange request-flows page against typed stubs, so a variable used before -// it is declared, a name that is never defined or a wrong SDK call fails -// `go build` instead of sitting in the documentation. handler.go is extracted -// from the page by conformance/docgo_test.go; this file is the scaffold the -// example needs and the only hand-written part. -package requestflows - -import ( - "context" - "crypto/rand" - "encoding/hex" - "time" - - forav1 "github.com/FORA-Protocol/protocol/gen/go/fora/v1" - "github.com/FORA-Protocol/protocol/sdk/go/helpers" -) - -// ExchangeHandler is the handler the example is a method of. Every field is -// an interface the example calls; none has an implementation here. -type ExchangeHandler struct { - brokers interface { - Admits(signatureAgent string) bool - } - accounts interface { - ForDirectory(ctx context.Context, directory string) (*Account, error) - } - tenants interface { - ResolveFromURIs(uris []string) (*TenantConfig, error) - } - subscriptions interface { - RecordsForTenant(ctx context.Context, tenantID string) []SubscriptionRecord - } - journal interface { - DelegationRefused(ctx context.Context, recordID string, err error) - } - catalog interface { - FindOffers(ctx context.Context, tenantID string, uris, statedScopes []string, grants map[string]*helpers.VerifiedDelegation) ([]*forav1.Offer, error) - } - billing Billing - reporting interface { - GetPolicy(tenantID string) *forav1.ReportingObligation - } - offerSigner interface { - Sign(offer *forav1.Offer) (string, error) - } - clock interface{ Now() time.Time } - exchangeDomain string -} - -// Billing answers subscription questions for the account the query resolved. -type Billing interface { - CheckSubscription(ctx context.Context, billingRef, tenantID string) (*SubscriptionStatus, error) - SubscriptionQuota(ctx context.Context, subscriptionID, tenantID string) []*forav1.SubscriptionQuotaInfo -} - -// Account is the registered account a key directory resolves to. -type Account struct{ BillingRef string } - -// TenantConfig is the publisher tenant the queried URIs belong to. Identity is -// the Exchange's own recipient identity, the value a delegation's aud must name. -type TenantConfig struct{ ID, Identity string } - -// SubscriptionRecord is one subscription with the root issuer keys it trusts. -type SubscriptionRecord struct { - ID string - TrustedIssuers []helpers.TrustedIssuer -} - -// SubscriptionStatus is the billing view of one subscription. -type SubscriptionStatus struct { - Active bool - SubscriptionID string -} - -func validate(msg *forav1.ResourceQuery) error { return helpers.Validate(msg) } - -// offerMatchesURI reports whether an offer answers the queried URI. -func offerMatchesURI(offer *forav1.Offer, uri string) bool { - return offer.GetIdentity().GetCanonicalUrl() == uri -} - -// newOpaqueID mints an opaque offer id; the example only needs it to be fresh. -func newOpaqueID() string { - var b [16]byte - _, _ = rand.Read(b[:]) - return hex.EncodeToString(b[:]) -} diff --git a/conformance/docgo/requestflows/scaffold_test.go b/conformance/docgo/requestflows/scaffold_test.go deleted file mode 100644 index 8164659b..00000000 --- a/conformance/docgo/requestflows/scaffold_test.go +++ /dev/null @@ -1,7 +0,0 @@ -package requestflows - -import "testing" - -// TestScaffoldCompiles exists so `go test ./...` builds this package; the -// compile itself is the check. -func TestScaffoldCompiles(t *testing.T) { _ = (&ExchangeHandler{}).DiscoverResources } diff --git a/conformance/docgo_test.go b/conformance/docgo_test.go deleted file mode 100644 index 6fc93140..00000000 --- a/conformance/docgo_test.go +++ /dev/null @@ -1,55 +0,0 @@ -package conformance - -import ( - "go/format" - "os" - "path/filepath" - "strings" - "testing" -) - -// TestDocHandlerExampleCompiles pins the DiscoverResources handler example of -// the Exchange request-flows page to conformance/docgo/requestflows/handler.go, -// a package that compiles the example against typed stubs. The page is the -// source: under FORA_UPDATE_VECTORS=1 the file is rewritten from it, otherwise -// the two must match, and `go test ./...` compiles the package, so an example -// that uses a variable before declaring it or calls the SDK wrongly fails CI. -func TestDocHandlerExampleCompiles(t *testing.T) { - page, err := os.ReadFile(filepath.Join("..", "website", "src", "content", "docs", "components", "exchange", "request-flows.mdx")) - if err != nil { - t.Fatal(err) - } - content := string(page) - i := strings.Index(content, "### Handler Implementation") - if i < 0 { - t.Fatal("request-flows.mdx has no Handler Implementation section") - } - content = content[i:] - start := strings.Index(content, "```go\n") - if start < 0 { - t.Fatal("no Go fence under Handler Implementation") - } - content = content[start+len("```go\n"):] - block := content[:strings.Index(content, "```")] - - path := filepath.Join("docgo", "requestflows", "handler.go") - existing, err := os.ReadFile(path) - if err != nil { - t.Fatal(err) - } - preamble := string(existing)[:strings.Index(string(existing), "func (h *ExchangeHandler) DiscoverResources(")] - formatted, err := format.Source([]byte(preamble + block)) - if err != nil { - t.Fatalf("the example does not parse as Go: %v", err) - } - want := string(formatted) - if os.Getenv("FORA_UPDATE_VECTORS") == "1" { - if err := os.WriteFile(path, []byte(want), 0o644); err != nil { - t.Fatal(err) - } - return - } - if string(existing) != want { - t.Fatalf("%s differs from the example on the page; regenerate with FORA_UPDATE_VECTORS=1", path) - } -} diff --git a/sdk/go/helpers/gen_delegation_chains_test.go b/sdk/go/helpers/gen_delegation_chains_test.go index 59cece82..7098723f 100644 --- a/sdk/go/helpers/gen_delegation_chains_test.go +++ b/sdk/go/helpers/gen_delegation_chains_test.go @@ -33,9 +33,8 @@ import ( // // A case's mirrors are the plaintext Delegation fields an Exchange receives // next to the token. Nothing in this repository reads them: the verifier takes -// only the token, and the handler example in conformance/docgo is compiled, -// not run. Only an Exchange's own tests replay the mirrors, by sending the -// case's Delegation message and checking the offers come out as declared. +// only the token. Only an Exchange's own tests replay the mirrors, by sending +// the case's Delegation message and checking the offers come out as declared. // chainFileNote is written at the top of delegation-chains.json so a reader of // the file sees the two contracts above without opening this generator. diff --git a/website/astro.config.mjs b/website/astro.config.mjs index ee5fe7f9..587a3f64 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -152,6 +152,13 @@ export default defineConfig({ { label: 'Components', items: [ + { + label: 'Exchange', + items: [ + { label: 'Overview', slug: 'components/exchange/overview' }, + { label: 'Billing and Ledgers', slug: 'components/exchange/billing-adapter' }, + ], + }, { label: 'Broker', items: [ diff --git a/website/redirects.json b/website/redirects.json index 98681b86..acaf0bbe 100644 --- a/website/redirects.json +++ b/website/redirects.json @@ -29,6 +29,36 @@ "target": "/components/broker/overview/", "status": "301" }, + { + "source": "/components/exchange/request-flows/", + "target": "/components/exchange/overview/", + "status": "301" + }, + { + "source": "/components/exchange/configuration/", + "target": "/components/exchange/overview/", + "status": "301" + }, + { + "source": "/components/exchange/storage-model/", + "target": "/components/exchange/overview/", + "status": "301" + }, + { + "source": "/components/exchange/multi-tenant/", + "target": "/components/exchange/overview/", + "status": "301" + }, + { + "source": "/components/exchange/scaling/", + "target": "/components/exchange/overview/", + "status": "301" + }, + { + "source": "/components/exchange/health-checks/", + "target": "/components/exchange/overview/", + "status": "301" + }, { "source": "/security/threat-model/", "target": "/protocol/authentication/", diff --git a/website/routes.txt b/website/routes.txt index 76e54cd1..391b6a6b 100644 --- a/website/routes.txt +++ b/website/routes.txt @@ -26,13 +26,7 @@ /components/edge-function/overview/ /components/edge-function/signed-url-verification/ /components/exchange/billing-adapter/ -/components/exchange/configuration/ -/components/exchange/health-checks/ -/components/exchange/multi-tenant/ /components/exchange/overview/ -/components/exchange/request-flows/ -/components/exchange/scaling/ -/components/exchange/storage-model/ /components/identity/overview/ /components/transaction-log/event-types/ /components/transaction-log/overview/ diff --git a/website/src/content/docs/components/exchange/billing-adapter.mdx b/website/src/content/docs/components/exchange/billing-adapter.mdx index f90177d1..d9b1834c 100644 --- a/website/src/content/docs/components/exchange/billing-adapter.mdx +++ b/website/src/content/docs/components/exchange/billing-adapter.mdx @@ -1,389 +1,142 @@ --- -title: "Billing Adapter" -description: "Pluggable billing interface for Exchange operator integration, pricing computation, unit_cost normalization, subscription handling, and revenue tracking." +title: "Billing and Ledgers" +description: "How FORA Server's Exchange charges an agent's account: the billing adapter contract, the three ledgers, currencies, identifiers, the charging flow, free and subscription items, fees and publisher revenue, and failure handling." --- -## Billing Adapter Interface +The Exchange charges each purchase to the agent's account at that Exchange. The protocol defines what a purchase costs, and it leaves settlement outside the protocol (see [How Money Flows](/getting-started/how-money-flows/)). Inside FORA Server's Exchange, every charge goes through one Go interface, the billing adapter. The adapter is the only part of the Exchange that talks to a ledger. -The Billing Adapter is the pluggable boundary between the open-source Exchange and the Exchange operator's proprietary billing system. It is the single point of custom integration per deployment. +FORA Server includes three adapters, and `FORA_BILLING_ADAPTER` selects one at boot. -### Go Interface +## Adapter contract -```go -// BillingAdapter is the interface that Exchange operators implement to connect -// their billing system to the Exchange. This is the proprietary boundary. -// -// Implementations must be safe for concurrent use by multiple goroutines. -// All methods accept a context for timeout/cancellation propagation. -type BillingAdapter interface { - // Authorize checks whether the requester can afford this transaction. - // Called synchronously during ExecuteTransaction, before signing. - // - // Must be fast (< 30ms p99). If the billing system is slow, - // consider caching recent authorizations. - // - // The adapter MAY reserve funds (hold) at this stage. - // If the transaction fails after authorization, Release() is called. - Authorize(ctx context.Context, req *BillingAuthorizeRequest) (*BillingAuthorizeResponse, error) - - // Record confirms a completed transaction in the billing system. - // Called after the transaction log write and URL signing succeed. - // - // This is best-effort from the Exchange's perspective — if it fails, - // the transaction is already committed. Reconciliation catches gaps. - Record(ctx context.Context, req *BillingRecordRequest) (*BillingRecordResponse, error) - - // Release cancels a previously authorized hold. - // Called when a transaction fails after Authorize() but before completion. - Release(ctx context.Context, billingID string) error - - // GetBalance returns the requester's remaining balance or credit. - // Optional — used for informational purposes only. - // Return ErrNotSupported if the billing system doesn't support balance queries. - GetBalance(ctx context.Context, billingRef string) (*BillingBalance, error) - - // CheckSubscription checks whether the requester has an active subscription with the tenant. - // Returns subscription status including quota and unit value for financial attribution. - // Used by DiscoverResources to include zero-cost subscription offers and by ExecuteTransaction - // to skip per-request billing authorization for subscription-based access. - CheckSubscription(ctx context.Context, billingRef string, tenantID string) (*SubscriptionStatus, error) -} - -// SubscriptionStatus describes the state of a requester's subscription with a tenant. -type SubscriptionStatus struct { - SubscriptionID string - Active bool - QuotaRemaining int64 - UnitValue *forav1.Cost // for subscription_unit_value (ASC 606 prepaid drawdown) -} - -type BillingAuthorizeRequest struct { - BillingRef string // The requester's billing reference (handle into the operator's billing system) - Amount float64 // Transaction amount - Currency string // ISO 4217 - OfferID string // For audit trail - TenantID string // Provider tenant -} - -type BillingAuthorizeResponse struct { - Approved bool - BillingID string // Operator's billing reference (becomes billing_id in TransactionResponse) - Reason string // If denied, why -} - -type BillingRecordRequest struct { - BillingID string - TransactionID string - Amount float64 - Currency string - TenantID string - BillingRef string - ContentURI string - Timestamp time.Time -} - -type BillingRecordResponse struct { - Recorded bool -} - -type BillingBalance struct { - Available float64 - Currency string - CreditLimit float64 // 0 = no credit -} -``` - ---- - -## Reference Implementation: In-Memory - -For development, testing, and PoC deployments: +The interface is `billing.Adapter`, in the `src/exchange/internal/billing/adapter.go` file in the FORA Server repository. The adapter represents money as an exact decimal, never as a floating-point number: ```go -// InMemoryBillingAdapter is the reference implementation for development. -// All state is in-memory — lost on restart. -type InMemoryBillingAdapter struct { - mu sync.RWMutex - balances map[string]float64 // billing reference -> balance - holds map[string]float64 // billing ID -> held amount - records []BillingRecordRequest -} - -func NewInMemoryBillingAdapter(initialBalances map[string]float64) *InMemoryBillingAdapter { - return &InMemoryBillingAdapter{ - balances: initialBalances, - holds: make(map[string]float64), - } -} - -func (a *InMemoryBillingAdapter) Authorize( - ctx context.Context, req *BillingAuthorizeRequest, -) (*BillingAuthorizeResponse, error) { - a.mu.Lock() - defer a.mu.Unlock() - - balance, ok := a.balances[req.BillingRef] - if !ok { - return &BillingAuthorizeResponse{ - Approved: false, - Reason: "unknown requester", - }, nil - } - if balance < req.Amount { - return &BillingAuthorizeResponse{ - Approved: false, - Reason: fmt.Sprintf("insufficient balance: %.4f < %.4f", balance, req.Amount), - }, nil - } - - billingID := fmt.Sprintf("bill-%s", ulid.Make().String()) - a.balances[req.BillingRef] -= req.Amount - a.holds[billingID] = req.Amount - - return &BillingAuthorizeResponse{ - Approved: true, - BillingID: billingID, - }, nil +// Amount is an exact decimal value in one currency. +type Amount struct { + Value *big.Rat + Currency string +} + +type AuthorizeRequest struct { + TenantID string + BillingRef string // the agent's account, from Register + UnitCost Amount + Quantity int64 // the offer's estimated quantity, at least 1 + Unit string // for example "tokens" + IdempotencyKey string + ResourceOwnerID string // the payee + FeeRateBps int // the Exchange's fee, in basis points +} + +type AuthorizeResult struct { + BillingID string + Approved bool + Reason string // set when Approved is false +} + +type Adapter interface { + EnsureAgentAccount(ctx context.Context, billingRef string) error + Credit(ctx context.Context, billingRef string, amount Amount, idempotencyKey string) error + Authorize(ctx context.Context, req AuthorizeRequest) (AuthorizeResult, error) + Record(ctx context.Context, billingID string, advisoryQuantity int64, idempotencyKey string) error + Release(ctx context.Context, billingID string, idempotencyKey string) error + Refund(ctx context.Context, billingID string, amount Amount, reason string, idempotencyKey string) error + GetBalance(ctx context.Context, billingRef, currency string) (Amount, error) + AvailableBalance(ctx context.Context, billingRef, currency string) (Amount, error) + GetQuota(ctx context.Context, billingRef string) (int64, error) } ``` ---- +The following list describes each method: -## Production Implementation: DynamoDB +- `EnsureAgentAccount` opens the ledger account for a `billing_ref`, and leaves an existing account unchanged. The Exchange calls it on the first `Register`. +- `Credit` adds funds outside any purchase. The first credit with a given key wins. The Exchange calls it on the first `Register`, for the welcome credit. +- `Authorize` reserves the charge and returns a `billing_id`. The Exchange calls it for each paid item of a purchase. +- `Record` confirms the reservation. The settled amount is the reserved amount, and the quantity is for information only. The Exchange calls it after it commits the purchase. +- `Release` cancels a reservation that was not consumed. The Exchange calls it when a purchase fails after `Authorize`. +- `Refund` reverses a recorded charge, in part or in full. +- `GetBalance` returns the settled balance in one currency. +- `AvailableBalance` returns what the account can spend in one currency: credits, minus charges, minus open reservations. `GetAccountStatus` calls it to fill `balances`. +- `GetQuota` returns the remaining unit quota. -For AWS deployments, wrapping DynamoDB with consistent reads: +The Exchange treats each adapter call as one atomic operation, and does not retry it. Each adapter handles its own idempotency: a repeated call with the same key has no further effect. The shared test `TestAdapterConformance` defines the behavior that every adapter that holds balances must have. -```go -// DynamoDBBillingAdapter implements BillingAdapter using DynamoDB. -// Table schema: -// PK: "BUYER#" SK: "BALANCE" → {available, currency, credit_limit} -// PK: "BUYER#" SK: "TXN#" → {billing_id, amount, ...} -// PK: "HOLD#" SK: "HOLD" → {amount, requester, created_at} -// -// Uses DynamoDB transactions for atomic balance deduction + hold creation. -type DynamoDBBillingAdapter struct { - client *dynamodb.Client - table string -} -``` +## Ledgers ---- - -## Real Integration Example - -An Exchange operator that already runs a billing system implements the interface against it: - -```go -// ExampleBillingAdapter connects to the operator's internal billing API. -type ExampleBillingAdapter struct { - httpClient *http.Client - baseURL string - apiKey string -} +FORA Server includes the following ledgers, and `FORA_BILLING_ADAPTER` selects one of them: -func (a *ExampleBillingAdapter) Authorize( - ctx context.Context, req *BillingAuthorizeRequest, -) (*BillingAuthorizeResponse, error) { - // Call the operator's internal billing API - billReq := &billing.AuthorizeRequest{ - AccountID: mapBillingRefToAccount(req.BillingRef), - Amount: req.Amount, - Currency: req.Currency, - Product: "content-licensing", - Reference: req.OfferID, - } - billResp, err := a.billing.Authorize(ctx, billReq) - if err != nil { - return nil, fmt.Errorf("billing: %w", err) - } - return &BillingAuthorizeResponse{ - Approved: billResp.Status == "approved", - BillingID: billResp.HoldID, - Reason: billResp.DeclineReason, - }, nil -} -``` +- `free` (default) approves every charge and records nothing. It reports no balance, so `GetAccountStatus` returns none. The transaction log is the only record of a sale. +- `inmemory` keeps prepaid balances in process memory, in USD only. `EXCHANGE_BILLING_SEED` sets the starting balances. A restart loses every balance. +- `tigerbeetle` keeps prepaid balances in a [TigerBeetle](https://github.com/tigerbeetle/tigerbeetle) cluster, with one ledger for each currency in `EXCHANGE_BILLING_LEDGER`. It supports EUR and USD. -This is where the consulting value lives: building custom `BillingAdapter` implementations for real Exchange operators. +If the value is unknown, the Exchange logs a warning and uses `free`. If `tigerbeetle` is selected and the Exchange cannot reach the ledger at boot, the Exchange does not start. The [billing section of the configuration reference](https://github.com/FORA-Protocol/reference-implementation/blob/main/src/exchange/CONFIGURATION.md#25-billing) lists every billing variable, with its format and its default. ---- +With `tigerbeetle`, a charge is a two-phase transfer. `Authorize` creates a pending transfer from the agent's account, `Record` posts it, and `Release` voids it. A pending transfer that nobody posts or voids expires by itself, and the funds return to the agent. The timeout is the delivery URL's lifetime (5 minutes) plus `EXCHANGE_BILLING_HOLD_GRACE` (1 minute by default). -## Dispute Credits (v1.0) +The adapter interface is internal to FORA Server, so the Exchange has no plug-ins. Another ledger is another implementation of `billing.Adapter` in the source code, wired as a new `FORA_BILLING_ADAPTER` value. The wiring also names the currencies that the ledger bills in. Run the shared test `TestAdapterConformance` against the new adapter. An adapter whose ledger keeps a settlement history can also implement `RevenueReporter`, which serves the revenue totals (see [Fees and publisher revenue](#fees-and-publisher-revenue)). -When the Exchange's dispute resolution engine resolves a dispute in the agent's favor (`RESOLUTION_TYPE_CREDIT`), the billing adapter must process a credit. The `BillingAdapter` interface does not include an explicit `Credit` method -- credits are applied through the existing `Record` flow with a negative amount, or through operator-specific credit mechanisms. +## Currencies -For in-memory and DynamoDB implementations, credits are applied by adding the disputed amount back to the requester's balance. For production integrations, credits follow the operator's standard credit/refund workflow. +Each offer states its price in one currency, and the Exchange charges the item in that currency. The Exchange converts nothing between currencies. ---- +With `tigerbeetle`, each agent has one balance for each currency that the ledger bills in. The ledger takes a charge from the balance in the offer's currency, and `GetAccountStatus` returns the available balance in each currency. -## Pricing Computation +With `inmemory` or `tigerbeetle`, the ledger refuses an item whose offer is priced in a currency that it does not bill in. -### Pricing Priority +## Identifiers -Pricing resolution follows a priority chain. The Exchange is the price authority: +- **`billing_ref`** is the agent's account. The Exchange creates it on the agent's first `Register`, and returns it in `RegisterResponse`. The Exchange stores it with the agent. The Exchange always reads it from there, by the identity that the request signature proves, and never from the request body. +- **`billing_id`** identifies the reservation that `Authorize` returns for one item. It does not identify the account. The Exchange returns it on the item's `TransactionResultItem`, and stores it with the transaction. `Record`, `Release`, `Refund`, and the agent's usage report use it. A `billing_id` repeats only for a retry of the same reservation. A free item has no reservation and no `billing_id`. +- **`transaction_id`** identifies one purchased item. The Exchange creates it, and does not pass it to the adapter. +- **The idempotency key** for an item is the request's `idempotency_key`, a colon, and the item's `offer_id`. `Authorize`, `Record`, and `Release` for that item use the same key, so a retried purchase never reserves or settles twice. +- **The payee** is the `resource_owner_id` of the resource's catalog entry, as the publisher's site attests it. -```go -// resolvePrice returns pricing for a content path. -// Priority: Exchange config overrides > catalog pricing (from RSL/ingestion) > tenant defaults. -// RSL pricing is a fallback hint; the Exchange is the price authority. -func (tc *TenantCatalog) resolvePrice(path string) *forav1.Pricing { - // 1. Check Exchange config overrides (price authority) - if pricing, ok := tc.PricingOverrides[path]; ok { - return pricing - } - // 2. Check catalog pricing from ingestion (RSL-derived, fallback hint) - if pricing, ok := tc.URIIndex.Get(path); ok { - return pricing.Pricing - } - // 3. Fall back to tenant config defaults - return tc.DefaultPricing -} -``` +## Charging flow -The Exchange operator sets tenant-level defaults (e.g., "$0.05 per article for all content on style.example") during tenant onboarding. Providers who want path-level pricing control publish an RSL license. +For each item of an `ExecuteTransaction`, the Exchange first verifies the offer and the agent's acceptance. Then it charges the item in the following steps: -### Pricing Models +1. **Fee rate.** The Exchange reads its fee rate for the item's publisher, `fee_rate_bps` on the seat. +2. **Price.** The Exchange reads the price from the signed offer. The unit cost is the offer's `unit_cost`, or its `rate` when `unit_cost` is not set. The quantity is the offer's `estimated_quantity`, or 1 when the offer states none. +3. **Free items.** When the unit cost is 0, the item skips billing, even when the offer's `rate` is not 0. The Exchange calls neither `Authorize` nor `Record`, and the item has no `billing_id`. +4. **Account.** A paid item needs a registered account. Otherwise, the Exchange denies the item with `DENIAL_REASON_ACCOUNT_NOT_REGISTERED`. If the account registry marks the account inactive, the Exchange denies the item with `DENIAL_REASON_ACCOUNT_INACTIVE`. +5. **Reservation.** `Authorize` reserves the unit cost × the quantity, in the offer's currency, with the payee and the fee rate. If the ledger refuses, the Exchange denies the item with `DENIAL_REASON_INSUFFICIENT_BALANCE`. +6. **Delivery.** The Exchange signs the delivery URL and commits the transaction. If either step fails, the Exchange calls `Release`. +7. **Settlement.** After the commit, `Record` confirms the reservation. With `tigerbeetle`, the ledger splits the charge at this point between the operator and the publisher (see [Fees and publisher revenue](#fees-and-publisher-revenue)). -`PricingModel` is the charging structure only. The metering basis ("per what") is the open `Pricing.unit` vocabulary (tokens, pages, accesses, records, ...), not a pricing model. Attribution and contribution are `Obligation`s, not pricing models. Subscriptions are expressed via delegation/scopes (offers come back FREE), not a pricing model. +The item's `cost` in the response is the same unit cost × quantity. -| Pricing Model | Billing Basis | Charge | -|---|---|---| -| `per_unit` | Price per metering unit; the unit (tokens, pages, accesses, records, minutes, ...) comes from `Pricing.unit` | The offer's estimate × rate, or one unit's rate when the offer states no estimate. Final | -| `flat` | Fixed price per transaction, independent of quantity | The rate. Final | -| `free` | No charge | Not applicable | +`ReportUsage` moves no money, because the charge is final at purchase. `Register` calls `EnsureAgentAccount`. For an active account, `Register` then calls `Credit` once for each currency in `EXCHANGE_DEFAULT_AGENT_CREDIT`. -The estimate a metered offer carries (`Pricing.estimated_quantity`) is the publisher's own, stated in the price's `unit` on the term's pricing or once on `ResourceEntry.estimated_quantity`, and the Exchange carries it onto the offer unchanged. It is never computed by the Exchange, and a usage report never changes the charge: it records the quantity consumed, and a disagreement about that quantity is a dispute. See [Charging a metered purchase](/protocol/transaction-flow/#charging-a-metered-purchase). +## Free and subscription items ---- +A free item is still a purchase. The Exchange skips the ledger, but it signs the delivery URL and writes the transaction as for a paid item. A free item needs no account. The agent still owes a usage report unless the price's metering is `PRICING_METERING_NONE`, and a report on a free item carries no `billing_id`. -## Unit Cost Normalization +A subscription uses this path. In the protocol, a subscription is a free license term behind a concrete subscription scope, and the agent pays for the subscription itself outside the protocol. The Exchange sells such a term only when the request's delegation verifies, and the purchase never reaches the ledger. See [Subscription Billing](/getting-started/how-money-flows/#subscription-billing). -DiscoverResources includes `unit_cost` in each offer so AI agents can compare offers across pricing models: the price of one purchase divided by the resource's size in the comparison unit of its content type (tokens for text, seconds for audio and video, pages for documents, records for data). See [unit_cost: Normalized Pricing](/getting-started/how-money-flows/#unit_cost-normalized-pricing). The size is computed from content metadata. It is a comparison input only: it is not `estimated_quantity`, which is the publisher's estimate in the price's own unit, and it never enters a charge. +## Fees and publisher revenue -### Size Formula +The operator's fee is `fee_rate_bps`, in basis points of the charge. The operator sets it with `AdminService.SetTenantFeeRate` on the admin listener. The value is from 0 to 9999, so 1500 is 15%. The rate applies immediately, without a restart. A reservation keeps the rate that was in effect when the Exchange made the reservation. -``` -estimated_tokens = word_count x 1.32 (text, sized in tokens) -``` +With `tigerbeetle`, the ledger splits each charge when `Record` confirms it. The fee is the charge × `fee_rate_bps` / 10000, rounded down, and it goes to the operator's fee account. The rest goes to the publisher's revenue account. The `free` and `inmemory` ledgers do not split. -The 1.32 multiplier is derived from empirical analysis of English-language content across common tokenizers (BPE-based: GPT-4, Claude). For non-English content, the multiplier may differ; tenant config can override. +The publisher console, when the operator runs one, reads a publisher's revenue totals from the Exchange. The totals show the gross, the fee, and the net for a period, in one currency. The totals come from the same ledger that settled the charges, so only `tigerbeetle` reports them. The `free` ledger has no settlements to report, and the `inmemory` ledger keeps no settlement history. -### Data Source +The ledger only records what each publisher earned. Paying the publisher is outside the protocol (see [How Money Flows](/getting-started/how-money-flows/)). -`word_count` comes from RSL content metadata or sitemap `` extensions. If unavailable, the Exchange estimates it from content length: `word_count ~ content_length_bytes / 5.5`. For other comparison units (seconds, pages, records), the size is derived from content metadata specific to that unit type. +## Failure handling -### Subscription Content and Unit Cost +An adapter reports a refusal in one of two ways: -For subscription-based access (RSL payment type="subscription"), unit_cost is computed retrospectively: -- Offer-time estimate: subscription_price / estimated_monthly_consumed_quantity -- Actual: subscription_price / total_consumed_quantity_in_period -- The Exchange computes the estimate from historical usage or provider catalog size +- A soft refusal is `Approved = false` from `Authorize`, for example for an insufficient balance or an unknown account. The Exchange denies the item in the response body with `DENIAL_REASON_INSUFFICIENT_BALANCE`, whatever the reason. The other items of the request continue. +- Every other failure is an error value. An error for an insufficient balance denies only the item, like a soft refusal. Any other error fails the whole request. ---- +The Exchange does not retry an adapter call. When the Exchange cannot reach the ledger, `/readyz` answers `503`, and `/healthz` stays `200`. -## Subscription Handling +`Record` is best effort. When `Record` fails, the purchase still succeeds, and the Exchange logs `billing_record_failed_best_effort`. The charge is then not settled, and nothing repairs it automatically. With `tigerbeetle`, the reservation expires, and the agent is not charged. The Exchange logs a failed `Release` as `release_hold_failed`. With `tigerbeetle`, that reservation also expires. To find charges that are not settled, see the [troubleshooting section of the runbook](https://github.com/FORA-Protocol/reference-implementation/blob/main/src/exchange/RUNBOOK.md#3-troubleshooting). -When a requester has an active subscription with a tenant: - -1. **DiscoverResources** includes subscription offer variants (rate=0) alongside regular offers for each catalog entry. Quota enforcement is deferred to ExecuteTransaction time. -2. **ExecuteTransaction** skips billing authorization for subscription offers. The transaction log, signed URL, and reporting obligation are still created (subscription offers still require mandatory usage reporting). -3. **Financial attribution**: Subscription transactions include `subscription_unit_value` on the response for ASC 606 prepaid drawdown accounting. This represents the per-request rate the content would cost outside the subscription. - ---- - -## Currency Model (v1) - -v1 Exchange operates in a **single currency** per deployment. All offers returned by DiscoverResources are denominated in that currency. No conversion logic is needed. The currency is declared via `base_currency` in the Exchange Manifest (`/.well-known/fora.json`), enabling Brokers to perform cross-exchange price comparison. - -```go -// ExchangeConfig includes the deployment currency. -type ExchangeConfig struct { - // ... - Currency string // ISO 4217 — e.g., "USD". All offers use this currency. - // Published as base_currency in WellKnownManifest (role=ROLE_EXCHANGE). -} -``` - -**Rationale**: Cross-currency support adds exchange rate management, settlement timing risk, and display complexity. None of this is needed for v1, where the Exchange operator sets a single operating currency. - -**v2 scope**: Cross-currency conversion (requester pays in EUR, provider settles in USD) is a v2 feature. It requires exchange rate feeds, conversion at transaction time, and currency-aware reconciliation. - ---- - -## Revenue Tracking - -Each tenant configuration includes a revenue share percentage: - -```go -// Revenue share (not protocol-relevant, but needed for billing) -RevenueSharePct float64 // Provider's share (e.g., 0.85 = 85%) -``` - -Revenue tracking and reconciliation are handled through the transaction log. The `BillingRecordRequest` includes all fields needed for settlement: `BillingID`, `TransactionID`, `Amount`, `Currency`, `TenantID`, `BillingRef`, `ContentURI`, and `Timestamp`. - ---- - -## Error Hierarchy - -All billing errors use Go sentinel error patterns with `errors.Is` / `errors.As` unwrapping. String-based error returns are prohibited. - -```go -var ( - ErrBilling = errors.New("billing") - ErrBillingTimeout = fmt.Errorf("%w: timeout", ErrBilling) - ErrBillingDenied = fmt.Errorf("%w: denied", ErrBilling) - ErrBillingBalance = fmt.Errorf("%w: insufficient balance", ErrBillingDenied) -) -``` - -### Mapping to Connect-Go Status Codes - -```go -func billingErrToConnect(err error) *connect.Error { - switch { - case errors.Is(err, ErrBillingBalance): - return connect.NewError(connect.CodeResourceExhausted, err) - case errors.Is(err, ErrBillingTimeout): - return connect.NewError(connect.CodeUnavailable, err) - case errors.Is(err, ErrBillingDenied): - return connect.NewError(connect.CodePermissionDenied, err) - case errors.Is(err, ErrBilling): - return connect.NewError(connect.CodeInternal, err) - default: - return connect.NewError(connect.CodeUnknown, err) - } -} -``` - -| Sentinel Error | Connect Code | HTTP Status | -|---|---|---| -| `ErrBillingBalance` | `CodeResourceExhausted` | 429 | -| `ErrBillingTimeout` | `CodeUnavailable` | 503 | -| `ErrBillingDenied` | `CodePermissionDenied` | 403 | - -All billing errors MUST be logged via `slog.Error` with structured key-value pairs before returning the Connect error. - ---- - -## Billing Adapter Timeout Handling - -**Scenario**: Billing Authorize call exceeds the 30ms timeout. - -**Policy options** (configurable per deployment): - -| Policy | Behavior | Risk | When to Use | -|---|---|---|---| -| **Reject** (default) | Return `CodeUnavailable` to agent | Lost revenue | High-value content, strict accounting | -| **Deferred** | Authorize optimistically, record for later settlement | Potential bad debt | Low-value content, trusted requesters | - -```go -// BillingTimeoutPolicy determines behavior when billing adapter times out. -type BillingTimeoutPolicy int - -const ( - BillingTimeoutReject BillingTimeoutPolicy = iota // Safe: reject transaction - BillingTimeoutDefer // Risky: allow with deferred billing -) -``` +## Related pages -For deferred mode, the transaction is logged with `billing_status: "deferred"` and a background reconciliation goroutine retries authorization when the billing system recovers. The signed URL is still issued, but the financial record is marked as unconfirmed. +- [Exchange](/components/exchange/overview/): what the Exchange serves, and how a purchase works +- [How Money Flows](/getting-started/how-money-flows/): who pays whom, and where settlement happens +- [Transaction Flow](/protocol/transaction-flow/): discovery, purchase, and usage reports in the protocol diff --git a/website/src/content/docs/components/exchange/configuration.mdx b/website/src/content/docs/components/exchange/configuration.mdx deleted file mode 100644 index 0f95b0e0..00000000 --- a/website/src/content/docs/components/exchange/configuration.mdx +++ /dev/null @@ -1,276 +0,0 @@ ---- -title: "Configuration" -description: "Environment variables, config file structure, secrets management, hot reload, and deployment procedures for the Exchange Node." ---- - -## Configuration Sources - -Three-tier configuration with precedence: environment variables > config file > defaults. - -| Setting | Source | Hot Reload? | Example | -|---|---|---|---| -| Listen address | Env var | No (restart) | `EXCHANGE_LISTEN_ADDR=:8080` | -| Exchange domain | Env var | No | `EXCHANGE_DOMAIN=exchange.example` | -| TLS cert/key | Env var / file | No | `EXCHANGE_TLS_CERT=/etc/tls/cert.pem` | -| Tenant configs | Config file (YAML/JSON) | Yes (SIGHUP) | `EXCHANGE_CONFIG=/etc/exchange/config.yaml` | -| Signing keys | Secrets manager | Yes (polled) | `EXCHANGE_SECRETS_PROVIDER=aws-sm` | -| Billing adapter endpoint | Config file | Yes (SIGHUP) | In tenant config | -| Log level | Env var | Yes (signal) | `EXCHANGE_LOG_LEVEL=info` | -| WAL directory | Env var | No | `EXCHANGE_WAL_DIR=/var/lib/exchange/wal` | -| Transaction store DSN | Env var | No | `EXCHANGE_TXN_STORE_DSN=kafka://...` | - ---- - -## Config File Structure - -```yaml -# /etc/exchange/config.yaml -exchange: - domain: "exchange.example" - version: "1.0" - -billing: - adapter: "dynamodb" # or "http", "in-memory" - endpoint: "https://billing.internal.example/v1" - timeout: "30ms" - timeout_policy: "reject" # or "defer" - -transaction_log: - store: "kafka" - kafka: - brokers: ["kafka-1:9092", "kafka-2:9092"] - topic: "exchange-transactions" - wal: - dir: "/var/lib/exchange/wal" - max_bytes: 1073741824 # 1 GB - flush_interval: "50ms" - flush_batch_size: 100 - -tenants: - - id: "meridian-media" - domains: - - "style.example" - - "outdoors.example" - - "home.example" - rsl_urls: - style.example: "https://style.example/license.xml" - outdoors.example: "https://outdoors.example/license.xml" - home.example: "https://home.example/license.xml" - rsl_poll_interval: "5m" - content_base_url: "https://cdn.meridian.example" - cdn_type: "cloudfront" - signing_key_ref: "arn:aws:secretsmanager:us-east-1:123456:secret:meridian-signing-key" - url_ttl_seconds: 300 - bind_agent_id: true - reporting: # Tenant-level default — inherited by all offers - required: true - window: "86400s" - required_fields: ["transaction_id", "function", "consumed_quantity"] - abuse_thresholds: - min_query_to_txn_ratio: 0.01 # Application-level only; volumetric limiting at infra - catalog_contributors: # v1.0: authorized third-party push sources - - domain: "doubleverify.com" - relationship: "verifier" - verifier_trust: # v1.0: trusted attestation verifiers - cache_ttl: "1h" - trusted_verifiers: - - "doubleverify.com" - - "gumgum.com" - dispute_thresholds: # v1.0: per-tenant dispute policy - auto_credit_max_amount: 0.50 # Max auto-credit per dispute (USD) - agent_dispute_rate_warning: 0.03 # 3% warning threshold - agent_dispute_rate_block: 0.05 # 5% blocking threshold - - - id: "news-example" - domains: ["news.example"] - rsl_urls: - news.example: "https://news.example/license.xml" - # ... -``` - ---- - -## Secrets Management - -### Key Storage - -- Keys stored encrypted at rest: AWS KMS envelope encryption or HashiCorp Vault transit engine -- Per-tenant key isolation — each tenant's keys are under a separate KMS key or Vault path -- Access audit trail on all key operations - -### Supported Secrets Providers - -| Provider | Config Value | Notes | -|---|---|---| -| AWS Secrets Manager | `aws-sm` | Production recommended for AWS deployments | -| HashiCorp Vault | `vault` | For multi-cloud or on-premises | -| GCP Secret Manager | `gcp-sm` | For GCP deployments | -| Local file | `file` | Development only | - -### Key Reference Format - -The `signing_key_ref` in tenant configuration points to the key's location in the secrets provider: - -```yaml -# AWS Secrets Manager -signing_key_ref: "arn:aws:secretsmanager:us-east-1:123456:secret:meridian-signing-key" - -# HashiCorp Vault -signing_key_ref: "vault://secret/exchange/tenants/meridian-media/signing-key" - -# Local file (development only) -signing_key_ref: "file:///var/lib/exchange/keys/meridian-media.pem" -``` - -Keys are loaded from the secrets provider at startup and cached in memory. A background goroutine polls for rotations every 60 seconds. - ---- - -## Hot Reload - -Tenant configuration changes are reloaded on SIGHUP without restarting the process: - -```go -func (s *Server) watchConfig(ctx context.Context) { - sigCh := make(chan os.Signal, 1) - signal.Notify(sigCh, syscall.SIGHUP) - - for { - select { - case <-ctx.Done(): - return - case <-sigCh: - newCfg, err := LoadConfig(s.configPath) - if err != nil { - slog.Error("config reload failed", slog.Any("error", err)) - continue - } - s.applyConfig(newCfg) // Updates tenant map, triggers RSL re-ingestion - slog.Info("config reloaded", slog.Int("tenants", len(newCfg.Tenants))) - } - } -} -``` - -### What Reloads Without Restart - -| Component | Trigger | Behavior | -|---|---|---| -| Tenant configs | SIGHUP | Tenant map updated, new tenants' RSL ingestion started | -| Signing keys | Background poll (60s) | New key becomes active, old key moves to previous | -| Content catalog | RSL poll interval (default 5m) | Atomic pointer swap of CatalogSnapshot | -| Billing adapter endpoint | SIGHUP | Connection pool updated | -| Log level | SIGHUP or env var | Immediate effect | - -### What Requires Restart - -| Component | Reason | -|---|---| -| Listen address | Bound at startup | -| TLS certificates | Loaded at startup | -| WAL directory | File handles opened at startup | -| Transaction store DSN | Connection established at startup | -| Exchange domain | Used in response construction | - -### Admin API for Catalog Refresh - -Catalog changes (RSL re-ingestion) happen automatically on the poll interval. An explicit re-ingestion can be triggered via the admin API: - -``` -POST /admin/tenants/{tenant_id}/refresh-catalog -``` - ---- - -## Resource Ingestion Pipeline - -Resource ingestion is a background pipeline, separate from request handling. It builds and maintains the resource catalog. - -### Ingestion Tiers - -The tiers size each resource in tokens for `unit_cost`, the comparison metric. That size is never an offer's `estimated_quantity`: an offer carries only the estimate the publisher states, in the price's own unit, and a metered purchase charges that estimate × rate, or one unit's rate without one (see [Charging a metered purchase](/protocol/transaction-flow/#charging-a-metered-purchase)). - -**Tier 1 (best): Provider provides token counts** -- Via RSL word count extension, sitemap XML extension, or CoMP Package.scope.text.wordcount -- Exchange uses directly, no crawling needed - -**Tier 2 (good): Exchange crawls and sizes** -- Crawl URLs from sitemap.xml -- Extract main text using readability algorithm (Mozilla Readability.js equivalent in Go) -- Count words -> size in tokens (wordcount x 1.32) -- Store in catalog, refresh periodically (daily or on provider webhook) - -**Tier 3 (fallback): Tenant-level defaults** -- Provider sets average word count per content type via tenant management API -- "My articles average 2000 words" -> a size of 2640 tokens -- Crude but functional for unit_cost comparison - -### Ingestion Flow - -``` -1. Crawl sitemap.xml for each tenant domain → discover all content URLs -2. Check for an RSL license at each domain → parse pricing, restrictions, terms -3. If no RSL license: fall back to tenant-level defaults from config -4. Build OfferTemplates from merged data (sitemap URLs + RSL pricing + tenant defaults) -5. Atomic pointer swap into CatalogSnapshot -``` - -### Sitemap Extension for FORA - -Providers can add token estimates and content IDs directly in sitemap.xml using XML namespace extensions: - -```xml - - - https://example.com/premium/article.html - 2026-03-14 - 3300 - article-2026-03-14-ai-infra - per_article - 0.05 - - -``` - -XML namespace extensions don't break standard sitemap readers — they ignore unknown namespaces. This is established practice (Google uses image:, video:, news: extensions). - -### CMS API Integration - -For WordPress sites, the Exchange can poll the REST API (`/wp-json/wp/v2/posts`) to discover content with rich metadata (title, excerpt, word count, categories). This provides better token estimates than sitemap-only discovery. CMS integration is optional and configured per-tenant. - -### Pipeline Architecture - -The ingestion pipeline runs as a separate background process (not in the Exchange hot path): -1. Crawl sitemap.xml -> discover content URLs -2. For each URL: check for FORA sitemap extensions -> use if present -3. If no extensions: crawl HTML -> extract text (readability algorithm) -> count words -> estimate tokens -4. Check the RSL license -> merge pricing terms -5. Build catalog entries with token estimates -6. Serialize radix trie to binary file -7. Exchange process loads pre-built binary via atomic pointer swap - -Refresh: daily cron, or on provider webhook notification (POST /admin/refresh-catalog). -Not on the hot path. Never blocks DiscoverResources or ExecuteTransaction. - ---- - -## Error Code Reference - -| Scenario | Sentinel Error | Connect Code | gRPC Code | HTTP Status | -|---|---|---|---|---| -| Invalid request fields | (validation) | `CodeInvalidArgument` | `INVALID_ARGUMENT` | 400 | -| More request signatures than `max_intermediary_hops`, counted before any is verified (no typed reason) | `helpers.ErrTooManyHops` | `CodeResourceExhausted` | `RESOURCE_EXHAUSTED` | 429 | -| Request signature missing, invalid or stale (`request_auth_failure`) | (verify middleware) | `CodeUnauthenticated` | `UNAUTHENTICATED` | 401 | -| Offer signature verification failed | `ErrOfferSignature` | `CodeInvalidArgument` | `INVALID_ARGUMENT` | 400 | -| Offer expired | `ErrOfferExpired` | `CodeNotFound` | `NOT_FOUND` | 404 | -| Billing denied (general) | `ErrBillingDenied` | `CodePermissionDenied` | `PERMISSION_DENIED` | 403 | -| Billing denied (insufficient balance) | `ErrBillingBalance` | `CodeResourceExhausted` | `RESOURCE_EXHAUSTED` | 429 | -| Reporting obligation outstanding | (reporting) | `CodePermissionDenied` | `PERMISSION_DENIED` | 403 | -| Application-level abuse (low query:txn ratio) | (abuse) | `CodeResourceExhausted` | `RESOURCE_EXHAUSTED` | 429 | -| Billing adapter timeout | `ErrBillingTimeout` | `CodeUnavailable` | `UNAVAILABLE` | 503 | -| Transaction log full (WAL capacity) | `ErrTransactionLog` | `CodeUnavailable` | `UNAVAILABLE` | 503 | -| Internal error (signing, catalog) | `ErrTransactionSigning` | `CodeInternal` | `INTERNAL` | 500 | -| Idempotent replay | (none) | Success (cached) | `OK` | 200 | - -Note: Volumetric rate limiting (per-IP, per-tenant RPS) is handled by the infrastructure layer (HAProxy/Envoy/API Gateway) and returns 429 before reaching the Exchange service. diff --git a/website/src/content/docs/components/exchange/health-checks.mdx b/website/src/content/docs/components/exchange/health-checks.mdx deleted file mode 100644 index c891ca45..00000000 --- a/website/src/content/docs/components/exchange/health-checks.mdx +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: "Health Checks" -description: "Three-layer health checking for the FORA Exchange -- gRPC health, HTTP liveness, and HTTP readiness with subsystem health matrix." ---- - -## Three Health Layers - -The Exchange implements three complementary health check mechanisms: - -| Layer | Protocol | Purpose | Consumer | -|---|---|---|---| -| **gRPC Health** | `grpc.health.v1.Health/Check` | Per-service health for gRPC-native probes | Kubernetes gRPC probes, Broker | -| **HTTP Liveness** | `GET /healthz` | Process alive, no external I/O | Kubernetes livenessProbe | -| **HTTP Readiness** | `GET /readyz` | All subsystems ready to serve traffic | Kubernetes readinessProbe, load balancers | - -The gRPC Health layer is the primary probe mechanism for the [Broker](/components/broker/overview/). HTTP endpoints exist for Kubernetes and non-gRPC consumers. All three layers derive status from the same internal subsystem health matrix. - -## Subsystem Health Matrix - -Each subsystem is classified as relevant to liveness, readiness, or both. Background goroutines probe subsystems and cache their status -- health endpoints read cached status only, with no synchronous I/O. - -| Subsystem | Liveness? | Readiness? | Rationale | -|---|---|---|---| -| **Process alive** | Yes | Yes | Base signal | -| **Catalog loaded** | No | Yes | Cannot serve offers without a catalog | -| **Catalog age within threshold** | No | Yes | Stale catalog means ingestion is stuck | -| **WAL writable** | No | Yes | Cannot record transactions | -| **WAL utilization below 90%** | No | Yes | Prevents transaction loss under pressure | -| **Billing adapter reachable** | No | Yes | Cannot authorize purchases | -| **Signing keys loaded** | No | Yes | Cannot sign offers or generate signed URLs | - -### Background Probe Intervals - -| Subsystem | Interval | Mechanism | -|---|---|---| -| Catalog loaded | 5s | Check in-memory catalog pointer | -| Catalog age | 5s | Compare timestamp to 2x poll interval | -| WAL writable | 10s | No-op write attempt | -| WAL utilization | 10s | Size / max capacity | -| Billing adapter | 15s | TCP connect | -| Signing keys | 30s | Check key ring for valid keys | - -## HTTP Endpoints - -### GET /healthz -- Liveness - -Returns `200 OK` with body `ok` if the process is alive. No external I/O, no subsystem checks, no JSON body. - -**Why no external I/O**: Liveness probes that call external services can cause cascading failures. If a dependency slows down, the liveness probe times out, Kubernetes restarts the pod, which increases load on remaining pods, causing more restarts. The `/healthz` endpoint avoids this by checking only that the process can handle HTTP requests. - -### GET /readyz -- Readiness - -Returns `200 OK` with subsystem detail when all readiness subsystems are healthy. Returns `503 Service Unavailable` with detail when any subsystem is unhealthy. - -```json -{ - "ready": true, - "subsystems": [ - {"name": "catalog_loaded", "healthy": true, "message": "2847 entries"}, - {"name": "catalog_age", "healthy": true, "message": "age: 2m14s (max: 10m)"}, - {"name": "wal_writable", "healthy": true, "message": "write latency: 0.4ms"}, - {"name": "wal_utilization", "healthy": true, "message": "42% (limit: 90%)"}, - {"name": "billing_adapter", "healthy": true, "message": "reachable: 1.2ms"}, - {"name": "signing_keys", "healthy": true, "message": "2 active keys"} - ], - "checked_at": "2025-01-15T10:30:01Z" -} -``` - -## Kubernetes Probe Configuration - -```yaml -containers: - - name: exchange - ports: - - containerPort: 8080 - name: grpc - startupProbe: - httpGet: - path: /readyz - port: 8080 - periodSeconds: 10 - failureThreshold: 30 # 5 minutes for first catalog build - readinessProbe: - grpc: - port: 8080 - service: "fora.v1.ExchangeService" - periodSeconds: 10 - failureThreshold: 3 - livenessProbe: - httpGet: - path: /healthz - port: 8080 - periodSeconds: 20 - failureThreshold: 3 # 60s before restart -``` - -| Probe | Type | Rationale | -|---|---|---| -| **startupProbe** | HTTP `/readyz` | First catalog build can take minutes. HTTP gives subsystem detail for debugging slow starts | -| **readinessProbe** | gRPC `fora.v1.ExchangeService` | Once started, use gRPC-native probing. Removes pod from Service endpoints when unhealthy | -| **livenessProbe** | HTTP `/healthz` | Lightweight -- no external I/O. Detects deadlocked processes | - -## Broker Health Probing - -The Broker's Exchange Registry uses `grpc.health.v1.Health/Check` instead of naive HEAD probes. This enables structured routing decisions: - -| Scenario | HEAD Probe | gRPC Health | Broker Action | -|---|---|---|---| -| Catalog stale but billing works | 200 (looks healthy) | NOT_SERVING | Skip for discovery | -| Billing down but catalog fresh | 200 (looks healthy) | NOT_SERVING | Can serve read-only, not transactions | -| Process alive, nothing ready | 200 (looks healthy) | NOT_SERVING | Skip entirely | -| Process dead | Connection refused | Connection refused | Mark unhealthy | - -With HEAD probes, scenarios 1-3 are indistinguishable. With gRPC health, the Broker knows the Exchange is degraded and routes accordingly. - -## Next Steps - -- [Exchange Overview](/components/exchange/overview/) -- full architecture -- [Exchange Manifest](/protocol/exchange-manifest/) -- machine-readable self-description -- [Broker Overview](/components/broker/overview/) -- how the Broker uses health data diff --git a/website/src/content/docs/components/exchange/multi-tenant.mdx b/website/src/content/docs/components/exchange/multi-tenant.mdx deleted file mode 100644 index c6ca78a2..00000000 --- a/website/src/content/docs/components/exchange/multi-tenant.mdx +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: "Multi-Tenant Architecture" -description: "Tenant isolation, provider onboarding, domain-to-tenant mapping, and per-tenant configuration for the Exchange Node." ---- - -## Overview - -A single Exchange Node serves many providers. This is the multi-tenant model — one Exchange operator runs an Exchange that serves 10, 100, or 1000+ providers. Each provider is represented as a "tenant" with isolated configuration, catalog, signing keys, and reporting obligations. - ---- - -## Per-Tenant Configuration - -```go -// TenantConfig holds all provider-specific configuration. -// A tenant represents a provider account (e.g., "Meridian Media") which may -// operate multiple domains (style.example, outdoors.example, home.example, etc.). -// URI resolution uses a domain→tenant lookup map, not offer_id prefix parsing. -type TenantConfig struct { - // Identity - ID string // Unique tenant identifier (e.g., "meridian-media") - Domains []string // All provider domains (e.g., ["style.example", "outdoors.example", "home.example"]) - - // Resource catalog (per-domain RSL discovery) - RSLURLs map[string]string // domain -> RSL URL (e.g., "style.example" -> "https://style.example/license.xml") - RSLPollInterval time.Duration // How often to re-fetch RSL (default: 5m) - - // Content delivery - ContentBaseURL string // CDN base URL (e.g., "https://cdn.meridian.example") - Scheme SigningScheme // ED25519 or AWS_CLOUDFRONT_RSA - SigningKeyRef string // Reference to key in secrets manager - - // Signed URL configuration - URLTTLSeconds int // Default: 300 (5 minutes) - BindAgentID bool // Whether to include agent identity in signed URL - - // Reporting policy - ReportingPolicy *forav1.ReportingObligation - - // Revenue share (not protocol-relevant, but needed for billing) - RevenueSharePct float64 // Provider's share (e.g., 0.85 = 85%) - - // v1.0: Attestation and dispute configuration - CatalogContributors []CatalogContributor // Authorized third-party push sources - VerifierTrustConfig *VerifierTrustConfig // Per-tenant verifier trust settings - DisputeConfig *DisputeConfig // Per-tenant dispute thresholds -} -``` - ---- - -## Tenant Isolation Model - -``` -┌──────────────────────────────────────────────────────┐ -│ Exchange Node │ -│ │ -│ Shared: │ -│ - HTTP server (Connect-Go) │ -│ - Transaction log writer (WAL) │ -│ - Billing adapter connection pool │ -│ - Metrics collector │ -│ │ -│ Per-Tenant (isolated): │ -│ - Resource catalog (in CatalogSnapshot.Tenants) │ -│ - Signing keys (in SigningEngine) │ -│ - RSL ingestion goroutine │ -│ - Reporting obligations │ -│ - Verifier trust configuration (v1.0) │ -│ - Dispute thresholds (v1.0) │ -│ - catalog_contributors authorization (v1.0) │ -│ │ -│ NOT shared across tenants: │ -│ - Signing key material │ -│ - Offer signatures (per-tenant Ed25519 key pair) │ -│ - Content paths │ -│ - Pricing configuration │ -└──────────────────────────────────────────────────────┘ -``` - -### Isolation Guarantees - -- **Data isolation**: No tenant can access another tenant's catalog, keys, or transaction records. Offer signatures are per-tenant (different Ed25519 key pairs). Transaction log records include tenant_id for filtering. -- **Performance isolation**: The Exchange keeps no per-request state, so request volume is limited in front of it, per address or per verified identity, by the load balancer or API gateway. Optional: per-tenant goroutine pools for RSL ingestion. -- **Failure isolation**: An RSL ingestion failure for tenant A does not affect tenant B's catalog. Each tenant's catalog is independently rebuildable. - ---- - -## Domain-to-Tenant Mapping - -**Tenant resolution**: The Exchange resolves tenant from the requested URI(s) in the ResourceQuery. The URI's domain is matched against a domain-to-tenant lookup map. A tenant (e.g., "Meridian Media") maps to many domains (style.example, outdoors.example, etc.). For ExecuteTransaction, the tenant is resolved from the domain embedded in the signed offer token — no offer_id prefix parsing. - -```go -// Resolve tenant from the request's URIs (repeated string uris) -tenantCfg, err := h.tenants.ResolveFromURIs(req.Msg.Uris) - -// Resolve tenant from offer domain (ExecuteTransaction path) -tenantCfg, err := h.tenants.ResolveFromDomain(offer.Domain) -``` - ---- - -## Provider Onboarding - -Adding a new provider tenant requires: - -1. Adding a `TenantConfig` entry (config file, API, or database) -2. Uploading the provider's CDN signing key to the secrets manager -3. The provider dropping `fora.json` pointing to this Exchange -4. The Exchange's RSL ingestion goroutine automatically discovers and builds the catalog - -No restart required if hot reload is enabled (see the Configuration page). - ---- - -## Provider Trust Verification - -The Exchange SHOULD periodically re-fetch `/.well-known/fora.json` for each tenant's domains to confirm the provider still authorizes this Exchange to sell their resources. If the Exchange is removed from a provider's `fora.json`: - -- Revoke the tenant configuration -- Stop serving offers for that provider's resources -- Log the revocation for audit - -This is ongoing verification, not just onboarding. Providers can revoke authorization at any time by updating their `fora.json`. The Exchange SHOULD check at least once per hour (configurable via tenant settings). - ---- - -## Key Rotation via Tenant Management API - -Providers who don't operate infrastructure manage signing keys via the Exchange tenant management API. The Exchange operator provides these endpoints as part of the tenant onboarding experience. - -### Key Storage - -- Keys stored encrypted at rest: AWS KMS envelope encryption or HashiCorp Vault transit engine -- Per-tenant key isolation — each tenant's keys are under a separate KMS key or Vault path -- Access audit trail on all key operations - -### Rotation Protocol (API-Driven) - -1. Provider uploads new key via `POST /admin/tenants/{tenant_id}/signing-keys` -2. Exchange stores new key encrypted, marks as `pending_activation` -3. Provider configures new key on their CDN (or Exchange manages CDN config for managed providers) -4. Provider activates via `POST /admin/tenants/{tenant_id}/signing-keys/{key_id}/activate` -- new key becomes `ActiveKey`, old key becomes `PreviousKey` -5. Dual-key grace period (configurable, default 1 hour): CDN and Exchange accept signatures from both keys -6. After grace period: `PreviousKey` is archived (retained for audit, not used for signing) - -### Automatic Rotation - -For managed providers, the Exchange supports automatic rotation on a configurable schedule (default: 90 days per NFR). The Exchange generates a new key pair, provisions it on the CDN, and rotates with a dual-key grace period — no provider action required. - ---- - -## Public Key Exchange - -Brokers and agents fetch the Exchange's WBA directory (the JWK Set at `/.well-known/http-message-signatures-directory`) and read its `keys` to verify `Offer.signature` without manual key exchange. The Exchange's offer-signing Ed25519 public keys are inline in that directory as RFC 7517 JWKs, each identified by its RFC 7638 thumbprint (the RFC 9421 `keyid`). - -**Note:** The Exchange's WBA directory keys serve the Exchange's offer-signing keys. Agent keys are separate — they are fetched from the agent's own WBA directory (self-signup) or stored from enterprise registration (out-of-band key exchange). - -Since the default offer signature algorithm is Ed25519, these are **public keys** — the WBA directory does NOT require authentication. Public keys are safe to expose; they can only verify signatures, not create them. - -**WBA directory entries (the Exchange's `keys`):** -```json -// GET /.well-known/http-message-signatures-directory -// Content-Type: application/http-message-signatures-directory+json -{ - "keys": [ - { - "kty": "OKP", - "crv": "Ed25519", - "use": "sig", - "alg": "EdDSA", - "x": "", - "not_before": "2026-03-01T00:00:00Z", - "not_after": "2026-06-01T00:00:00Z" - }, - { - "kty": "OKP", - "crv": "Ed25519", - "use": "sig", - "alg": "EdDSA", - "x": "", - "not_before": "2026-01-01T00:00:00Z", - "not_after": "2026-03-01T00:00:00Z" - } - ] -} -``` - -- Returns current and previous keys (for rotation grace period); each key's validity window is half-open `[not_before, not_after)` -- **No authentication required** — Ed25519 public keys are safe to expose (they can only verify, not sign) -- Brokers SHOULD cache with a TTL of minutes to hours, as the [Caching Contract](/protocol/authentication/#caching-contract) allows, and poll the directory's `revocation_url` every 300 seconds -- On signature verification failure, refresh key cache before retrying -- The `x` field contains the base64url-encoded Ed25519 public key (32 bytes) - ---- - -## CatalogService Authentication - -The Exchange exposes `CatalogService` (PushResources, RemoveResources, RefreshCatalog) for external parties to push resource metadata. Every CatalogService request is authenticated: - -1. **Verify the RFC 9421 HTTP Message Signature**: The request's signer is the pusher. The request is signed with an [RFC 9421 HTTP Message Signature](https://www.rfc-editor.org/rfc/rfc9421) carried in the HTTP headers (`Signature` / `Signature-Input`, with a `Content-Digest` over the body) — there is no in-message caller signature field. The Exchange verifies it against the caller's published Ed25519 key in the caller's WBA directory (the JWK Set at `{caller domain}/.well-known/http-message-signatures-directory`), identified by its RFC 7638 thumbprint (the RFC 9421 `keyid`). Invalid signatures are rejected with `CodeUnauthenticated` and an `ErrorDetail.request_auth_failure` reason: `SIGNATURE_MISSING`, `SIGNATURE_INVALID` or `SIGNATURE_STALE`. - -2. **Check the signer's authorization**: For each entry, the Exchange resolves `/.well-known/fora.json` from the entry's domain and verifies that the signer is that domain's publisher or one of its `catalog_contributors`. Unauthorized tenant access is rejected with `CodePermissionDenied`. The deprecated `caller_id` field is not needed: the caller is whoever signs. - -3. **Caller registration**: CatalogService callers may also be registered out-of-band (admin API or configuration), for example with the domain where the Ed25519 signing key is published (the WBA directory at `{domain}/.well-known/http-message-signatures-directory`), the authorized `tenant_id` set, and a caller type ("cms_plugin", "intelligence_provider", "syndicator"). - -This prevents unauthorized parties from injecting or modifying catalog entries. The same authentication mechanism applies to RemoveResources and RefreshCatalog calls. RemoveResources names each resource by domain and path, as a push does, and the Exchange checks that the signer is authorized for each item's domain exactly as for a push. - -An Exchange implemented on the Go SDK mounts the service through `connectserver.NewCatalogServiceHandler`, which composes the same request-id · verify · validate · error-detail stack as the Exchange and Broker bindings: an unsigned push never reaches the handler, the wire tier (the `ResourceEntry` envelope rules and the `LicenseTerm` rules) refuses a malformed entry before it **on a mount that passes `connectserver.WithValidation(connect.ValidationStrict)`** — that option composes protovalidate and is not the default, so a deployment relying on the boundary rules names it explicitly — and the proven signer is available to the handler from the request context. Steps 2 and 3 above — contributor authorisation and tenant binding — and the ingest-tier term checks (`helpers.ValidateResourceEntry`) are the handler implementation's job. diff --git a/website/src/content/docs/components/exchange/overview.mdx b/website/src/content/docs/components/exchange/overview.mdx index 1eaf6c50..4723d712 100644 --- a/website/src/content/docs/components/exchange/overview.mdx +++ b/website/src/content/docs/components/exchange/overview.mdx @@ -1,173 +1,150 @@ --- -title: "Exchange Overview" -description: "Exchange component that manages resource catalogs, executes transactions, and generates signed URLs for AI resource access." +title: "Exchange" +description: "The FORA Exchange sells access to publishers' content. It holds their catalogs, signs offers, charges the agent's account, returns signed delivery URLs, and takes usage reports." --- -## What the Exchange Does +An AI agent that wants a publisher's content needs a price, license terms, and a way to pay. Each publisher names, in its `fora.json`, the Exchanges that sell its content. An Exchange holds the catalogs and license terms of many publishers, and it answers an agent's query with offers that it signs. When the agent buys, the Exchange charges the agent's account and returns a signed delivery URL. The agent fetches the content with that URL. Afterward, the agent reports to the Exchange how much it used. -The Exchange Node is the core transaction component in the FORA architecture. It is a single Go binary (using Connect-Go for gRPC/HTTP) that acts as the commercial intermediary between AI agents requesting resources and providers offering them. A single Exchange Node serves many providers — one Exchange operator runs an Exchange that serves 10, 100, or 1000+ providers. +The protocol defines what every Exchange does (see [Transaction Flow](/protocol/transaction-flow/) and [Authentication](/protocol/authentication/)). [FORA Server](https://github.com/FORA-Protocol/reference-implementation), the open-source reference implementation, includes an Exchange. -The Exchange implements the FORA v1.0 `ExchangeService` (4 RPCs: `DiscoverResources`, `ExecuteTransaction`, `ReportUsage`, `DisputeTransaction`). +## From publisher to catalog -**NFR targets**: 10K RPS, <100ms p99 ExecuteTransaction, <$0.00005/txn. +The Exchange can sell a publisher's content only after the content is in its catalog. The catalog receives entries only through `CatalogService.PushResources`, which the pushing party signs. The Exchange accepts a push only when all of the following conditions are true: -## Key Responsibilities +- The pusher's signature verifies. +- Each entry's site is registered, and the seat lists that site as active. +- The site's `fora.json` lists the pusher in `catalog_contributors`, and attests the publisher as the resource owner for this Exchange. +- Each entry's license terms pass the SDK's term checks. +- No URL moves from one resource to another. -| Responsibility | Description | -|---|---| -| **Catalog Management** | Maintains an in-memory resource catalog (radix trie) per provider tenant, built from RSL, sitemaps, CMS APIs, and third-party intelligence providers. Scope-based catalog filtering ensures requesters only see resources matching their declared scopes | -| **Pricing** | Computes offer pricing from Exchange config overrides, RSL-derived pricing, and tenant defaults. Includes unit_cost normalization for cross-provider comparison | -| **Transaction Execution** | Stateless offer verification (Ed25519), billing authorization via pluggable adapter, durable transaction logging (write-before-sign invariant). Subscription offers include `SubscriptionQuotaInfo` for proactive quota signaling | -| **Signed URL Generation** | Per-tenant Ed25519 signed URLs, or CloudFront RSA where the CDN verifies natively, with configurable TTL and requester identity binding | -| **Usage Reporting** | Tracks reporting obligations per transaction, enforces compliance rates, blocks non-compliant agents. Returns `report_id` for dispute chain linkage (v1.0) | -| **Attestation Verification (v1.0)** | Verifies `ResourceAttestation` signatures at catalog push time using keys from the verifier's WBA directory (the JWK Set at `/.well-known/http-message-signatures-directory`). Propagates valid attestations to offers | -| **Dispute Resolution (v1.0)** | Accepts `DisputeTransaction` RPCs, auto-resolves disputes using CDN logs and cryptographic evidence (Tier 1), applies rule-based review (Tier 2), and escalates patterns (Tier 3) | -| **[Health Checks](/components/exchange/health-checks/)** | Three-layer health checking: gRPC `grpc.health.v1`, HTTP `/healthz` (liveness), HTTP `/readyz` (readiness). Subsystem health matrix with background probes | -| **[Exchange Manifest](/protocol/exchange-manifest/)** | Machine-readable self-description at `/.well-known/fora.json` (`role=ROLE_EXCHANGE`). Declares endpoints, capabilities, accepted verifiers, `supported_profiles`, and `base_currency`. Enables Broker capability negotiation and cross-exchange price comparison | -| **Streaming Delivery** | Supports `DELIVERY_METHOD_STREAMING` for real-time connections (WebSocket, SSE, HLS). Generates streaming signed URLs with appropriate TTL for long-running sessions | -| **Extension Profiles** | Declares conformance to domain extension profiles (e.g., `fora-news-v1`, `fora-academic-v1`, `fora-legal-v1`) via `supported_profiles` in the manifest. Includes profile-specific ext fields in offers | +Together, these checks mean that only a party that the publisher names in its own `fora.json` can put the publisher's content up for sale. -## Component Architecture +A push is atomic. When one entry fails, the Exchange stores nothing and answers `invalid_argument`, with the failing URLs and their reasons in the error message. The Exchange stores the attestations that a push carries, and returns them on offers without verifying their signatures. -The Exchange Node has five internal modules. Each module owns a distinct responsibility. Modules communicate via Go interfaces — no internal RPC, no message queues, no shared mutable state between modules. Identity verification uses the `Requester` model (Ed25519 domain-bound keys) with optional delegation (JWT) and verification of the RFC 9421 HTTP Message Signature of whichever party sent the request, the agent or a Broker. +FORA Server includes two pushers. `fora-import`, in the Exchange image, imports the sitemap of each active site listing, with the terms that the publisher chose. `fora-ingest` pushes a JSON Lines feed. See [Run the ingestion pipeline](https://github.com/FORA-Protocol/reference-implementation/blob/main/src/exchange/RUNBOOK.md#run-the-ingestion-pipeline) and [Automatic catalog import](https://github.com/FORA-Protocol/reference-implementation/blob/main/src/exchange/RUNBOOK.md#automatic-catalog-import) in the runbook. -``` -┌──────────────────────────────────────────────────────────────────┐ -│ Exchange Node (Go binary) │ -│ │ -│ ┌────────────────┐ ┌────────────────────┐ ┌──────────────┐ │ -│ │ Supply │ │ Transaction │ │ Signing │ │ -│ │ Discovery │ │ Engine │ │ Engine │ │ -│ │ │ │ │ │ │ │ -│ │ - Catalog │ │ - Idempotency │ │ - Per-tenant │ │ -│ │ (in-memory) │ │ - Billing authz │ │ keys │ │ -│ │ - Offer build │ │ - Txn log write │ │ - CDN-aware │ │ -│ │ - URI matching │ │ - Signed URL issue │ │ signing │ │ -│ └───────┬────────┘ └────────┬───────────┘ └──────┬───────┘ │ -│ │ │ │ │ -│ ┌───────┴────────┐ ┌───────┴───────────┐ │ -│ │ RSL │ │ Reporting │ │ -│ │ Ingestion │ │ Tracker │ │ -│ │ │ │ │ │ -│ │ - Crawl + parse│ │ - Obligation FSM │ │ -│ │ - Diff detect │ │ - Enforcement │ │ -│ │ - Catalog push │ │ - Compliance log │ │ -│ └────────────────┘ └───────────────────┘ │ -│ │ -│ │ │ │ -│ ▼ ▼ │ -│ ┌──────────────────────────────────────────────────────────────┐│ -│ │ Billing Adapter (pluggable interface) ││ -│ └──────────────────────────────────────────────────────────────┘│ -└──────────────────────────────────────────────────────────────────┘ -``` - -## Module Summary +## Discovery and offers -| Module | In-Memory | External I/O | Hot Path? | -|---|---|---|---| -| **Supply Discovery** | Resource catalog (radix trie), offer templates | None (reads from in-memory catalog) | Yes — DiscoverResources | -| **Transaction Engine** | Idempotency cache (LRU) | Billing Adapter, Transaction Log Store | Yes — ExecuteTransaction | -| **Signing Engine** | Per-tenant signing keys | None (all in-process) | Yes — ExecuteTransaction | -| **Reporting Tracker** | Obligation state machine (in-memory + durable) | Transaction Log Store (for obligation records) | Moderate — ReportUsage | -| **RSL Ingestion** | Parsed RSL documents | HTTP fetch to provider domains | No — background goroutine | +An agent asks for offers with `DiscoverResources`, which carries a `ResourceQuery` with the URLs that the agent wants. Discovery reads no account and changes no data, so an agent can ask before it registers. -## Module Interaction Rules +1. **The Exchange finds the entry.** For each URL, the Exchange finds the catalog entry with the longest matching prefix. For a URL with no entry, it returns an `OfferGroup` with `OFFER_ABSENCE_REASON_NOT_IN_CATALOG`. +2. **The Exchange picks the terms that the requester can see.** It shows a normal term when the requester's stated `scopes` cover that term. It shows a subscription term only when the request carries a delegation that verifies, and the key that signed the request holds that delegation. On a query that the Broker originates, it hides subscription terms. See [Scope Matching](/protocol/authentication/#scope-matching). +3. **The Exchange hides what the requester cannot see.** For a resource whose terms the requester cannot see, the Exchange returns an empty `OfferGroup` with no reason. This answer is the same as the answer for a resource with nothing to offer, so it does not reveal that hidden terms exist. +4. **The Exchange signs each offer.** Each offer has a random `offer_id`, the price from its license term, and an expiry 5 minutes later. The Exchange signs the whole offer with its Ed25519 key, so nobody between the Exchange and the agent can change the price or the terms. +5. **The agent gets offer groups.** The response holds one `OfferGroup` for each URL. -1. **Supply Discovery** is read-only on the hot path. The ingestion pipeline serializes the trie to a binary file; the Exchange loads the pre-built binary via atomic pointer swap (see Concurrency Model). -2. **Transaction Engine** verifies the offer's signature (Ed25519 for offers, stateless — no catalog lookup), then calls the Billing Adapter, then writes to the Transaction Log, then calls the Signing Engine. This is a sequential pipeline — no parallelism within a single transaction. Offers are stateless: no OfferStore, no OfferCache, no ResolveOffer. -3. **Reporting Tracker** is called by the ReportUsage RPC handler. It reads the obligation from the Transaction Log to validate the report, then updates the obligation state. -4. **RSL Ingestion** runs on a configurable interval (default: 5 minutes). It fetches, parses, diffs, and produces a serialized catalog binary that the Exchange loads via atomic pointer swap. Source priority is defined in the Resource Ingestion Pipeline design doc. -5. **Signing Engine** has two subsystems, both asymmetric: (a) Ed25519 for offer signatures, verified by agents and Brokers with the published public key, and (b) delivery-URL signatures, verified by the delivery endpoint — Ed25519 at a code-capable edge, or RSA where CloudFront verifies natively. They differ in which key signs and who verifies, not in the primitive. Both are pure function calls — no external I/O. Keys are loaded at startup and rotated via a background goroutine watching a key store. +## Purchase -## Module Dependency Graph +The agent buys with `ExecuteTransaction`. Each item of the request presents a signed offer and the agent's signed acceptance of that offer. The agent can send the request directly, or through a Broker (see [Buying through the Broker](/components/broker/overview/#buying-through-the-broker)). ```mermaid -graph TD - RPC[Connect-Go RPC Handlers] - SD[Supply Discovery] - TE[Transaction Engine] - SE[Signing Engine] - RT[Reporting Tracker] - RSL[RSL Ingestion] - BA[Billing Adapter Interface] - TXL[Transaction Log / WAL] - SM[Secrets Manager] - IC[Idempotency Cache] - - RPC --> SD - RPC --> TE - RPC --> RT - - TE --> BA - TE --> SE - TE --> TXL - TE --> RT - TE --> IC - - RT --> TXL - - RSL --> SD - - SE --> SM - - style BA fill:#f9f,stroke:#333 - style SM fill:#f9f,stroke:#333 - style TXL fill:#f9f,stroke:#333 +%%{init: {"sequence": {"mirrorActors": false, "width": 110, "actorMargin": 30}}}%% +sequenceDiagram + participant Agent + participant Exchange + participant Ledger + participant DB as Database + + Agent->>Exchange: ExecuteTransaction (items) + Note over Exchange: verifies each offer and acceptance + Exchange->>Ledger: Authorize + Ledger-->>Exchange: billing_id + Note over Exchange: signs the delivery URL + Exchange->>DB: transaction, evidence, obligation (one commit) + Exchange->>Ledger: Record + Exchange-->>Agent: one result per item ``` -Pink nodes are external dependencies. Everything else runs in-process. +1. **The Exchange identifies the agent.** On a direct request, the agent is the owner of the key directory that the request signature names. On a request that the Broker relays, `requester.domain` names the agent, and the agent's signed acceptances prove that identity. See [Direct and relayed requests](/protocol/authentication/#direct-and-relayed-requests). +2. **The Exchange recognizes a retry.** The Exchange stores each agent's `idempotency_key` values, with a digest of the items. For a retry with the same key and the same items, it returns the stored response, so a retry after a lost answer never buys twice. It refuses the same key with other items as `already_exists`. +3. **The Exchange handles each item on its own.** The items are independent. For each item, the Exchange performs the following actions: + 1. Verifies the offer's signature and expiry, and finds the offer's catalog entry by the signed `canonical_url`. + 2. Verifies the agent's `AgentAcceptance`. For a subscription term, it also verifies the delegation. + 3. Refuses the item when the agent has too many overdue usage reports: more than 10, or more than one in five of the reports that are due. + 4. Checks the agent's account, and reserves the charge in the ledger with `Authorize`. An item whose `unit_cost` is 0 skips billing. See [Billing and Ledgers](/components/exchange/billing-adapter/). + 5. Signs the delivery URL. The URL is valid for 5 minutes, and it is bound to the key that the agent's acceptance verifies under. + 6. Writes the transaction, its evidence, and the reporting obligation in one database commit. The evidence is the offer, the signatures, and the URL's hash. + 7. Confirms the charge with `Record`, after the commit. +4. **The agent gets one result per item.** A purchased item carries its delivery URL, its `billing_id`, and its reporting obligation. A refused item carries a `denial_reason`, such as `DENIAL_REASON_INSUFFICIENT_BALANCE`, and the other items continue. The Exchange returns a URL only after it commits the URL's transaction. So every URL that an agent holds has a transaction record behind it. If the Exchange cannot sign a URL or write a transaction, it releases the reservation and fails the whole request. -## How It Fits in the FORA Architecture +A seat can refuse purchases that the Broker relays (`allow_broker_relay`). In that case, the Exchange refuses the whole relayed request with `permission_denied`, and sets `ErrorDetail.transaction_denial` to `DENIAL_REASON_RELAY_NOT_ACCEPTED`. -The Exchange sits between AI agents/Brokers and provider CDN infrastructure: +## After the purchase -1. An AI agent discovers available resources by calling `DiscoverResources` — the Exchange verifies the `Requester` identity (Ed25519 signature over domain-bound key), presents the terms the requester's stated scopes cover, and returns signed offers. If a `Delegation` is present on a query the agent signed, the Exchange verifies the delegation JWT chain — including the **holder-binding** step (the request-signing key MUST hash to the final JWT's `cnf.jkt`; see [Verification](/protocol/authentication/#verification)) — before honouring it. A query that comes through a Broker is one the Broker originated and signed alone; the Exchange counts the signatures against its `max_intermediary_hops` before verifying any, then authenticates the Broker by its signature (see [Multi-hop forwarding](/protocol/authentication/#multi-hop-forwarding)). Nothing on such a query can pass a delegation's holder binding, so the Exchange does not honour one there and answers as if none were present. How an agent proves a holder-of-key entitlement at discovery time through a Broker is an open protocol question. -2. The agent executes a transaction by calling `ExecuteTransaction` with a chosen offer — the Exchange verifies the offer signature, authorizes billing, logs the transaction, and returns a signed URL -3. The agent fetches the resource using the signed URL — the delivery endpoint verifies the URL signature with the Exchange's published public key, holding nothing secret -4. The agent reports usage by calling `ReportUsage` — the Exchange validates the report and updates the obligation state +The agent fetches the content from the publisher's CDN with the delivery URL. The CDN checks the URL's signature before it serves the content (see [Signed URL Verification](/components/edge-function/signed-url-verification/)). -## Key Design Decisions +Then the agent reports how much it used, with `ReportUsage`. A report moves no money, because the charge is final at purchase. The Exchange applies the following rules to a report: -- **Stateless offer verification**: Offers are Ed25519-signed tokens. ExecuteTransaction verifies and decodes the offer from its signature — no offer storage, no offer cache, no re-resolution against the catalog. This eliminates a class of consistency bugs and simplifies horizontal scaling. -- **Write-before-sign invariant**: The transaction log write MUST complete before the Signing Engine generates the signed URL. No signed URL is ever issued for an unrecorded transaction. -- **Two signing subsystems, one primitive**: Ed25519 for offer signatures, verified by agents and Brokers, and Ed25519 for delivery URLs, verified by the delivery endpoint (RSA where CloudFront verifies natively). Both are asymmetric and neither shares a secret; separating them isolates the keys and their audiences, not the algorithms. -- **Pluggable Billing Adapter**: The single point of custom integration per deployment. The open-source Exchange is billing-system-agnostic. -- **Copy-on-write catalog**: The resource catalog uses `atomic.Pointer` for lock-free reads on the hot path. The ingestion pipeline builds a new catalog snapshot in the background and swaps it atomically. -- **Single currency per deployment (v1)**: No cross-currency conversion. The Exchange operator sets a single operating currency. Cross-currency is a v2 feature. +- The report must carry the transaction's `billing_id` and the fields that the seat's reporting policy requires. Its timestamp must not be earlier than the transaction. +- The Exchange refuses a report when its `consumed_quantity` differs from the estimate by more than the quantity tolerance. The reporting policy sets the tolerance, 20% by default. +- The Exchange accepts a report after its reporting window closes. +- If the agent sends an accepted report again, with the same `UsageReport.idempotency_key`, the Exchange returns the same `report_id`. It refuses a second, different report on the same transaction as `failed_precondition`. +- The Exchange refuses a report on another agent's transaction as `permission_denied`. +## Agent accounts -## Key Go Interfaces +Free content needs no account. To buy paid content, the agent calls `Register` once. The Exchange identifies the agent by the key directory that the request signature names, never by the request body. On the first call, the Exchange performs the following actions: -```go -// The five pluggable interfaces that define the Exchange's extension points. +1. Checks the payload against the published registration schema and the accepted terms. +2. Creates the account in the account registry. +3. Opens the agent's ledger account. +4. Grants the welcome credit. +5. Returns a `billing_ref`. -type BillingAdapter interface { - Authorize(ctx context.Context, req *BillingAuthorizeRequest) (*BillingAuthorizeResponse, error) - Record(ctx context.Context, req *BillingRecordRequest) (*BillingRecordResponse, error) - Release(ctx context.Context, billingID string) error - GetBalance(ctx context.Context, billingRef string) (*BillingBalance, error) - CheckSubscription(ctx context.Context, billingRef string, tenantID string) (*SubscriptionStatus, error) -} +Each later call returns the same `billing_ref`. -type OfferSigner interface { - Sign(offer *forav1.Offer) (string, error) - VerifyAndDecode(offerID string, signature string, algorithm string) (*forav1.Offer, error) -} +`GetAccountStatus` returns the `billing_ref`, whether the account is active, the digest of the accepted terms, and the balances. With the default `free` ledger, it reports no balance. For an agent that is not registered, it returns `not_found`. -type Signer interface { - SignURL(ctx context.Context, tenantID string, req SignRequest) (string, error) -} +## Request verification -type TransactionStore interface { - Write(ctx context.Context, record *TransactionRecord) error - WriteBatch(ctx context.Context, records []*TransactionRecord) error - Lookup(ctx context.Context, transactionID string) (*TransactionRecord, error) - LookupByRequestID(ctx context.Context, requestID string) (*TransactionRecord, error) - WriteUsageReport(ctx context.Context, report *UsageReportRecord) error -} +Every call reaches the Exchange as a signed HTTP request. Before the Exchange acts on any call, it checks the request in the following order: -type SecretsProvider interface { - GetSigningKey(ctx context.Context, keyRef string) (*SigningKey, error) - WatchRotation(ctx context.Context, keyRef string, callback func(*SigningKey)) error -} -``` +1. **The message is well formed.** The message must pass the proto's validation rules. +2. **The request is for this Exchange.** The request must name this Exchange in its `exchange` field, so a request signed for another Exchange cannot be used here. Otherwise, the Exchange refuses it as `invalid_argument`. +3. **The request has few enough signatures.** The Exchange refuses a request that has more signatures than `max_intermediary_hops`. It does so before it verifies any signature, so a refusal costs little work. +4. **Each signature verifies.** The Exchange verifies each RFC 9421 signature under the Web Bot Auth profile. It uses the key from the directory that the signature's own `Signature-Agent` names. +5. **The request is not a replay.** The Exchange refuses a signature that it already accepted, so a copied request cannot be sent again. + +The [Authentication](/protocol/authentication/#verification-at-the-exchange) page defines these rules. + +The Exchange admits one Broker, which its operator configures. The Exchange reads that Broker's list of withdrawn keys from the Broker. While the Exchange cannot read the list, it refuses signed requests. + +## What an Exchange never does + +- **Deliver the content.** The publisher's CDN serves the content. The Exchange signs the URL that opens it. +- **Charge for a usage report.** The charge is final at purchase, and a report moves no money. +- **Take the agent's identity from the request body.** The Exchange identifies the agent by the request signature, and reads the agent's `billing_ref` from its own records. +- **Hold the agent's keys.** The agent signs its acceptances, and the Exchange only verifies them. +- **Return a URL before the sale is recorded.** The Exchange commits the transaction first. + +## Who runs an Exchange + +An Exchange operator runs the Exchange and registers the publishers that it sells for. + +FORA Server's Exchange is one Go binary in a container. Its public listener serves the Connect RPCs, the manifest at `/.well-known/fora.json`, and the key directory at `/.well-known/http-message-signatures-directory`. A separate admin listener serves only `AdminService`, behind an IP allowlist. Through `AdminService`, the operator sets the fee rate and the reporting policy, and a change applies immediately. Every other setting is an environment variable, and a change takes effect after a restart. + +**One seat.** One deployment sells as one seat, which is the Exchange's own hostname. The seat holds the operator's settings for every publisher under it. Many publishers, each with its sites, are registered under that seat. + +**Keys.** One Ed25519 key signs the offers and the Ed25519 delivery URLs. Its public key is the only key in the Exchange's key directory. A publisher site that uses the AWS CloudFront signing scheme also needs an RSA key. To rotate a key, replace it and restart the Exchange. The previous key and its replacement are never valid at the same time. See [Rotate the tenant signing key](https://github.com/FORA-Protocol/reference-implementation/blob/main/src/exchange/RUNBOOK.md#rotate-the-tenant-signing-key) in the runbook. + +**Data.** The Exchange keeps its data in the following places: + +- **Main database (PostgreSQL):** The seat, the publishers, their sites and listings, the agents, the catalog, the transaction log, the transaction evidence, the reporting obligations, and the audit log. The database refuses any change to a stored evidence row. +- **Account registry (PostgreSQL, a separate database):** The agents' accounts. +- **Replay cache (Redis):** The signatures that the Exchange already accepted. Without Redis, the Exchange keeps them in its own memory. +- **Ledger (selected by the operator):** Balances and charges. See [Billing and Ledgers](/components/exchange/billing-adapter/). + +The Exchange also keeps the catalog in memory, as a radix trie. At boot and after each accepted push, it rebuilds the trie from PostgreSQL and swaps it in atomically. None of the stores holds the keys. The two PostgreSQL databases hold the durable state, so back up both of them. See [Backup and recovery](https://github.com/FORA-Protocol/reference-implementation/blob/main/src/exchange/RUNBOOK.md#5-backup-and-recovery). + +The FORA Server repository has the full reference: + +- The [configuration reference](https://github.com/FORA-Protocol/reference-implementation/blob/main/src/exchange/CONFIGURATION.md) describes every variable. +- The [deployment guide](https://github.com/FORA-Protocol/reference-implementation/blob/main/src/exchange/DEPLOYMENT.md) covers a first installation. +- The [runbook](https://github.com/FORA-Protocol/reference-implementation/blob/main/src/exchange/RUNBOOK.md) covers monitoring, troubleshooting, and routine procedures. + +## Related pages + +- [FORA for Exchange Operators](/getting-started/for-exchange-operators/): how to set up an Exchange and register publishers +- [Billing and Ledgers](/components/exchange/billing-adapter/): how the Exchange charges an agent's account +- [Broker](/components/broker/overview/): the service that relays queries and purchases to Exchanges +- [Transaction Flow](/protocol/transaction-flow/): discovery, purchase, and usage reports in the protocol +- [Authentication](/protocol/authentication/): request signatures, relayed requests, and accounts diff --git a/website/src/content/docs/components/exchange/request-flows.mdx b/website/src/content/docs/components/exchange/request-flows.mdx deleted file mode 100644 index ffb4855d..00000000 --- a/website/src/content/docs/components/exchange/request-flows.mdx +++ /dev/null @@ -1,969 +0,0 @@ ---- -title: "Request Flows" -description: "Detailed request flow diagrams and implementation for DiscoverResources, ExecuteTransaction, and ReportUsage RPCs." ---- - -## DiscoverResources - -The fastest path. No external I/O. In-memory catalog lookup, offer construction, and response serialization. - -```mermaid -sequenceDiagram - participant Agent as Agent / Broker - participant Handler as ConnectHandler - participant SD as SupplyDiscovery - participant RT as ReportingTracker - - Agent->>Handler: DiscoverResources(ResourceQuery) - - Note over Handler: Validate request (proto validation) - Note over Handler: Reject unless request.exchange names this Exchange's own domain (INVALID_ARGUMENT) - Note over Handler: Count the RFC 9421 signatures against max_intermediary_hops before verifying any (over the cap: RESOURCE_EXHAUSTED) - Note over Handler: Verify the signature of the party that sent the request (Ed25519, key from the directory its Signature-Agent member names) - Note over Handler: Extract tenant from ResourceQuery.uris[0] domain - Note over Handler: (Volumetric rate limiting handled by infra layer — HAProxy/Envoy) - - Handler->>SD: FindOffers(ctx, tenantID, query.uris, requester.scopes) - - Note over SD: Lookup URI(s) in radix trie - Note over SD: Filter catalog by requester.scopes - Note over SD: One Offer per entitled LicenseTerm
(restrictions ride on that offer's term, and the agent chooses an offer, no server-side filter) - Note over SD: Build []Offer from templates + live pricing - - SD-->>Handler: []Offer - - Handler->>RT: GetReportingPolicy(ctx, tenantID) - RT-->>Handler: ReportingObligation (tenant-level default) - - Note over Handler: Attach tenant's ReportingObligation to each Offer
(per-tenant default, rarely overridden per-offer) - Note over Handler: Ed25519-sign every offer (MANDATORY) - Note over Handler: Build ResourceResponse - - Handler-->>Agent: ResourceResponse -``` - -### Handler Implementation - -```go -func (h *ExchangeHandler) DiscoverResources( - ctx context.Context, - req *connect.Request[forav1.ResourceQuery], -) (*connect.Response[forav1.ResourceResponse], error) { - // 1. Validate - if err := validate(req.Msg); err != nil { - return nil, connect.NewError(connect.CodeInvalidArgument, err) - } - - // 1b. Respect deadline field from ResourceQuery. - // If req.Msg.Deadline is set, use it as the context timeout. - // If absent, use a 500ms default timeout for the entire handler. - if req.Msg.Deadline != nil { - var cancel context.CancelFunc - ctx, cancel = context.WithTimeout(ctx, req.Msg.Deadline.AsDuration()) - defer cancel() - } else { - var cancel context.CancelFunc - ctx, cancel = context.WithTimeout(ctx, 500*time.Millisecond) - defer cancel() - } - - // 2. Requester identity. Verification already happened at the HTTP seam: - // the SDK's verify middleware checked the RFC 9421 signature of the - // party that sent the request — the agent, or a Broker that originated - // or re-packaged it (Authentication > Multi-hop forwarding) — resolving the signer's key - // by its signed keyid (an RFC 7638 thumbprint) in the key directory - // named by the `Signature-Agent` member that signature covers. The - // self-asserted Requester.domain field never drives request-signing key - // lookup. - // The handler consumes the proof from the context; it never re-fetches - // keys or re-verifies bytes, and it fails closed when the proof is - // absent (a route the middleware does not guard). - requester := req.Msg.Requester - verified := helpers.FromContext(ctx) // the first verified signature in header order; all of them via helpers.AllSignaturesFromContext - if verified == nil { - return nil, connect.NewError(connect.CodeUnauthenticated, - errors.New("request reached the handler without a verified signature")) - } - - // 2b. Direct or Broker-led ("Direct and relayed requests" in the protocol). - // Requester.domain is the host of the agent's key directory, never a - // free label. When it names the directory the signature resolved from - // (the host of the covered Signature-Agent URL, compared by the - // request-recipient identity rule: case-folded, an absent port the same - // as :443), the query is DIRECT: the agent signed it. When it names - // another directory, the query is one a Broker originated, which this - // Exchange acts on only when it admits the signer as a Broker; there the - // domain is the Broker's statement of whom it queries for, and nothing - // on this leg authenticates the agent. Any other mismatch is a signature - // that verifies, but not for the requester the body names. - host, err := helpers.HostOf(verified.SignatureAgent) - verdict := helpers.AudienceMalformed - if err == nil { - verdict, err = helpers.CheckAudience(host, requester.GetDomain()) - } - direct := err == nil && verdict == helpers.AudienceAccepted - brokerLed := err == nil && verdict == helpers.AudienceMismatch && - h.brokers.Admits(verified.SignatureAgent) - if !direct && !brokerLed { - return nil, connectserver.AttachDetail( - connect.NewError(connect.CodeUnauthenticated, errors.New("requester.domain is not the signing directory")), - helpers.RequestAuthFailureDetail("fora.v1.ExchangeService", "requester.domain is not the signing directory", - forav1.RequestAuthFailureReason_REQUEST_AUTH_FAILURE_REASON_SIGNATURE_INVALID)) - } - - // 2c. On a DIRECT query, resolve the agent's registered account from the - // directory the signature resolved from (verified.SignatureAgent; see - // "Accounts" on the authentication page). Every currently valid key that - // directory publishes acts for the account, so the key that verified - // does not select it, and neither does requester.id, a free label. A - // query a Broker originated authenticates no agent, so this Exchange - // consults no account for it (its own choice; the protocol leaves it - // open) and presents on the stated scopes alone. - var account *Account - if direct { - account, err = h.accounts.ForDirectory(ctx, verified.SignatureAgent) - if err != nil { - return nil, connect.NewError(connect.CodePermissionDenied, err) - } - } - - // 3. Resolve tenant - tenantCfg, err := h.tenants.ResolveFromURIs(req.Msg.Uris) - if err != nil { - return nil, connect.NewError(connect.CodeNotFound, err) - } - - // 3b. Verify the delegation (if present) on a DIRECT query, once per - // subscription record. Trust is per record: the SDK verifier is given - // the keys that record lists, so an issuer trusted for one subscription - // grants nothing on another. A record whose keys refuse the chain keeps - // its gated terms hidden; the refusal is journaled, never reported. The - // holder is the RFC 9421 signer's key from the HTTP proof of step 2, - // which stays separate from the delegation result. On a query a Broker - // originated the Broker signs alone, so nothing can pass the holder - // binding: the delegation is not honoured, and the query is answered - // as if none were present. A token over the size limit never gets - // here: step 1 refused the request. - grants := map[string]*helpers.VerifiedDelegation{} // subscription record ID -> verified grant - if direct && requester.GetDelegation() != nil { - holder, err := helpers.Thumbprint(verified.PublicKey) - if err != nil { - return nil, connect.NewError(connect.CodeInternal, err) - } - for _, record := range h.subscriptions.RecordsForTenant(ctx, tenantCfg.ID) { - grant, err := helpers.VerifyDelegation(helpers.DelegationInput{ - Token: requester.GetDelegation().GetToken(), - TrustedIssuers: record.TrustedIssuers, - Audience: tenantCfg.Identity, - Holder: holder, - Now: h.clock.Now(), - }) - if err != nil { - h.journal.DelegationRefused(ctx, record.ID, err) - continue - } - grants[record.ID] = grant - } - } - - // 4. Application-level abuse check (optional — volumetric rate limiting is at infra layer) - // The Exchange MAY return 429 for application-level abuse, e.g., query-to-transaction - // ratio too low (agent discovering but never buying). Volumetric rate limiting (per-IP, - // per-tenant RPS caps) belongs in HAProxy/Envoy/API Gateway in front of this service. - - // 5. Catalog lookup (lock-free read, scope-filtered) - // A non-gated term is filtered by requester.scopes, the requester's own - // statement — terms outside the stated scopes are not returned. A gated - // term (a subscription term) is presented only when the grant verified - // under the term's own subscription record covers the term's scopes, by - // the one matching rule on Requester.scopes; requester.scopes is ignored - // for it, and a record with no grant — every record on a query a Broker - // originated (3b) — keeps its gated terms hidden, as if they did not - // exist. The catalog bounds each gated offer's expires_at by its grant's - // ExpiresAt, so the offer never outlives the chain. - offers, err := h.catalog.FindOffers(ctx, tenantCfg.ID, req.Msg.Uris, requester.Scopes, grants) - if err != nil { - return nil, connect.NewError(connect.CodeInternal, err) - } - - // 5b. Check for active subscription, on a DIRECT query (step 2d). - // If the requester has an active subscription with this tenant, include a - // subscription offer variant (rate=0) for each catalog offer with - // SubscriptionQuotaInfo attached. Quota enforcement is deferred to - // ExecuteTransaction time — DiscoverResources checks subscription status - // and populates quota visibility. Subscription/entitlement is resolved - // from the registered account of step 2d (plus any delegation) — never - // from the caller-written requester.id. A query a Broker originated has - // no account here, so it gets no subscription variant. - var subStatus *SubscriptionStatus - if account != nil { - if sub, err := h.billing.CheckSubscription(ctx, account.BillingRef, tenantCfg.ID); err == nil && sub.Active { - subStatus = sub - } - } - - // Build subscription offer variants per catalog offer (if subscription active). - // Each subscription offer includes SubscriptionQuotaInfo so agents can see - // remaining quota before committing to a transaction. - if subStatus != nil { - var subOffers []*forav1.Offer - for _, offer := range offers { - subOffer := proto.Clone(offer).(*forav1.Offer) - // A subscription variant is a distinct offer, so it gets a fresh - // opaque offer_id — never one derived from the base offer's id. - subOffer.OfferId = "offer-" + newOpaqueID() - subOffer.SubscriptionId = proto.String(subStatus.SubscriptionID) - subOffer.Pricing = &forav1.Pricing{ - Model: offer.Pricing.Model, - Rate: "0", // zero marginal cost under subscription; money is a decimal string - Currency: offer.Pricing.Currency, - UnitCost: proto.String("0"), - EstimatedQuantity: offer.Pricing.EstimatedQuantity, - } - // Populate SubscriptionQuotaInfo for proactive quota signaling - subOffer.SubscriptionQuota = h.billing.SubscriptionQuota( - ctx, subStatus.SubscriptionID, tenantCfg.ID, - ) - subOffers = append(subOffers, subOffer) - } - offers = append(offers, subOffers...) - } - - // 6. Attach reporting obligations (per-tenant default, not per-offer lookup) - // Reporting obligation is set once in tenant config. All offers inherit the - // tenant's reporting obligation unless explicitly overridden (rare). - tenantReporting := h.reporting.GetPolicy(tenantCfg.ID) - for _, offer := range offers { - offer.Reporting = tenantReporting - } - - // 7. Ed25519-sign every offer (MANDATORY — enables stateless ExecuteTransaction) - // Ed25519 is the default for offers because agents and Brokers must - // verify signatures without holding the signing key. The Exchange signs - // with its Ed25519 private key; anyone verifies with the public key. - for _, offer := range offers { - sig, err := h.offerSigner.Sign(offer) - if err != nil { - return nil, connect.NewError(connect.CodeInternal, err) - } - offer.Signature = sig - offer.SignatureAlgorithm = "EdDSA" - } - - // 8. Build response — flat offers or OfferGroups depending on URI count. - // When the ResourceQuery contains multiple URIs, return OfferGroups - // (one per URI) so the caller knows which offers map to which resource. - // When a single URI is queried, use the flat offers field. - uris := req.Msg.Uris - if len(uris) > 1 { - // Batch mode: group offers by requested URI. - groups := make([]*forav1.OfferGroup, 0, len(uris)) - for _, uri := range uris { - var uriOffers []*forav1.Offer - for _, offer := range offers { - if offerMatchesURI(offer, uri) { - uriOffers = append(uriOffers, offer) - } - } - groups = append(groups, &forav1.OfferGroup{ - Uri: uri, - Offers: uriOffers, // empty slice = resource not available for this URI - }) - } - return connect.NewResponse(&forav1.ResourceResponse{ - Ver: helpers.ProtocolVersion, - Exchange: h.exchangeDomain, - OfferGroups: groups, - }), nil - // Correlation is not echoed in the body: it rides the X-Request-ID - // HTTP header, propagated across the request/response round-trip. - } - - return connect.NewResponse(&forav1.ResourceResponse{ - Ver: helpers.ProtocolVersion, - Exchange: h.exchangeDomain, - Offers: offers, - }), nil -} -``` - -**IAB Content Taxonomy**: When building offers, the DiscoverResources handler includes `iab_categories` from the catalog entry on each Offer. This enables agents and Brokers to filter offers by topic (e.g., "only finance resources"). Categories use IAB Content Taxonomy 3.1 codes and are populated during resource ingestion — either from FORA sitemap extensions, CMS metadata, or third-party intelligence providers via CatalogService. - -**Latency budget**: 10ms p50, 50ms p99. All in-memory. The only variable is offer count and serialization cost. - -### Requester Authentication - -Requester authentication uses an RFC 9421 HTTP Message Signature in the HTTP headers, signed with a domain-bound Ed25519 key and made to the [Web Bot Auth profile](/protocol/authentication/#the-web-bot-auth-profile). The public key is published in the signer's key directory (`{origin}/.well-known/http-message-signatures-directory`); the verifier resolves that origin from the `Signature-Agent` member the signature covers. The `Requester.id` identifies the specific entity within that domain. The requester's private key never leaves the requester. - -**Two onboarding paths:** - -1. **Enterprise (out-of-band key exchange)**: During contract signing, the Exchange operator registers the requester's public key via an internal admin API: `POST /admin/requesters { requester_id, domain, public_key, subscription }`. The public key is exchanged out-of-band (email, portal, API) as part of the commercial agreement. - -2. **Self-signup**: The agent calls `ExchangeService.Register`, signed with a key its WBA directory (the JWK Set at `/.well-known/http-message-signatures-directory`) publishes. The Exchange verifies the signature against that directory, the key identified by its RFC 7638 thumbprint (the RFC 9421 `keyid`), and creates the account for the directory, never for a `requester_id` (see [Accounts](/protocol/authentication/#accounts)). No subscription is created — self-signup requesters use per-request billing only. - -**Requester public key storage:** - -```go -type RequesterRecord struct { - RequesterID string - Domain string - PublicKey ed25519.PublicKey - ManifestURL string // {domain}/.well-known/fora.json - Subscriptions map[string]SubscriptionStatus // tenantID -> status -} -``` - -### Forwarding Verification - -Nothing about the route is carried in the message: there is no `intermediaries` field. Each party that sends a `ResourceQuery` or `TransactionRequest` signs it with **one** labeled signature that conforms to Web Bot Auth, with its own `Signature-Agent` member. The rules are specified once, in [Multi-hop forwarding](/protocol/authentication/#multi-hop-forwarding). In short, FORA's Broker never forwards an agent's request unchanged: - -- **Discovery is Broker-led.** The Broker chooses the Exchanges and originates its own `ResourceQuery`, signed by the Broker alone, so the Exchange does not honour a delegation on it and answers as if none were present ([Which signature binds in a brokered request](/protocol/authentication/#verification)). How an agent proves a holder-of-key entitlement at discovery time through a Broker is an open protocol question. -- **Execute is re-packaged.** The Broker builds a fresh `TransactionRequest` for each Exchange and signs it alone. The agent's identity and consent are the `AgentAcceptance`, a detached Ed25519 signature over `{offer_sig, requester_id, requester_domain, idempotency_key}` verified against the agent's registered key, resolved from `Requester.domain`. - -In both cases the Broker's signature covers its own request components and only its own `Signature-Agent` member, and the request carries no agent signature headers. - -The Exchange MUST: - -1. **Verify the request signature.** The `keyid` is the key's RFC 7638 thumbprint; the Exchange resolves the key in the key directory at `{origin}/.well-known/http-message-signatures-directory`, where `{origin}` is the `Signature-Agent` member the signature covers, verifies the Ed25519 signature, and authenticates the caller as that party: the agent on a direct call, the Broker on a request the Broker sent. A request whose `requester.domain` names a directory other than the signer's is relayed, and the Exchange acts on it only from a Broker it admits, by its own policy (for example, only Brokers registered with it); from any other signer it is refused as `unauthenticated` with `request_auth_failure` `SIGNATURE_INVALID`. See [Direct and relayed requests](/protocol/authentication/#direct-and-relayed-requests). -2. **Verify each item's `AgentAcceptance` on an execute request** against the agent's registered key, as [Projected execute requests](/protocol/authentication/#projected-execute-requests) describes. On a re-packaged request this is the agent's identity and consent, and its key gives the delivery-URL binding and the key a delegation's `cnf.jkt` is checked against. -3. **Where a party forwarded unchanged and covered an earlier signature**, verify that signature too, and the coverage, as the general WG-00 rule describes. - -Every signature on the request must pass. If any one fails, the Exchange rejects the request with `CodeUnauthenticated`. The refusal carries an `ErrorDetail` whose `request_auth_failure` block holds a [`RequestAuthFailureReason`](/reference/proto-fora/#requestauthfailurereason): `SIGNATURE_MISSING` (sign the request), `SIGNATURE_INVALID` (the signature does not verify) or `SIGNATURE_STALE` (sign it again, now). The reason names what the caller does next, never which check failed. - -Before it verifies any signature, the Exchange counts the signatures on the request against its `WellKnownManifest.max_intermediary_hops`, every signature counted whether or not it covers another, and refuses a request carrying more with `CodeResourceExhausted` (HTTP 429) and no typed reason. A request signed only by the party that sent it carries one. `RequestConstraints.max_hops` never reaches an Exchange: it rides only on the agent's `DiscoveryRequest` to the Broker, and no party enforces it in this version. - -```go -// Request-signature verification runs in the SDK's verify middleware at the -// HTTP seam, before any handler. The middleware: -// 1. Parses the Signature / Signature-Input headers into labeled signatures. -// 2. Counts them against max_intermediary_hops before verifying any -// (connectserver.WithMaxSignatures). A request carrying more is refused -// with CodeResourceExhausted (HTTP 429) and no ErrorDetail. -// 3. Verifies the request signature against the key in the directory its -// own Signature-Agent member names, at -// {origin}/.well-known/http-message-signatures-directory. -// 4. Where a party forwarded unchanged and covered an earlier signature, -// verifies that signature and the coverage too. -// A signature that fails rejects the request with CodeUnauthenticated before -// the handler runs, carrying ErrorDetail.request_auth_failure -// (SIGNATURE_MISSING, SIGNATURE_INVALID or SIGNATURE_STALE). The handler reads -// the proven signatures from the context, in header order: -sigs := helpers.AllSignaturesFromContext(ctx) -``` - -### Delegation Verification - -When `Requester.delegation` is present, the Exchange runs the chain through the profile's verifier before honoring it. The procedure, the limits and the outcome of each failure are stated once, in [Verification](/protocol/authentication/#verification). What the handler supplies and does: - -1. The trusted root keys come from the subscription record that owns the gated term, never from `principal_domain` or a fetched directory -2. The holder is the key the request proved: the RFC 9421 request signer on a direct call, the key each item's `AgentAcceptance` verifies under on a purchase a Broker relayed. On a query a Broker originated nothing can pass this check, so the delegation is not verified or honored there, and the query is answered as if none were present -3. For a gated term, the effective scopes the verifier returns alone decide; `Requester.scopes` is ignored -4. A gated offer expires no later than the effective expiry the verifier returns - -### Provider Trust Verification - -The Exchange SHOULD periodically re-fetch `/.well-known/fora.json` for each tenant's domains to confirm the provider still authorizes this Exchange to sell their resources. If the Exchange is removed from a provider's `fora.json`: - -- Revoke the tenant configuration -- Stop serving offers for that provider's resources -- Log the revocation for audit - -This is ongoing verification, not just onboarding. Providers can revoke authorization at any time by updating their `fora.json`. The Exchange SHOULD check at least once per hour (configurable via tenant settings). - ---- - -## ExecuteTransaction - -The critical path. Stateless offer verification — no offer storage or re-resolution. A request carries one or more `items` (items-only model): each item presents the FULL signed offer it was issued, and the Exchange verifies that presented offer against its own offer-signing key. A single offer is the degenerate 1-element `items` list. Per item the pipeline is: validate -> verify the presented offer's signature (Ed25519 default) -> check idempotency -> authorize billing -> write transaction log -> sign URL -> respond. Before the idempotency check the Exchange verifies the agent's authorization: the request signature on a direct request, the item acceptances on a sub-request a Broker re-packaged, and, when the request carries `agent_request_acceptance`, that set claim — the signature, and that this request's items are the complete in-order projection of the signed set addressed to this Exchange (see [Projected execute requests](/protocol/authentication/#projected-execute-requests)). Idempotency state is never created or served for a request that fails it, and the key is scoped to the agent's [account](/protocol/authentication/#accounts), whatever route the request took. - -```mermaid -sequenceDiagram - participant Agent as Agent / Broker - participant Handler as ConnectHandler - participant Idemp as IdempotencyCache - participant BA as BillingAdapter - participant TxLog as TransactionLog - participant SE as SigningEngine - participant RT as ReportingTracker - - Agent->>Handler: ExecuteTransaction(TransactionRequest{items}) - - Note over Handler: Validate request - Note over Handler: Reject unless EVERY items[].offer.exchange names this Exchange's own domain (INVALID_ARGUMENT) - Note over Handler: Verify the sender's RFC 9421 HTTP Message Signature
(the agent's, or the Broker's on a re-packaged sub-request) - Note over Handler: Verify the agent's authorization: agent_request_acceptance and its projection,
and on a re-packaged sub-request the item acceptances - Note over Handler: Resolve the agent's account (direct: the signer's directory,
relayed: requester.domain, once the acceptances verify) - Note over Handler: Check idempotency key, scoped to the agent - - Handler->>Idemp: Check(agent, idempotency_key) - alt Already processed - Idemp-->>Handler: cached TransactionResponse - Handler-->>Agent: TransactionResponse (replay) - end - - loop For each item in items - Note over Handler: Verify the presented item.offer signature
(Ed25519 default, no offer storage, no re-resolution) - Note over Handler: Extract tenant via domain→tenant lookup - - Handler->>BA: Authorize(ctx, AuthorizeRequest) - Note over BA: Check requester balance/credit
Resolve billing reference
Reserve funds - - alt Authorization failed - BA-->>Handler: AuthorizeResponse{Approved: false} - Note over Handler: record per-item denial_reason (in-body) - end - - BA-->>Handler: AuthorizeResponse{Approved: true, BillingID: "..."} - - Note over Handler: Generate transaction_id (ULID) - - Handler->>TxLog: Write(TransactionRecord) [MUST succeed before signing] - Note over TxLog: Append to WAL buffer
Durable write confirmed - - Handler->>SE: SignURL(ctx, tenantID, contentURL, txnID, agentID, expiry) - SE-->>Handler: signedURL - - Handler->>RT: CreateObligation(ctx, txnID, reportingPolicy) - - Handler->>BA: Record(ctx, RecordRequest) - Note over BA: Confirm transaction in billing system - end - - Handler->>Idemp: Store(agent, idempotency_key, response) - - Handler-->>Agent: TransactionResponse{items} -``` - -**Critical ordering invariant**: The transaction log write MUST complete successfully before the Signing Engine generates the signed URL. If the transaction log write fails, the request is rejected — no signed URL is ever issued for an unrecorded transaction. This is the "write-before-sign" rule from the NFR document. - -### Handler Implementation - -A transaction carries one or more `items` (items-only model): there is no single-offer request shape. The handler validates, verifies the requester's RFC 9421 identity (and, on a sub-request a Broker re-packaged, the agent's acceptances), resolves the agent's account, checks idempotency once for the whole request under that agent, then **always** iterates `req.Msg.Items` — a single offer is simply a 1-element list. Each item presents the FULL signed offer it received at discovery; the Exchange verifies that presented `item.Offer` against its own offer-signing key (stateless, no reconstruct-from-catalog) and reads pricing, delivery, and domain from `item.Offer` itself. - -**Denial semantics**: every per-item denial is answered **in the body**, whatever the item count. The request returns 200 with the denied item's `denial_reason` set, so surviving items still commit, and a one-item request that is denied is a 200 whose only item is denied. A non-OK error carrying `ErrorDetail.transaction_denial` is produced only for a refusal of the **whole request** that decides no item — a reason about the requester that would deny every item alike, such as overdue reports on the agent's account. `transactionDenied(...)` produces that whole-request error; the loop records every per-item denial in the body. - -```go -func (h *ExchangeHandler) ExecuteTransaction( - ctx context.Context, - req *connect.Request[forav1.TransactionRequest], -) (*connect.Response[forav1.TransactionResponse], error) { - // 1. Validate - if err := validate(req.Msg); err != nil { - return nil, connect.NewError(connect.CodeInvalidArgument, err) - } - - // 2. Requester identity. As in DiscoverResources steps 2 and 2b, the SDK's - // verify middleware already verified every RFC 9421 signature at the HTTP - // seam; the handler consumes the proof from the context, fails closed when - // it is absent, and requires requester.domain to name the signing - // directory (elided here). On a sub-request a Broker re-packaged, the - // signer is the Broker, and the agent is authenticated instead by its - // acceptances, verified against the directory requester.domain names - // (see "Sub-requests from a Broker" below). - requester := req.Msg.Requester - verified := helpers.FromContext(ctx) - if verified == nil { - return nil, connect.NewError(connect.CodeUnauthenticated, - errors.New("request reached the handler without a verified signature")) - } - - // 2b. Authenticate the AGENT and resolve its account (see "Accounts" on the - // authentication page). On a direct request the agent is the verified - // signer, and its directory is the covered Signature-Agent origin. On a - // sub-request a Broker re-packaged, the agent is the one its acceptances - // authenticate: they, and the agent_request_acceptance projection when - // present, must verify against the keys of the directory requester.domain - // names. This runs before any idempotency state is read or written: a - // relayed request that proves no agent has every item denied in the body - // and touches no stored result. All entitlement, compliance and billing - // below use this account, never requester.id and never the Broker's; the - // Broker is kept only for attribution (agent.RelayedBy). - agent, ok := h.authenticateAgent(ctx, verified, req.Msg) - if !ok { - return connect.NewResponse(denyEveryItem(req.Msg, - forav1.DenialReason_DENIAL_REASON_SIGNATURE_INVALID)), nil - } - account, err := h.accounts.ForDirectory(ctx, agent.Directory) - if err != nil { - return nil, connect.NewError(connect.CodePermissionDenied, err) - } - - // 3. Idempotency check (idempotency_key — REQUIRED). The key is scoped to the - // agent, whatever the route: a direct request and a sub-request a Broker - // re-packaged for the same agent share one scope. The stored entry keeps a - // digest of the ordered items (each offer.signature), so the same key with - // the same items is a replay, answered with the stored result and the - // delivery binding it recorded, and the same key with different items, or - // another order, is refused with already_exists and no typed reason. - scope := agent.Directory - if cached, ok := h.idempotency.Get(scope, req.Msg.IdempotencyKey); ok { - if cached.ItemsDigest != itemsDigest(req.Msg.Items) { - return nil, connect.NewError(connect.CodeAlreadyExists, - errors.New("idempotency_key already used by this agent with a different request")) - } - return connect.NewResponse(cached.Response), nil - } - - // 3a. Reporting gate: refuse up front if the agent's account has overdue - // reports. It runs after the replay check, so a stored result is still - // answered. This is a reason about the requester that would deny every - // item alike, so - // it refuses the WHOLE request, whatever the item count: a non-OK error - // carrying ErrorDetail.transaction_denial, and nothing is purchased. - if blocked, reason := h.reporting.CheckBuyerCompliance(ctx, account.ID); blocked { - slog.Warn("requester blocked for overdue reporting", - slog.String("requester_id", requester.Id), - slog.String("domain", requester.Domain), - slog.String("reason", reason), - ) - return nil, transactionDenied(forav1.DenialReason_DENIAL_REASON_REPORTING_OVERDUE) - } - - // 4. Items-only pipeline. There is no separate single-offer branch: a single - // offer is the degenerate 1-element `items` list, and its denial is answered - // in the body like any other. Process each item independently — items are - // NOT atomic; one can fail (signature invalid, resource unavailable, billing - // denied) while others succeed. - // agent_identity_hash names the key the delivery URL binds to; which key that - // is on each route is stated on TransactionResponse.agent_identity_hash. - agentHash, err := helpers.Thumbprint(agent.Key) - if err != nil { - return nil, connect.NewError(connect.CodeInternal, err) - } - // The account handle (the billing_ref minted at Register) comes from the - // agent's account resolved in step 2b, on a relayed purchase too. The request - // carries no caller-written billing field, and requester.id never selects the - // account. - billingRef := account.BillingRef - var resultItems []*forav1.TransactionResultItem - totals := map[string]float64{} // purchased amount per currency - - for _, item := range req.Msg.Items { - resultItem := &forav1.TransactionResultItem{OfferId: item.Offer.OfferId} - - // deny records a per-item denial in the body. It is the same for a - // one-item request and a batch: a per-item denial is never a non-OK error. - deny := func(reason forav1.DenialReason) { - resultItem.DenialReason = &reason - resultItems = append(resultItems, resultItem) - } - - // 4a. Verify the PRESENTED signed offer (stateless — no offer storage, - // no reconstruct-from-catalog). The id and signature live inside the - // reflected offer: item.Offer.OfferId, item.Offer.Signature, - // item.Offer.SignatureAlgorithm. offerVerifier.Verify checks the - // signature over the presented offer bytes against the Exchange's own - // offer-signing key and returns that same offer to read pricing from. - offer, err := h.offerVerifier.Verify(item.Offer) - if err != nil { - deny(forav1.DenialReason_DENIAL_REASON_SIGNATURE_INVALID) - continue - } - - // Resolve tenant from the offer's Exchange domain (domain→tenant lookup) - tenantCfg, err := h.tenants.ResolveFromDomain(offer.Exchange) - if err != nil { - deny(forav1.DenialReason_DENIAL_REASON_CONTENT_UNAVAILABLE) - continue - } - - // 4b. Authorize billing (per item) — skip for subscription offers - var billingID string - var amount float64 - if offer.SubscriptionId != nil { - billingID = "sub-" + ulid.Make().String() - amount = 0 - resultItem.SubscriptionId = proto.String(*offer.SubscriptionId) - resultItem.SubscriptionUnitValue = &forav1.Cost{ - Amount: offer.OriginalRate, - Currency: offer.Pricing.Currency, - UnitCost: offer.Pricing.UnitCost, - } - } else { - authResp, err := h.billing.Authorize(ctx, &BillingAuthorizeRequest{ - BillingRef: billingRef, - Amount: offer.Pricing.Rate, - Currency: offer.Pricing.Currency, - OfferID: offer.OfferId, - TenantID: tenantCfg.ID, - }) - if err != nil { - slog.Error("billing authorization failed", - slog.String("offer_id", offer.OfferId), - slog.String("tenant_id", tenantCfg.ID), - slog.Any("error", err), - ) - } - if err != nil || !authResp.Approved { - if err == nil { - slog.Warn("billing authorization denied", - slog.String("offer_id", offer.OfferId), - slog.String("reason", authResp.Reason), - ) - } - deny(txnErrToDenialReason(err)) - continue - } - billingID = authResp.BillingID - amount = offer.Pricing.Rate - } - - // 4c. Write transaction log (MUST succeed before signing — WAL invariant - // applies per item). No signed URL is ever issued for an unrecorded - // transaction. - txnID := ulid.Make().String() - record := &TransactionRecord{ - TransactionID: txnID, - BillingID: billingID, - OfferID: offer.OfferId, - TenantID: tenantCfg.ID, - BillingRef: billingRef, - Broker: agent.RelayedBy, // the relaying Broker; attribution only, never billed - AgentIdentityHash: agentHash, - Amount: amount, - Currency: offer.Pricing.Currency, - UnitCost: derefFloat64(offer.Pricing.UnitCost), - OfferSnapshotJSON: marshalOfferSnapshot(offer), - DeliveryMethod: offer.DeliveryMethod, - ReportingRequired: tenantCfg.ReportingPolicy.GetRequired(), - IdempotencyKey: req.Msg.IdempotencyKey, - CreatedAt: time.Now().UTC(), - } - if err := h.txLog.Write(ctx, record); err != nil { - slog.Error("txlog write failed", - slog.String("txn_id", txnID), - slog.String("billing_id", billingID), - slog.Any("error", err), - ) - if releaseErr := h.billing.Release(ctx, billingID); releaseErr != nil { - slog.Error("billing release after txlog failure also failed", - slog.String("billing_id", billingID), - slog.Any("error", releaseErr), - ) - } - deny(forav1.DenialReason_DENIAL_REASON_CONTENT_UNAVAILABLE) - continue - } - - // 4d. Sign URL (only after durable log write) - signedURL, err := h.signer.SignURL(ctx, tenantCfg.ID, SignRequest{ - ContentURL: tenantCfg.ContentBaseURL + offer.ContentPath, - TransactionID: txnID, - AgentIdentity: agentHash, - Expiry: tenantCfg.URLTTLOrDefault(5 * time.Minute), - }) - if err != nil { - slog.Error("URL signing failed", - slog.String("txn_id", txnID), - slog.String("tenant_id", tenantCfg.ID), - slog.Any("error", err), - ) - deny(forav1.DenialReason_DENIAL_REASON_CONTENT_UNAVAILABLE) - continue - } - - // 4e. Create reporting obligation - h.reporting.CreateObligation(ctx, txnID, tenantCfg.ReportingPolicy) - - // 4f. Record in billing (async-safe — transaction is already logged) - if err := h.billing.Record(ctx, &BillingRecordRequest{ - BillingID: billingID, - TransactionID: txnID, - Amount: amount, - Currency: offer.Pricing.Currency, - }); err != nil { - slog.Error("billing record failed", - slog.String("txn_id", txnID), - slog.String("billing_id", billingID), - slog.Any("error", err), - ) - } - - // 4g. Populate the successful per-item result. - resultItem.TransactionId = txnID - resultItem.BillingId = billingID - resultItem.ResourceTitle = offer.Title // human-readable title echoed from the Offer - resultItem.RetrievalEndpoint = proto.String(signedURL) - resultItem.Cost = &forav1.Cost{ - Amount: amount, - Currency: offer.Pricing.Currency, - UnitCost: offer.Pricing.UnitCost, - } - resultItem.DeliveryMethod = offer.DeliveryMethod - resultItem.ReportingObligation = tenantCfg.ReportingPolicy - resultItem.ExpiresAt = timestamppb.New(time.Now().Add(tenantCfg.URLTTLOrDefault(5 * time.Minute))) - resultItems = append(resultItems, resultItem) - - totals[offer.Pricing.Currency] += amount - } - - // 5. Build response — every per-result datum lives on its TransactionResultItem; - // the top-level fields carry only shared aggregate state. Correlation is not - // in the body — it rides the X-Request-ID HTTP header across the round-trip. - // total_cost is set only when the purchased items share one currency: - // amounts are never summed across currencies, and this version defines no - // currency conversion. - resp := &forav1.TransactionResponse{ - Ver: helpers.ProtocolVersion, - AgentIdentityHash: agentHash, - Items: resultItems, - } - if len(totals) == 1 { - for currency, amount := range totals { - resp.TotalCost = &forav1.Cost{Amount: amount, Currency: currency} - } - } - - // 6. Cache for idempotency, under the agent's scope, with the items digest - // that tells a replay from a reuse of the key with a different request. - h.idempotency.Set(scope, req.Msg.IdempotencyKey, cachedResult{ - Response: resp, - ItemsDigest: itemsDigest(req.Msg.Items), - }, 10*time.Minute) - return connect.NewResponse(resp), nil -} - -// transactionDenied maps a typed DenialReason to a non-OK transport error -// carrying ErrorDetail.transaction_denial. It is used ONLY for a refusal of the -// whole request — a reason about the requester that decides no item — never for a -// per-item denial, which is answered in the body whatever the item count. The -// transport code is the error class, the attached ErrorDetail the typed reason. -func transactionDenied(reason forav1.DenialReason) error { - detail := &forav1.ErrorDetail{ - Reason: &forav1.ErrorDetail_TransactionDenial{ - TransactionDenial: &forav1.TransactionDenial{ - Reason: reason, - }, - }, - } - err := connect.NewError(connect.CodePermissionDenied, errors.New("transaction denied")) - if d, derr := connect.NewErrorDetail(detail); derr == nil { - err.AddDetail(d) - } - return err -} -``` - -**Latency budget**: 20ms p50, 100ms p99 per item. The billing adapter authorization (5ms p50) and transaction log write (1-2ms p50 for local WAL) dominate. Multi-item requests are processed sequentially, so latency scales with item count. - -**Atomicity note**: Multi-item requests are best-effort per item and **NOT atomic**. The Exchange processes items sequentially in original order. If item 3 of 5 fails billing authorization, items 1-2 are already committed (signed URLs issued) and items 4-5 continue processing. The caller MUST check each `TransactionResultItem.denial_reason` to determine which items succeeded. This non-atomic model is deliberate: it matches how programmatic resource access handles multi-slot requests. A 1-element request follows the same rule: its denial is an in-body `denial_reason`, never a non-OK error. - -### Sub-requests from a Broker - -When an agent buys through `BrokerService.ExecuteTransaction`, the Broker sends this Exchange a sub-request it authored: this Exchange's items in request order, each with the agent's `AgentAcceptance`, the agent's `AgentRequestAcceptance`, `requester` and `idempotency_key` unchanged, and the **Broker's** RFC 9421 signature. The pipeline above runs unchanged, with these points to note: - -- **Who consented.** The wire signer is the Broker. The agent is authenticated by its body acceptances, verified against the keys published in the WBA directory of `requester.domain`. The delivery URL and `agent_identity_hash` are bound to the agent key the acceptances verify under, and a delegation's `cnf.jkt` is checked against that same key. -- **Whose purchase.** The purchase is the agent's. Its account is the one the directory of `requester.domain` names, resolved once the acceptances verify, and billing, the account checks, the reporting gate and the transaction record use it. The Broker is kept with the record for attribution only (see [Accounts](/protocol/authentication/#accounts)). -- **Idempotency.** The key is the agent's, forwarded unchanged, and scoped to the agent as on a direct request: the same key from the same agent, directly or through any Broker, is one purchase, and two agents behind one Broker that choose the same key never collide. The acceptances are verified before any idempotency state is read or written. The same key with different items is refused with `already_exists`. -- **The signed set.** If the sub-request's items are not exactly the agent's `AgentRequestAcceptance` projected onto this Exchange — an item dropped, added or reordered — deny every item with `DENIAL_REASON_SIGNATURE_INVALID`, in the body, purchase nothing and claim no idempotency state. It is not an `invalid_argument` error. -- **Answers.** Answer exactly as for a direct request: every per-item denial in the body, whatever the item count. Whether relayed purchases are accepted is decided per item, by the provider of each offer's resource: an item whose provider does not accept them is denied with `DENIAL_REASON_RELAY_NOT_ACCEPTED`, in the body, while the other items may succeed. It is never a refusal of the whole sub-request. Only a refusal of the whole sub-request, which decides no item, is a non-OK error; it reaches the agent unchanged on each affected item's `TransactionResultItem.refusal`, because the Broker never turns it into an error of its own. - -### Partial Failure Handling - -The ExecuteTransaction pipeline has multiple steps that can fail independently: - -| Step Failed | Already Done | Action | -|---|---|---| -| Validation | Nothing | Return `CodeInvalidArgument` (the whole request) | -| Offer signature verification | Nothing | Deny the item in the body (`DENIAL_REASON_SIGNATURE_INVALID`) | -| Billing Authorize | Nothing | Deny the item in the body, with the reason the timeout policy maps the sentinel error to | -| Transaction log write | Billing authorized | Release billing hold, deny the item in the body | -| URL signing | Billing authorized + log written | Log error, deny the item in the body (txn recorded as failed) | -| Reporting obligation create | Billing + log + URL | Log warning, continue (non-critical) | -| Billing Record | Billing + log + URL | Log warning, continue (reconciliation catches) | - -The key invariant: if the transaction log write fails, no signed URL is ever issued. If the signed URL generation fails, the transaction is recorded as failed for reconciliation. Every failure in this table that concerns one item is answered on that item, in the body, whatever the item count. - ---- - -## ReportUsage - -Lower-latency path. Validates report against recorded obligation, updates state, persists. The agent files its own report, with the Exchange that issued the offer, for a purchase made through a Broker as for a direct one; no Broker files or relays one (see [Accounts](/protocol/authentication/#accounts)). - -```mermaid -sequenceDiagram - participant Agent - participant Handler as ConnectHandler - participant RT as ReportingTracker - participant TxLog as TransactionLog - - Agent->>Handler: ReportUsage(UsageReport) - - Note over Handler: Validate request fields - Note over Handler: Reject unless report.exchange names this Exchange's own domain (INVALID_ARGUMENT) - - Handler->>TxLog: LookupTransaction(ctx, txnID) - TxLog-->>Handler: TransactionRecord (verify billing_id matches) - - Handler->>RT: SubmitReport(ctx, UsageReport) - - Note over RT: Validate required fields present - Note over RT: Check reporting window (not expired, else WINDOW_EXPIRED) - Note over RT: consumed_quantity is never checked against the estimate - Note over RT: Transition obligation: pending → fulfilled - - RT->>TxLog: WriteUsageReport(ctx, UsageReportRecord) - - alt Accepted - RT-->>Handler: report_id - Handler-->>Agent: UsageReportResponse (success) - else Rejected - RT-->>Handler: typed UsageReportRejectionReason - Handler-->>Agent: Error (ErrorDetail.usage_report_rejection) - end -``` - -```go -func (h *ExchangeHandler) ReportUsage( - ctx context.Context, - req *connect.Request[forav1.UsageReport], -) (*connect.Response[forav1.UsageReportResponse], error) { - // 1. Validate. A malformed report is invalid_argument with its typed reason, - // USAGE_REPORT_REJECTION_REASON_MALFORMED. - if err := validate(req.Msg); err != nil { - return nil, usageReportRejected(connect.CodeInvalidArgument, - forav1.UsageReportRejectionReason_USAGE_REPORT_REJECTION_REASON_MALFORMED) - } - - // 2. Verify the transaction exists FOR THIS AGENT and billing_id matches: it - // must be recorded under the account of the directory that signed the - // report, a purchase a Broker relayed included. A transaction recorded - // under a different agent's account is answered exactly as an unknown one, - // so the answer does not reveal that it exists. A billing_id - // that is not the transaction's makes the report malformed. - txn, err := h.txLog.LookupForAgent(ctx, agentFrom(ctx), req.Msg.TransactionId) - if err != nil { - return nil, usageReportRejected(connect.CodeNotFound, - forav1.UsageReportRejectionReason_USAGE_REPORT_REJECTION_REASON_TRANSACTION_NOT_FOUND) - } - if txn.BillingID != req.Msg.BillingId { - return nil, usageReportRejected(connect.CodeInvalidArgument, - forav1.UsageReportRejectionReason_USAGE_REPORT_REJECTION_REASON_MALFORMED) - } - - // 3. Submit to reporting tracker. A rejection is NOT a success body: it - // travels as a non-OK transport error carrying a typed - // ErrorDetail.usage_report_rejection (UsageReportRejectionReason). A - // report past its reporting window is WINDOW_EXPIRED with the code - // failed_precondition. The tracker never refuses a report for its - // consumed_quantity: the quantity is unrestricted, and the report is a - // record of it. - // Success returns the Exchange-assigned report_id, required to anchor - // the dispute chain. - result, err := h.reporting.SubmitReport(ctx, req.Msg, txn) - if err != nil { - return nil, connect.NewError(connect.CodeInternal, err) - } - if !result.Accepted { - return nil, usageReportRejected(result.Code, result.Reason) // ErrorDetail.usage_report_rejection - } - - return connect.NewResponse(&forav1.UsageReportResponse{ - ReportId: result.ReportID, - }), nil -} -``` - -**Latency budget**: 5ms p50, 20ms p99. Transaction lookup is a key-value read. Report write is appended to the same WAL as transactions. - ---- - -## Attestation Verification at Catalog Push - -Before the handler below runs, the wire tier has already refused a malformed push: the `ResourceEntry` envelope rules (bare-host `domain`, absolute `path`, bounded fields, at most 32 terms, and at most 256 entries in the submission) and the `LicenseTerm` rules (including at most 8 restrictions, and at most 64 quotas or obligations, per term) are protovalidate rules applied at the boundary. A submission with no entries or more than 256 is a malformed request, refused `invalid_argument` by wire validation with no `catalog_rejection`, because no entry was examined. That tier is something a deployment turns on: an Exchange built on the Go SDK mounts its handler with `connectserver.WithValidation(connect.ValidationStrict)`, which is what composes protovalidate onto it — the option is not the default, and the reference implementation passes it on every mount. The handler then canonicalises the terms and applies registry membership — the ingest tier — before the attestation checks. The ingest tier also re-asserts that no token is both permitted and prohibited (`restriction.canonical_disjoint`), because the boundary rule compares the tokens as written and two spellings of one token become one token only once folded. That is the check a mount without the wire tier still gets, and the one that keeps a self-contradictory term out of the catalog — a stored term that violates the contract would fail validation again on the way out, on every offer that carries it. Both tiers ship in the SDK as a publisher pre-check, so a conforming feed rarely reaches this flow with a refusable entry. - -When `CatalogService.PushResources` includes attestations, the Exchange performs additional verification before accepting entries into the resource catalog. - -```mermaid -sequenceDiagram - participant Caller as Provider / Verifier - participant Handler as CatalogHandler - participant Manifest as WellKnownManifest Cache - participant Verifier as WBA Directory Cache - - Caller->>Handler: PushResources(PushResourcesRequest) - - Note over Handler: 1. Verify caller's RFC 9421 HTTP Message Signature (headers) - - loop For each ResourceEntry with attestations - Handler->>Handler: Is the signer == attestation.verifier? - - alt Direct push (provider or vendor pushing own attestation) - Note over Handler: Authorized directly - else Third-party push - Handler->>Manifest: Is the signer in catalog_contributors? - Manifest-->>Handler: Yes / No - Note over Handler: Record which entry failed — the submission is refused whole - end - - Handler->>Verifier: Fetch verifier keys (cached, TTL-based) - Verifier-->>Handler: WBA directory (keys) - - Note over Handler: Look up attestation key by RFC 7638 thumbprint (keyid) - Note over Handler: Verify attestation.signature (Ed25519) - Note over Handler: Handler-applied claims-size limit (no wire rule bounds claims) - end - - alt Every entry passed - Handler-->>Caller: PushResourcesResponse { accepted: N } - else Any entry failed - Handler-->>Caller: non-OK error + ErrorDetail.catalog_rejection { reason, rejected_paths } - end -``` - -The loop checks each entry, but the verdict is not per-entry: a push is all-or-nothing, so a single failing entry refuses the submission and nothing is persisted. `rejected_paths` names which entries the refusal is about — it is reporting, not a list of what was dropped from an otherwise applied batch. - -**Rejection reasons** come from [`CatalogRejectionReason`](/reference/proto-fora/#catalogrejectionreason). The ones this flow can produce are `CATALOG_REJECTION_REASON_NOT_CATALOG_CONTRIBUTOR` (the signer is not authorized for the entry's domain, a resource-owner mismatch included), `CATALOG_REJECTION_REASON_EXCHANGE_NOT_LISTED` (the publisher's manifest does not list this Exchange), `CATALOG_REJECTION_REASON_DOMAIN_NOT_VERIFIED` and `CATALOG_REJECTION_REASON_MALFORMED_ENTRY`, which the envelope rules make the common one. A push whose request signature fails never reaches this loop: step 1 refuses it like every other signed request, `unauthenticated` with `ErrorDetail.request_auth_failure` (`SIGNATURE_MISSING`, `SIGNATURE_INVALID` or `SIGNATURE_STALE`). `CATALOG_REJECTION_REASON_SIGNATURE_INVALID` is deprecated and never sent. The attestation-specific failures — a bad attestation signature, an unknown verifier, oversized claims — have no dedicated value in that enum; they travel in the refusal's human-readable message. - -See [Content Attestation](/protocol/content-attestation/) for the full attestation system design. - ---- - -## DisputeTransaction - -The dispute path handles post-delivery resource complaints. Agents must file a `UsageReport` before disputing -- `DisputeRequest.report_id` is required. The agent files its own dispute, for a purchase made through a Broker as for a direct one, and the Exchange accepts it only for a transaction recorded under the agent's account. - -```mermaid -sequenceDiagram - participant Agent - participant Handler as ConnectHandler - participant TxLog as TransactionLog - participant CDN as CDN Logs - participant Resolver as DisputeResolver - - Agent->>Handler: DisputeTransaction(DisputeRequest) - - Note over Handler: Validate request (report_id required) - Note over Handler: Reject unless request.exchange names this Exchange's own domain (INVALID_ARGUMENT) - - Handler->>TxLog: LookupTransaction(ctx, transaction_id) - TxLog-->>Handler: TransactionRecord + UsageReport - - Note over Handler: Verify the transaction is recorded under the signing agent's account
(else not found) and report_id matches a filed report - - Handler->>Resolver: Evaluate(dispute, transaction, report) - - Note over Resolver: Tier 1: Check CDN logs for delivery failure - Resolver->>CDN: QueryAccessLog(transaction_id) - CDN-->>Resolver: HTTP status, response size, timestamp - - alt CDN failure (4xx/5xx) - Note over Resolver: AUTO_RESOLVED -> CREDIT - else Hash mismatch (Level 1) - Note over Resolver: AUTO_RESOLVED -> CREDIT - else CDN size corroborates discrepancy - Note over Resolver: AUTO_RESOLVED -> CREDIT - else Inconclusive - Note over Resolver: EVIDENCE_NEEDED (Tier 2) - end - - Resolver-->>Handler: DisputeResponse - - Handler-->>Agent: DisputeResponse -``` - -A `DisputeResponse` is only returned when the dispute is **accepted for processing**. A refusal to file (transaction unknown, no preceding usage report, window expired, duplicate, ineligible) is a non-OK transport error carrying a typed `ErrorDetail.dispute_failure` (`DisputeFailureReason`) — not a `DisputeResponse` with a rejection field. - -**Tier 1 resolution** uses CDN access logs as the authoritative evidence source, with a design goal of under a second. CDN logs are infrastructure-level records that neither party controls, making them the most trustworthy evidence in the hierarchy. - -See [Dispute Resolution](/protocol/dispute-resolution/) for the recommended three-tier resolution policy and abuse prevention. diff --git a/website/src/content/docs/components/exchange/scaling.mdx b/website/src/content/docs/components/exchange/scaling.mdx deleted file mode 100644 index 7ae40419..00000000 --- a/website/src/content/docs/components/exchange/scaling.mdx +++ /dev/null @@ -1,547 +0,0 @@ ---- -title: "Scaling and Performance" -description: "NFR targets, caching strategies, concurrency model, horizontal scaling, failure modes, and cost analysis for the Exchange Node." ---- - -## NFR Targets - -| Metric | Target | -|---|---| -| Request rate | 10K RPS | -| ExecuteTransaction latency (p99) | <100ms | -| DiscoverResources latency (p99) | <50ms | -| ReportUsage latency (p99) | <20ms | -| Per-transaction cost | <$0.00005 | - ---- - -## Concurrency Model - -### Goroutine-Per-Request - -Each incoming RPC is handled by its own goroutine (standard Go HTTP server behavior). No goroutine pooling needed — Go's scheduler handles this efficiently up to 100K+ concurrent goroutines. - -```go -// Server setup — standard Connect-Go with HTTP/2. -func NewServer(cfg *Config) *http.Server { - mux := http.NewServeMux() - - handler := NewExchangeHandler(cfg) - path, h := forav1connect.NewExchangeServiceHandler(handler) - mux.Handle(path, h) - - return &http.Server{ - Addr: cfg.ListenAddr, - Handler: mux, - // HTTP/2 enabled by default in Go's net/http - } -} -``` - -### Lock-Free Catalog Reads - -The resource catalog is read on every DiscoverResources call. Writes happen only during RSL re-ingestion (every 5 minutes). This is a classic read-heavy workload. - -**Pattern**: Copy-on-write with `atomic.Pointer`. - -```go -// Read path (hot — every DiscoverResources): -func (c *Catalog) FindOffers(ctx context.Context, tenantID string, ais *compv1.AISystem) ([]*forav1.Offer, error) { - // Atomic load — no lock, no contention - snapshot := c.current.Load() - tenant, ok := snapshot.Tenants[tenantID] - if !ok { - return nil, ErrTenantNotFound - } - // Traverse radix trie — immutable data, safe for concurrent reads - return tenant.matchOffers(ais) -} - -// Write path (cold — every 5 minutes per tenant): -func (c *Catalog) ReplaceSnapshot(newSnapshot *CatalogSnapshot) { - // Atomic store — single pointer write, no lock - // Old snapshot is GC'd after all in-flight reads complete - c.current.Store(newSnapshot) -} -``` - -No `sync.RWMutex` needed. The atomic pointer swap is wait-free. In-flight reads on the old snapshot complete normally; they just see slightly stale data (which is fine — the catalog changes every 5 minutes, not every request). - -### Connection Pooling to Billing Adapter - -The Billing Adapter makes an external call on every ExecuteTransaction. Connection reuse is critical. - -```go -// Billing adapter HTTP client with connection pooling. -billingClient := &http.Client{ - Transport: &http.Transport{ - MaxIdleConns: 200, - MaxIdleConnsPerHost: 200, - IdleConnTimeout: 90 * time.Second, - // Keep-alive enabled by default - }, - Timeout: 30 * time.Millisecond, // Hard timeout per NFR -} -``` - -At 10K RPS, the billing adapter needs to sustain 10K concurrent requests. With connection reuse and a 5ms average response time, ~50 connections can handle 10K RPS. The pool of 200 provides headroom for latency spikes. - -### Batched Transaction Log Writes - -Individual fsync per transaction is too slow at 10K RPS. The WAL batches writes. - -```go -// WALWriter batches transaction log writes for throughput. -type WALWriter struct { - file *os.File - buf *bufio.Writer - mu sync.Mutex - pending []pendingWrite - ticker *time.Ticker // Flush interval -} - -type pendingWrite struct { - data []byte - done chan error -} - -// Write appends a record to the WAL. Blocks until the batch is flushed. -func (w *WALWriter) Write(ctx context.Context, record *TransactionRecord) error { - data, err := encodeRecord(record) - if err != nil { - return err - } - - pw := pendingWrite{data: data, done: make(chan error, 1)} - - w.mu.Lock() - w.pending = append(w.pending, pw) - shouldFlush := len(w.pending) >= w.batchSize - w.mu.Unlock() - - if shouldFlush { - w.flush() - } - - // Wait for flush confirmation - select { - case err := <-pw.done: - return err - case <-ctx.Done(): - return ctx.Err() - } -} - -// flush writes all pending records and fsyncs. -func (w *WALWriter) flush() { - w.mu.Lock() - batch := w.pending - w.pending = w.pending[:0] - w.mu.Unlock() - - var writeErr error - for _, pw := range batch { - if _, err := w.buf.Write(pw.data); err != nil { - writeErr = err - break - } - } - if writeErr == nil { - writeErr = w.buf.Flush() - } - if writeErr == nil { - writeErr = w.file.Sync() // fdatasync — one sync per batch - } - - for _, pw := range batch { - pw.done <- writeErr - } -} -``` - -At 10K RPS with 50ms flush interval, each batch contains ~500 records. One fdatasync per batch = 20 fsyncs/second, well within SSD capability (typically 10K+ IOPS). - -### Idempotency Cache - -The idempotency cache uses a concurrent LRU with sharded locks to avoid contention: - -```go -// IdempotencyCache stores recent TransactionResponse values keyed by the agent -// and its idempotency key: the agent's authenticated key directory plus -// TransactionRequest.idempotency_key, whatever route the request took (see -// "Accounts" and "Idempotency" in the protocol). Sharded by hash of key to -// reduce lock contention. -type IdempotencyCache struct { - shards [256]*idempotencyShard - ttl time.Duration -} - -type idempotencyShard struct { - mu sync.RWMutex - items map[string]*idempotencyEntry -} - -type idempotencyEntry struct { - response *forav1.TransactionResponse - expiresAt time.Time -} -``` - ---- - -## Horizontal Scaling - -### What's Stateless - -The Exchange request handler is stateless. Any instance can handle any request. No session affinity required. - -### What's Shared State - -| State | Sharing Model | Consistency | -|---|---|---| -| Content catalog | Independently built per instance from RSL | Eventual (instances may serve slightly different catalogs during RSL re-ingestion) | -| Transaction log | Shared durable store (Kafka/S3/DynamoDB) | Append-only, no conflicts | -| Idempotency cache | Per-instance (not shared) | At-most-once per instance; cross-instance idempotency via transaction log dedup | -| Reporting obligations | Shared durable store | Eventually consistent | -| Signing keys | Shared secrets manager (read-only) | Consistent (all instances load same keys) | - -### Idempotency Across Instances - -The per-instance idempotency LRU cache handles the common case (retry hits same instance). For cross-instance retries (load balancer routes retry to different instance), the transaction log provides dedup. - -**Growth Tier**: Accept the risk. Both nodes may process the same request. The transaction log provides deduplication at the durable store layer. The billing adapter's `Record` call is idempotent (keyed by billing_id). The cost of a rare duplicate signed URL is negligible compared to the engineering cost of distributed coordination at this tier. - -``` -Node A: processes request → writes txn log → signs URL → responds -Node B: processes same request → writes txn log (dedup at store) → signs URL → responds -Result: Two signed URLs issued for one billing event. CDN redeems one. No financial impact. -``` - -**Scale Tier**: At 10K+ RPS, use Redis for distributed idempotency: - -```go -// Distributed idempotency check via Redis. The key is the agent (its -// authenticated key directory, which holds no "/") and the request's -// idempotency key (TransactionRequest.idempotency_key), whatever the route, -// not the wire correlation id (which rides the X-Request-ID HTTP header). -func (h *ExchangeHandler) checkIdempotency(ctx context.Context, agent, idempotencyKey string) (*forav1.TransactionResponse, error) { - key := agent + "/" + idempotencyKey - // 1. Local LRU (fast path, no network) - if cached, ok := h.localCache.Get(key); ok { - return cached, nil - } - // 2. Redis SETNX with TTL (distributed lock) - acquired, err := h.redis.SetNX(ctx, "idemp:"+key, "processing", 10*time.Minute).Result() - if err != nil { - // Redis down — fall back to Growth tier behavior (accept the risk) - slog.Warn("redis idempotency check failed, proceeding without distributed lock", - slog.String("agent", agent), - slog.String("idempotency_key", idempotencyKey), - slog.Any("error", err), - ) - return nil, nil - } - if !acquired { - // Another node is processing — wait briefly, then read result - return h.waitForResult(ctx, key) - } - return nil, nil // Proceed with new transaction -} -``` - -**Day-one guidance**: Don't over-engineer. Start with Growth tier behavior. Add Redis idempotency when you observe duplicate transactions in the transaction log exceeding your tolerance threshold. - -### Sharding Strategy - -For the Scale tier (10K RPS) and beyond, shard by **provider tenant**: - -``` - ┌──────────────┐ - │ Load Balancer│ - │ (L7, path │ - │ routing) │ - └──────┬───────┘ - │ - ┌────────────┼────────────┐ - │ │ │ - ┌─────────▼────┐ ┌─────▼──────┐ ┌──▼───────────┐ - │ Shard A │ │ Shard B │ │ Shard C │ - │ Tenants: │ │ Tenants: │ │ Tenants: │ - │ techcrunch │ │ reuters │ │ wsj │ - │ verge │ │ apnews │ │ nytimes │ - │ wired │ │ bbc │ │ washpost │ - └──────────────┘ └────────────┘ └──────────────┘ -``` - -**Why shard by tenant?** -- Each shard's catalog is smaller (fewer tenants = less memory). -- Signing keys are isolated per shard. -- A misbehaving tenant (RSL changes, traffic spikes) only affects its shard. -- Load balancer can route based on the URI domain in the ResourceQuery. - -**Why not shard by requester or content path?** -- Requester sharding requires the load balancer to inspect the request body (`requester.id` + `requester.domain`), which is slower and more complex. -- Content path sharding fragments a tenant's catalog across shards, complicating RSL ingestion and offer resolution. - -**Load balancing**: Layer 7 (HTTP) load balancer. Use consistent hashing on the target domain extracted from the request URI for sticky routing. Fallback to round-robin for requests without a resolvable domain. - -### Scaling Tiers - -| Tier | Instances | Tenants/Instance | RPS/Instance | Total RPS | -|---|---|---|---|---| -| Growth | 4 | 25 | 250 | 1,000 | -| Scale | 20 | 5 | 500 | 10,000 | -| Extreme | 100+ | 1-2 | 1,000 | 100,000+ | - ---- - -## Failure Modes - -### Billing Adapter Timeout - -**Scenario**: Billing Authorize call exceeds the 30ms timeout. - -**Policy options** (configurable per deployment): - -| Policy | Behavior | Risk | When to Use | -|---|---|---|---| -| **Reject** (default) | Return `CodeUnavailable` to agent | Lost revenue | High-value content, strict accounting | -| **Deferred** | Authorize optimistically, record for later settlement | Potential bad debt | Low-value content, trusted requesters | - -For deferred mode, the transaction is logged with `billing_status: "deferred"` and a background reconciliation goroutine retries authorization when the billing system recovers. - -### CDN Signing Failure - -**Scenario**: SignURL returns an error (corrupt key, unsupported algorithm, etc.). - -**Behavior**: Transaction is rejected. The billing hold is released. The transaction log records the failure with `status: "sign_failed"`. - -This is a hard failure — no fallback. The Exchange cannot issue an unsigned URL; it would bypass the entire security model. The operator must fix the signing configuration. - -### Catalog Stale or Empty - -**Scenario**: RSL ingestion fails (provider domain down, RSL malformed, network error). - -**Behavior**: The Exchange continues serving from the previous catalog snapshot. DiscoverResources returns offers based on the last successful ingestion. The catalog's `BuiltAt` timestamp is included in metrics for staleness monitoring. - -**If no catalog has ever been built** (first startup, RSL never reachable): DiscoverResources returns zero offers. The Exchange is healthy but has no inventory. - -**Alert thresholds**: -- Catalog age > 15 minutes: warning -- Catalog age > 1 hour: critical -- Catalog empty for > 5 minutes: critical - -### Transaction Log Store Down - -**Scenario**: The durable store (Kafka, S3, DynamoDB) backing the transaction log is unreachable. - -**Behavior**: The local WAL continues accepting writes. The WAL has a configurable capacity (default: 1 GB, ~5M records). When the durable store recovers, the WAL drainer resumes shipping records. - -**If WAL reaches capacity**: The Exchange stops accepting new transactions (ExecuteTransaction returns `CodeUnavailable`). DiscoverResources and ReportUsage continue functioning. This is the "transaction log store down" failure mode from the NFR document — the Exchange must stop issuing signed URLs when it cannot guarantee durable recording. - -```go -// WALDrainer ships WAL records to the durable store. -type WALDrainer struct { - wal *WALWriter - store TransactionStore - retryDelay time.Duration // Exponential backoff on store failure - maxWALBytes int64 // Capacity limit before rejecting transactions -} - -func (d *WALDrainer) Run(ctx context.Context) { - for { - select { - case <-ctx.Done(): - return - default: - batch, err := d.wal.ReadBatch(1000) - if err != nil { - // WAL read error — critical, log and retry - continue - } - if err := d.store.WriteBatch(ctx, batch); err != nil { - // Durable store down — back off and retry - time.Sleep(d.retryDelay) - d.retryDelay = min(d.retryDelay*2, 30*time.Second) - continue - } - d.retryDelay = 100 * time.Millisecond // Reset on success - d.wal.Acknowledge(batch) // Mark WAL records as shipped - } - } -} -``` - ---- - -## Cost Analysis - -### At 10K RPS (Scale Tier) - -**Assumptions**: 864M transactions/day. Go binary running on AWS ECS. US-East region. 30-day month. - -#### Compute - -| Component | Instances | Instance Type | Monthly Cost | -|---|---|---|---| -| Exchange Node | 20 | c7g.xlarge (4 vCPU, 8 GB) | 20 x $98 = **$1,960** | -| Total monthly compute | | | **$1,960** | -| Per-transaction compute | | | **$0.0000000756** | - -Each c7g.xlarge handles ~500 RPS. Go's goroutine model and in-memory catalog mean CPU is primarily spent on serialization and crypto. At 500 RPS with 20ms average latency, each request consumes ~10ms of CPU time = ~0.01 vCPU per request. 500 RPS x 0.01 = 5 vCPU needed per instance — but we have 4, so targeting 500 RPS leaves ~20% headroom when accounting for non-request CPU (RSL ingestion, WAL flushing, etc.). - -#### Storage - -| Component | Store | Volume/Month | Monthly Cost | -|---|---|---|---| -| Transaction log (Kafka) | MSK (3 brokers, kafka.m5.large) | ~800 GB/month | **$600** | -| Transaction log (S3 archival) | S3 Standard | ~200 GB/month (Parquet compressed) | **$5** | -| WAL (local EBS) | gp3, 100 GB per instance | 20 x 100 GB | **$160** | -| Idempotency cache | In-memory | ~1 GB per instance | $0 (included in compute) | -| Content catalog | In-memory | ~2-20 GB per instance | $0 (included in compute) | -| Total monthly storage | | | **$765** | -| Per-transaction storage | | | **$0.0000000295** | - -#### Network - -| Component | Volume/Month | Monthly Cost | -|---|---|---| -| Inter-AZ (Exchange to Kafka) | ~400 GB | **$4** | -| Internet egress (responses to agents) | ~500 GB | **$45** | -| Total monthly network | | **$49** | -| Per-transaction network | | **$0.0000000019** | - -#### Total Cost - -| Category | Monthly | Per Transaction | -|---|---|---| -| Compute | $1,960 | $0.0000000756 | -| Storage | $765 | $0.0000000295 | -| Network | $49 | $0.0000000019 | -| **Total** | **$2,774** | **$0.000000107** | - -**Per-transaction cost: ~$0.0000001** — well under the NFR target of $0.00005/txn. That target was conservative; the actual infrastructure cost is **500x below** the ceiling. - -At $0.05/article average transaction value, infrastructure cost is **0.0002%** of transaction value. Even including the billing adapter (estimated ~$500/month for DynamoDB at this scale), the total is under $3,300/month — **$0.000127/txn**. - -The dominant cost is not compute or storage but **engineering time** to build and maintain the Billing Adapter integration and tenant onboarding tooling. - -#### Cost Comparison: Containers vs. Lambda - -| Model | Monthly Cost at 10K RPS | Per-Transaction | -|---|---|---| -| **Containers (this design)** | ~$2,774 | $0.0000001 | -| **Lambda** (128MB, 50ms avg) | ~$8,100 | $0.0000003 | -| **Lambda** (256MB, 50ms avg) | ~$16,200 | $0.0000006 | - -Containers are ~3-6x cheaper at this sustained load, confirming the NFR recommendation. - ---- - -## Metrics and Observability - -All metrics are exposed via Prometheus (OpenMetrics format) on `/metrics`. - -### Request Metrics - -| Metric | Type | Labels | Description | -|---|---|---|---| -| `exchange_rpc_total` | Counter | `method`, `code`, `tenant_id` | Total RPC calls | -| `exchange_rpc_duration_seconds` | Histogram | `method`, `tenant_id` | RPC latency (p50, p95, p99) | -| `exchange_offers_returned` | Histogram | `tenant_id` | Offers per DiscoverResources response | -| `exchange_transaction_total` | Counter | `tenant_id`, `status` | Transactions by outcome | - -### Billing Adapter Metrics - -| Metric | Type | Labels | Description | -|---|---|---|---| -| `billing_authorize_duration_seconds` | Histogram | `tenant_id`, `approved` | Billing authorization latency | -| `billing_authorize_total` | Counter | `tenant_id`, `approved` | Billing authorization outcomes | -| `billing_timeout_total` | Counter | `tenant_id` | Billing adapter timeouts | - -### Catalog Metrics - -| Metric | Type | Labels | Description | -|---|---|---|---| -| `catalog_offers_total` | Gauge | `tenant_id` | Current offer count per tenant | -| `catalog_last_refresh_timestamp` | Gauge | `tenant_id` | Last successful RSL ingestion time | -| `catalog_refresh_duration_seconds` | Histogram | `tenant_id` | RSL ingestion duration | -| `catalog_refresh_errors_total` | Counter | `tenant_id`, `reason` | RSL ingestion failures | - -### Transaction Log Metrics - -| Metric | Type | Labels | Description | -|---|---|---|---| -| `txlog_wal_pending_bytes` | Gauge | | Current WAL size (bytes) | -| `txlog_wal_pending_records` | Gauge | | Records waiting for durable store flush | -| `txlog_flush_duration_seconds` | Histogram | | WAL batch flush latency | -| `txlog_store_errors_total` | Counter | `store` | Durable store write failures | - -### Reporting Metrics - -| Metric | Type | Labels | Description | -|---|---|---|---| -| `reporting_obligations_total` | Gauge | `tenant_id`, `state` | Obligations by state | -| `reporting_compliance_rate` | Gauge | `tenant_id` | % of obligations fulfilled on time | -| `reporting_token_deviation` | Histogram | `tenant_id` | Deviation between reported and estimated tokens | -| `reporting_token_deviation_cumulative` | Gauge | `tenant_id`, `billing_ref` | Cumulative token deviation per requester | - -### Health Check Endpoint - -``` -GET /healthz → 200 OK -GET /readyz → 200 OK (catalog loaded, billing adapter reachable, WAL writable) -``` - -```go -type ReadinessCheck struct { - CatalogLoaded bool `json:"catalog_loaded"` - CatalogAge string `json:"catalog_age"` // e.g., "2m30s" - TenantCount int `json:"tenant_count"` - BillingReachable bool `json:"billing_reachable"` - WALWritable bool `json:"wal_writable"` - WALUtilization float64 `json:"wal_utilization"` // 0.0-1.0 -} -``` - -`/readyz` returns 503 if: -- No catalog has ever been loaded -- WAL utilization > 90% -- Billing adapter has failed 10 consecutive health checks - -### Structured Logging - -All logs use `log/slog` with structured key-value pairs. No `log.Printf` or custom loggers. Every error path MUST log before returning. - -**Redaction rules**: -- `billing_ref`: last 4 characters only (e.g., `****a1b2`) -- Signing keys: never logged -- Signed URLs: hash only, never full URL -- Request/response bodies: logged at DEBUG level only - -### Distributed Tracing - -Connect-Go interceptors propagate OpenTelemetry trace context. Each RPC creates a span. Sub-operations (billing, signing, catalog lookup) create child spans. - -```go -// Interceptor for tracing -func tracingInterceptor() connect.UnaryInterceptorFunc { - return func(next connect.UnaryFunc) connect.UnaryFunc { - return func(ctx context.Context, req connect.AnyRequest) (connect.AnyResponse, error) { - ctx, span := tracer.Start(ctx, req.Spec().Procedure) - defer span.End() - - span.SetAttributes( - attribute.String("rpc.method", req.Spec().Procedure), - ) - - resp, err := next(ctx, req) - if err != nil { - span.RecordError(err) - span.SetStatus(codes.Error, err.Error()) - } - return resp, err - } - } -} -``` diff --git a/website/src/content/docs/components/exchange/storage-model.mdx b/website/src/content/docs/components/exchange/storage-model.mdx deleted file mode 100644 index 7b66916b..00000000 --- a/website/src/content/docs/components/exchange/storage-model.mdx +++ /dev/null @@ -1,378 +0,0 @@ ---- -title: "Storage Model" -description: "Data structures and storage systems for catalog entries, transaction records, reporting obligations, and signing keys." ---- - -## Content Catalog (In-Memory) - -The catalog is the hot data structure. It must support fast lookup by URI (exact match and prefix/glob), with each entry carrying its license terms and per-term restrictions. - -**Data structure**: Radix trie (compressed trie) keyed by URI path, per tenant. - -```go -// Catalog holds the in-memory resource catalog for all tenants. -// Loaded from pre-built serialized binary produced by the ingestion pipeline. -// Reads are lock-free via atomic pointer swap on reload. -type Catalog struct { - // Current catalog snapshot. Replaced atomically when new serialized binary is loaded. - current atomic.Pointer[CatalogSnapshot] -} - -// CatalogSnapshot is an immutable point-in-time view of all tenant catalogs. -type CatalogSnapshot struct { - // Per-tenant catalog. Key is tenant ID. - Tenants map[string]*TenantCatalog - - // When this snapshot was built. - BuiltAt time.Time - - // Source hashes used to build this snapshot (for diff detection). - // Tracks all input sources (RSL license, sitemap, robots.txt, etc.), not just RSL. - SourceHashes map[string]string // tenant ID -> SHA-256 of combined source inputs -} - -// TenantCatalog holds a single provider's content offers. -type TenantCatalog struct { - TenantID string - - // Radix trie for URI-based lookup. - // Keys are normalized URI paths (e.g., "/premium/ai-infrastructure.html"). - // Values are OfferTemplates. - // - // Supports: - // - Exact match: "/premium/article-123.html" - // - Prefix match: "/premium/*" (glob from RSL) - // - Longest prefix wins (radix trie property) - URIIndex *radixtree.Tree[*OfferTemplate] - - // Glob matchers for pattern-based URI matching (e.g., "/blog/*/comments"). - // Evaluated after trie lookup when no exact/prefix match is found. - GlobMatchers []GlobMatcher - - // All offer templates for enumeration (e.g., broad DiscoverResources queries). - AllOffers []*OfferTemplate - - // Default for paths matching no entry: whether the tenant serves them - // openly or blocks AI access. Tenant-local config, NOT a wire type — a path - // is "licensed" exactly when it has a catalog entry carrying LicenseTerms. - BlockUnmatched bool -} - -// OfferTemplate is the pre-computed offer skeleton. Pricing and identity -// fields are populated at RSL ingestion time. Per-request fields (offer_id, -// expiry) are filled at query time. -type OfferTemplate struct { - // Content metadata (from RSL + provider config). - ContentPath string - Package *compv1.Package - Pricing *forav1.Pricing - Identity *forav1.ResourceIdentity - // License terms carried on the offer. Each LicenseTerm carries - // repeated Restriction (kinds: FUNCTION, GEOGRAPHY, USER_TYPE, ...). - // Each entitled term becomes its own Offer, carrying that term; not a - // server-side filter. - Terms []*forav1.LicenseTerm - DeliveryMethod forav1.DeliveryMethod -} -``` - -**Memory estimate**: Each OfferTemplate is ~500 bytes per entry (Package metadata + pricing + identity). A large provider with 100K articles = ~50 MB per tenant. 100 tenants = 5 GB. Fits in a modern server's RAM. For providers with millions of articles, the trie compresses well because URLs share path prefixes. - -**Trie loading**: The ingestion pipeline (background process) builds and serializes the radix trie to a binary file. The Exchange process loads the pre-built binary via atomic pointer swap -- the Exchange NEVER builds the trie itself. See the Content Ingestion Pipeline design doc for the serialization format and pipeline details. Loading a pre-built binary for 100K entries takes <100ms. During loading, the old catalog continues serving. - ---- - -## Transaction Log (Append-Only, Durable) - -The transaction log is the most critical data store. Every transaction that produces a billing_id must be durably recorded before the signed URL is returned. - -**Write path**: Local WAL (write-ahead log) buffer -> batch flush to durable store. - -```go -// TransactionRecord is the durable record written for every ExecuteTransaction. -type TransactionRecord struct { - // Primary key — ULID, time-ordered. - TransactionID string `json:"transaction_id"` - - // Billing reference for settlement. - BillingID string `json:"billing_id"` - - // What was purchased. - OfferID string `json:"offer_id"` - TenantID string `json:"tenant_id"` - ContentURI string `json:"content_uri"` - - // Who purchased. - BillingRef string `json:"billing_ref"` // Last 8 chars only in logs - AgentName string `json:"agent_name"` - - // Financials. - Amount float64 `json:"amount"` - Currency string `json:"currency"` - UnitCost float64 `json:"unit_cost,omitempty"` - - // Idempotency. Stores the request's idempotency key - // (TransactionRequest.idempotency_key) so a replay returns the original - // record. The dedupe key is the agent and this key, whatever the route: a - // retry through a Broker or directly finds the same record. It is NOT the - // wire correlation id — request/response correlation rides the X-Request-ID - // HTTP header. - IdempotencyKey string `json:"idempotency_key"` - // The Broker that relayed the purchase, if any: attribution only. The - // purchase is the agent's and is billed to BillingRef. - Broker string `json:"broker,omitempty"` - - // Offer snapshot (serialized JSON of the offer at transaction time). - // Enables audit queries without reconstructing from a potentially changed catalog. - OfferSnapshotJSON string `json:"offer_snapshot_json"` - - // Agent identity hash (RFC 7638 JWK Thumbprint of the agent's Ed25519 key). Non-optional string, not pointer. - AgentIdentityHash string `json:"agent_identity_hash"` - - // Delivery metadata. - DeliveryMethod string `json:"delivery_method"` - ReportingRequired bool `json:"reporting_required"` - ReportingDeadline time.Time `json:"reporting_deadline,omitempty"` - - // Chain hash for tamper-evident audit log. - ChainHash string `json:"chain_hash"` - - // Signed URL metadata (for reconciliation with CDN logs). - SignedURLHash string `json:"signed_url_hash"` // SHA-256 of the issued signed URL - URLExpiresAt time.Time `json:"url_expires_at"` - - // Timestamps. - CreatedAt time.Time `json:"created_at"` -} -``` - -**Local WAL**: A pre-allocated file on local SSD. Writes are fdatasync'd in batches (every 50ms or 100 records, whichever comes first). Each WAL entry is length-prefixed + CRC32 checksummed. This gives sub-millisecond append latency with crash safety. - -### Durable Store Options - -| Store | Throughput | Latency | Cost at 10K RPS | Notes | -|---|---|---|---|---| -| **S3 + Parquet** (hourly roll) | Unlimited | N/A (batch) | ~$2/day | Best for archival. Queryable via Athena. | -| **Kafka / Redpanda** | 100K+ msg/s | <5ms | ~$20/day | Best for real-time streaming to analytics. | -| **ClickHouse** | 100K+ inserts/s | <10ms | ~$15/day | Best for ad-hoc queries on transaction data. | -| **DynamoDB** | 10K WCU | <10ms | ~$50/day | Simplest. Higher cost. | - -**Recommended**: Local WAL + Kafka for streaming + S3/Parquet for archival. The WAL provides crash safety; Kafka provides real-time fanout to billing reconciliation, analytics, and S3 archival consumers. - -**Retention**: 13 months minimum per NFR. S3 lifecycle policy moves to Glacier after 3 months. - -### Offer Snapshot in Transaction Records - -The transaction record includes a full offer snapshot (offer_id, package.id, package.title, pricing details, content identity) serialized as JSON. This is the "fulfilled order receipt" — approximately 500 bytes extra per event, negligible at any tier. The audit chain is: ResourceQuery -> Offers presented -> Transaction authorized -> Signed URL issued (with offer snapshot) -> Usage reported. The snapshot enables audit queries like "what exactly was promised in transaction X?" without reconstructing from the catalog, which may have changed since the transaction occurred. - -### Growth Tier: PostgreSQL - -For Growth tier (100-1K RPS), PostgreSQL with daily partitions provides sufficient write throughput with strong durability guarantees. - -```sql --- Daily partitioned transaction log (append-only) -CREATE TABLE transactions ( - transaction_id TEXT NOT NULL, - billing_id TEXT NOT NULL, - offer_id TEXT NOT NULL, - tenant_id TEXT NOT NULL, - content_uri TEXT NOT NULL, - billing_ref TEXT NOT NULL, - amount NUMERIC(12,6) NOT NULL, - currency TEXT NOT NULL, - created_at TIMESTAMPTZ NOT NULL DEFAULT NOW() -) PARTITION BY RANGE (created_at); - --- Daily partitions auto-created by pg_partman or cron -CREATE TABLE transactions_2026_03_15 PARTITION OF transactions - FOR VALUES FROM ('2026-03-15') TO ('2026-03-16'); - --- Append-only enforcement -REVOKE UPDATE, DELETE ON transactions FROM exchange_app; -``` - -**Volume estimate at 1K RPS**: ~86M records/day, ~1 KB/record = ~86 GB/day uncompressed, ~30 GB/day with PostgreSQL TOAST compression. Daily partition drop after export keeps disk usage bounded. - -**Export to S3 Parquet**: A nightly job exports each day's partition to S3 as Parquet files for long-term analytics. Queryable via Athena or Trino. - -**Monitoring**: Grafana dashboards on Prometheus metrics exported by `pg_stat_statements` and custom transaction counters. Key panels: transactions/second, p99 write latency, partition size, WAL lag. - -### Scale Tier: ClickHouse - -For Scale tier (10K+ RPS), ClickHouse replaces PostgreSQL as the transaction log store. ClickHouse's columnar storage and append-optimized MergeTree engine handle 100K+ inserts/second. - -The local WAL + Kafka architecture feeds ClickHouse as a Kafka consumer. ClickHouse is the analytical store; the local WAL remains the durability guarantee for the write-before-sign invariant. - ---- - -## Reporting Obligations (State Machine) - -Each transaction that carries a ReportingObligation creates an obligation record. The obligation tracks whether the agent fulfilled its reporting duty. - -```mermaid -stateDiagram-v2 - [*] --> Pending: ExecuteTransaction creates obligation - Pending --> Fulfilled: ReportUsage accepted - Pending --> Expired: Reporting window elapsed - Pending --> Waived: Exchange waives requirement - Expired --> Blocked: Agent attempts new transaction - Fulfilled --> [*] - Waived --> [*] - Blocked --> Fulfilled: Late report accepted (grace) - Blocked --> [*]: Exchange lifts block -``` - -```go -// ObligationState tracks a single reporting obligation. -type ObligationState int - -const ( - ObligationPending ObligationState = iota // Created, awaiting report - ObligationFulfilled // Report received and accepted - ObligationExpired // Window elapsed, no report - ObligationWaived // Exchange waived requirement - ObligationBlocked // Agent blocked for non-reporting -) - -// Obligation is the per-transaction reporting obligation record. -type Obligation struct { - TransactionID string - TenantID string - BillingRef string - State ObligationState - RequiredFields []string - WindowEnd time.Time // Deadline for report submission - CreatedAt time.Time - FulfilledAt *time.Time // When report was accepted - ReportID string // ID of the accepted report -} -``` - -**Storage**: Obligations are stored in the same durable store as transactions. The Reporting Tracker loads recent obligations (last 48h) into memory at startup for fast lookup. A background goroutine sweeps expired obligations every minute and transitions them to `Expired`. - -**Enforcement**: When ExecuteTransaction resolves the requester's billing reference, it queries the Reporting Tracker for any `Expired` obligations. If found, the transaction is rejected with a `CodePermissionDenied` error indicating outstanding reporting obligations. This is the enforcement mechanism described in the FORA protocol specification. - -### Two Independent Metrics: Compliance Rate vs Token Accuracy - -The Reporting Tracker tracks two independent metrics that must not be conflated: - -**a) Reporting compliance rate**: The percentage of transactions that received a usage report within the reporting window. This measures whether the agent is fulfilling its reporting obligations at all. Providers set the threshold (e.g., 98% required). The protocol RECOMMENDS 95% minimum compliance. - -**b) Consumption accuracy**: The deviation between reported consumption (`UsageReport.usage.consumed_quantity`) and estimated consumption (`Offer.pricing.estimated_quantity`). A per-request deviation never refuses a report, and a metered purchase's charge is final (see [Charging a metered purchase](/protocol/transaction-flow/#charging-a-metered-purchase)). Monitoring deviation is the Exchange operator's own business: cumulative deviation is tracked, but thresholds are Exchange implementation, not protocol. - -These metrics are INDEPENDENT: -- An agent could have **100% compliance rate** but consistently underreport tokens (high compliance, low accuracy) -- An agent could have **80% compliance rate** but be accurate when it does report (low compliance, high accuracy) -- Enforcement gates on **compliance rate** (blocking transactions for non-reporting). Token accuracy is tracked for analytics and potential contract-level enforcement, but does not trigger protocol-level blocking. - -Cumulative benchmarking (same content, different agents, compare reported token counts) is an Exchange implementation concern, not a protocol requirement. The protocol accepts that token accuracy is a known limitation: agents self-report, and the Exchange's own token count for a resource (word_count x 1.32) is approximate. Neither changes a charge — a metered purchase is charged at the publisher's estimate × rate, or one unit's rate without one, and that charge is final. - -### Provider Audit Access - -Providers get read-only access to all signed Offers issued for their content. This enables independent verification of Exchange behavior — the provider can confirm that the Exchange is honoring pricing agreements and not under-reporting transactions. - -**API endpoint**: `GET /provider/{domain}/transactions?from=...&to=...` - -**Returns** (per transaction): -- `transaction_id` — Exchange-assigned transaction identifier -- `billing_id` — billing reference for settlement -- `offer_snapshot` — full Offer at transaction time, including `exchange_signature` -- `cost` — actual amount charged (or `0` for subscription transactions) -- `agent_id` — hashed agent identity (`SHA256(agent_key)`) -- `timestamp` — when the transaction was executed - -**Verification capabilities**: -- Provider can independently verify every Offer's `exchange_signature` using the Exchange's published Ed25519 public key (fetch the Exchange's WBA directory, the JWK Set at `/.well-known/http-message-signatures-directory`, and read its `keys`) -- RSL pricing, when present, serves as the **price ceiling** — Offers exceeding the RSL-declared rate are detectable by comparing `offer_snapshot.pricing.rate` against the RSL terms -- Private floor pricing is contractual between provider and Exchange, not protocol-enforced — the protocol provides the audit data, the contract governs the terms - -**Authentication**: Provider authenticates via a separate admin credential (not the FORA protocol). The Exchange SHOULD enforce domain ownership verification (e.g., DNS TXT record or `fora.json` presence) before granting audit access. - -**Rate limiting**: Audit queries are read-only and hit the archival store (S3/Parquet via Athena or equivalent), not the hot transaction log. Rate limit to prevent abuse but allow bulk export for reconciliation. - ---- - -## Signing Keys (Per-Tenant) - -Each tenant has its own signing keys, and the Exchange signs the delivery URLs of every publisher that tenant represents with them. For a publisher on CloudFront, the tenant's RSA key is the one registered in that publisher's trusted key group. The Exchange must store the keys securely and support rotation. - -```go -// TenantSigningConfig holds the signing configuration for a single tenant. -type TenantSigningConfig struct { - TenantID string - - // Active signing key. - ActiveKey SigningKey - - // Previous key (for grace period during rotation). - // CDN should accept signatures from both keys during rotation. - PreviousKey *SigningKey - - // Which delivery-URL scheme this tenant uses. - Scheme SigningScheme -} - -type SigningKey struct { - KeyID string // Key-Pair-Id for CloudFront; the key thumbprint for Ed25519 - PrivateKey []byte // Ed25519 private key, or a PEM-encoded RSA private key - ValidFrom time.Time - ValidUntil time.Time // 90-day max per NFR -} - -type SigningScheme string - -const ( - SchemeEd25519 SigningScheme = "ED25519" - SchemeCFRSA SigningScheme = "AWS_CLOUDFRONT_RSA" -) -``` - -**Key storage**: Keys are loaded from an external secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager) at startup and cached in memory. A background goroutine polls for rotations every 60 seconds. Providers who don't operate infrastructure manage keys via the Exchange tenant management API. - -**Rotation protocol**: -1. Provider uploads new key to secrets manager and configures it on their CDN. -2. Exchange's background goroutine detects the new key. -3. New key becomes `ActiveKey`; old key moves to `PreviousKey`. -4. After a grace period (configurable, default 1 hour), `PreviousKey` is cleared. -5. CDN must be configured to accept both keys during the grace period. - -**Key isolation**: Keys are loaded into per-tenant `SigningKey` structs. There is no shared key material between tenants. A compromised tenant's key does not affect others. - ---- - -## Dispute Records (v1.0) - -The storage model includes dispute records linked to transactions via `transaction_id` and `report_id`. Each dispute produces a `DisputeRecord` stored alongside transaction records. - -```go -// DisputeRecord tracks a content dispute through its lifecycle. -type DisputeRecord struct { - DisputeID string `json:"dispute_id"` - TransactionID string `json:"transaction_id"` - ReportID string `json:"report_id"` // Links to the UsageReport - BillingID string `json:"billing_id"` - BillingRef string `json:"billing_ref"` - TenantID string `json:"tenant_id"` - Reason DisputeReason `json:"reason"` - Description string `json:"description"` - Status DisputeStatus `json:"status"` - Resolution ResolutionType `json:"resolution,omitempty"` // RESOLUTION_TYPE_REJECTED when reviewed and denied - CreditAmount float64 `json:"credit_amount,omitempty"` - Currency string `json:"currency,omitempty"` - FiledAt time.Time `json:"filed_at"` - ResolvedAt *time.Time `json:"resolved_at,omitempty"` - EvidenceJSON string `json:"evidence_json,omitempty"` // CDN log evidence -} -``` - -The `report_id` linkage is critical -- it connects the dispute to the agent's prior usage report, establishing the evidence chain: `Offer -> Transaction -> UsageReport -> Dispute`. A dispute filed without a valid `report_id` is refused at filing time — that refusal is a non-OK transport error carrying a typed `ErrorDetail.dispute_failure` (`DISPUTE_FAILURE_REASON_REPORT_NOT_FILED`), and no `DisputeRecord` is created. A `DisputeRecord` exists only for disputes accepted for processing; one that is later reviewed and denied carries `Resolution = RESOLUTION_TYPE_REJECTED`. - -**Storage**: Dispute records share the same durable store as transaction records (PostgreSQL for Growth tier, ClickHouse for Scale tier). They are indexed by `dispute_id`, `transaction_id`, and `(billing_ref, filed_at)` for compliance queries. - -## Signed URL Canonicalization - -This section applies to **signed URLs only** (content delivery), not to offer signatures. Both use Ed25519; they differ in which key signs and who verifies. - -The signed message is the literal `GET`, one newline, then the canonical URL: the whole URL with the `sig` parameter removed and the remaining query sorted by key. Scheme, host and path are covered verbatim, and so is every publisher query parameter. The signature is base64url with no padding. The full rules, including the parameter set and the verification order, are on the [signed URL verification](/components/edge-function/signed-url-verification) page, which is normative. - -The Exchange records `signed_url_hash` — SHA-256 of the URL verbatim — on the transaction, and the delivery endpoint records the same hash on its delivery event. That pair is the join key for three-sided reconciliation; there is no transaction-id URL parameter. diff --git a/website/src/content/docs/getting-started/for-exchange-operators.mdx b/website/src/content/docs/getting-started/for-exchange-operators.mdx index f49f0a69..6ebda282 100644 --- a/website/src/content/docs/getting-started/for-exchange-operators.mdx +++ b/website/src/content/docs/getting-started/for-exchange-operators.mdx @@ -28,7 +28,7 @@ An existing marketplace can run a FORA Exchange over its own catalog, beside the FORA Server's Exchange is one Go binary in a container, `ghcr.io/fora-protocol/exchange`. It listens on two ports: the public Exchange listener, `8081` by default, and an internal admin listener, `8082`. To run it you provide: - **Two PostgreSQL databases**: one for the catalog, the transaction log and the audit log (`EXCHANGE_DSN`), and one for the account registry (`EXCHANGE_SOR_DSN`). -- **Redis** (`REDIS_URL`), which stops a signed request from being replayed. Every instance of a scaled-out Exchange shares one. +- **Redis** (`REDIS_URL`), which stops a signed request from being replayed. A single instance can run without it and then keeps this record in its own memory. Every instance of a scaled-out Exchange must share one Redis. - **An Ed25519 private key**, which signs offers and delivery URLs. An RSA key is needed only for a publisher whose CDN is AWS CloudFront. - **A ledger.** `FORA_BILLING_ADAPTER` chooses it: `tigerbeetle` keeps a prepaid balance per agent account in TigerBeetle, in the currencies `EXCHANGE_BILLING_LEDGER` lists. The default, `free`, approves every charge and records none. - **The Broker's address** (`EXCHANGE_BROKER_WELLKNOWN_URL`). The Exchange reads the Broker's withdrawn-key list from there and refuses to start without the address. See [Broker](/components/broker/overview/#who-runs-a-broker). @@ -43,7 +43,7 @@ The Exchange answers these calls: | `ExchangeService.Register` | Opens an agent's account and returns its `billing_ref` | | `ExchangeService.GetAccountStatus` | Returns the state of the agent's account | | `ExchangeService.DiscoverResources` | Returns signed offers for the URLs in a `ResourceQuery` | -| `ExchangeService.ExecuteTransaction` | Buys offers and returns a signed delivery URL for each paid item | +| `ExchangeService.ExecuteTransaction` | Buys offers and returns a signed delivery URL for each item it grants | | `ExchangeService.ReportUsage` | Takes the agent's usage report and returns its `report_id` | | `CatalogService.PushResources` | Takes catalog entries from a contributor the site's `fora.json` names | | `AdminService.SetTenantFeeRate` | Sets your fee, on the admin listener only | @@ -53,12 +53,12 @@ It also serves `/.well-known/fora.json`, your key directory at `/.well-known/htt ## Your rules and your fee -- **Your fee.** Your commission is `fee_rate_bps` on your seat, in basis points, set with `AdminService.SetTenantFeeRate` without a restart. 1500 is 15%. Each sale records the gross, your fee and the publisher's net. +- **Your fee.** Your commission is `fee_rate_bps` on your seat, in basis points, set with `AdminService.SetTenantFeeRate` without a restart. 1500 is 15%. With the `tigerbeetle` ledger, each sale posts the gross, your fee and the publisher's net. The `free` ledger records none of them. - **Which agents can buy.** `activate_new_agents_by_default` decides whether a newly registered agent can buy at once, or waits until you activate its account. A deactivated account is refused paid purchases with `DENIAL_REASON_ACCOUNT_INACTIVE`. -- **A welcome credit.** `EXCHANGE_DEFAULT_AGENT_CREDIT` grants each new account a starting balance, for example `EUR=100`. -- **Purchases through a Broker.** `allow_broker_relay` on your seat decides whether you accept purchases the Broker relays. A refused item is denied with `DENIAL_REASON_RELAY_NOT_ACCEPTED`, and the agent can buy that offer directly. +- **A welcome credit.** `EXCHANGE_DEFAULT_AGENT_CREDIT` grants each new account a starting balance, for example `EUR=100`. Each currency must be one your ledger bills in. +- **Purchases through a Broker.** `allow_broker_relay` on your seat decides whether you accept purchases the Broker relays. The protocol denies each refused item in the body with `DENIAL_REASON_RELAY_NOT_ACCEPTED`. FORA Server's Exchange does not do this: it refuses the whole relayed purchase, with that reason in `ErrorDetail.transaction_denial`. Either way, the agent can buy the offers directly. - **How many signatures a request may carry.** `EXCHANGE_MAX_INTERMEDIARY_HOPS`, published as `max_intermediary_hops`, 4 by default. -- **Reporting.** `AdminService.SetReportingPolicy` sets which fields a usage report must carry. A report is never refused for the quantity it states. +- **Reporting.** `AdminService.SetReportingPolicy` sets which fields a usage report must carry, how far its quantity may differ from the estimate, and how long the agent has to send it. The protocol never refuses a report for the quantity it states. FORA Server's Exchange does not follow that rule: it refuses a report outside the quantity tolerance, 20% by default. See [After the purchase](/components/exchange/overview/#after-the-purchase). The publishers set the terms and prices of their own content. Your Exchange signs the offers it builds from them. @@ -75,7 +75,7 @@ From then on, the publisher sees its sales in the console. See [Publisher Onboar ## Agents -An agent opens an account at your Exchange with `ExchangeService.Register`. The Exchange identifies the agent by the key that signed the request and returns a `billing_ref`, the opaque, long-lived handle of the agent's account at your Exchange. Registering again returns the same handle. A paid purchase without an account is denied with `DENIAL_REASON_ACCOUNT_NOT_REGISTERED`; free content needs none. +An agent opens an account at your Exchange with `ExchangeService.Register`. The Exchange identifies the agent by the key directory its request signature names, never by the request body, and returns a `billing_ref`, the opaque, long-lived handle of the agent's account at your Exchange. Registering again returns the same handle. A paid purchase without an account is denied with `DENIAL_REASON_ACCOUNT_NOT_REGISTERED`; free content needs none. You don't need a separate deal with each AI company. Any agent that speaks FORA can open an account and buy, under your agent policy. An agent on MCP registers through the [Identity Service](/components/identity/overview/). @@ -142,6 +142,8 @@ And the relay reason, for a provider that does not accept purchases a Broker rel |---|---| | `DENIAL_REASON_RELAY_NOT_ACCEPTED` | The provider that sells this item's resource does not accept purchases relayed by a Broker. Decided per item by each offer's provider and answered in the body, never as a refusal of the whole sub-request; the agent can buy the offer directly | +FORA Server's Exchange does not follow this rule: it refuses the whole relayed request, as [Your rules and your fee](#your-rules-and-your-fee) describes. + This is the identity/entitlement subset with operator guidance; the complete, authoritative `DenialReason` enum is rendered from the proto on the [proto reference](/reference/proto-fora/). For the full identity model specification — Requester fields, the JWT chain, scope format, and key management — see [Authentication](/protocol/authentication/). ## Units and profiles @@ -151,7 +153,9 @@ An offer names what it is metered in, and a metered purchase charges the publish - `unit`: what is metered. - `rate`: the price of one `unit`. - `estimated_quantity`: optional, the publisher's own estimate, in `unit`. A metered purchase charges the estimate × `rate`, or one unit's `rate` when the offer states no estimate, and that charge is final (see [Charging a metered purchase](/protocol/transaction-flow/#charging-a-metered-purchase)). -- `unit_cost`: the price of one purchase divided by the resource's size in the comparison unit of its content type. It never enters the charge. +- `unit_cost`: optional, the Exchange's normalized cost per unit, in its `base_currency`, for comparing offers across Exchanges (for text, the cost per token). It never enters the charge. + +FORA Server's Exchange does not follow the charge rule: it charges the offer's `unit_cost`, or its `rate` when `unit_cost` is not set, times the estimate. The two agree when an offer has no `unit_cost` or its `unit_cost` equals its `rate`. See [Billing and Ledgers](/components/exchange/billing-adapter/#charging-flow). ``` Exchange over Pricing.unit Example rate @@ -166,13 +170,13 @@ Audio streams minutes $0.02/minute Drug interactions pharma:interaction_pairs $0.001/pair ``` -A usage report states `consumed_quantity` and `consumed_unit`, in the offer's `unit`, and is never refused for the quantity it reports. An Exchange MUST NOT assume an offer is metered in tokens; only a usage report that omits `consumed_unit` is read as tokens. +A usage report states `consumed_quantity` and `consumed_unit`. `consumed_unit` must match the offer's `unit`, and a report that omits it is read as tokens. The protocol never refuses a report for the quantity it reports; FORA Server's Exchange still does, outside the reporting policy's quantity tolerance. Your manifest's `supported_profiles` tells Brokers and agents which domain profiles your offers follow. FORA Server's Exchange declares `fora-news-v1`, `fora-comp-v1` and `fora-music-v1`. An agent declares the profiles it understands, and a Broker forwards that list to your Exchange unchanged. See [Extension Profiles](/protocol/extension-profiles/). ## Exchange manifest and health -Your Exchange serves its manifest at `/.well-known/fora.json`, with `role` set to `ROLE_EXCHANGE`. It tells Brokers and agents what your Exchange offers: its endpoint, `base_currency`, `supported_profiles` and `max_intermediary_hops`. In FORA Server, `base_currency` is the first currency in `EXCHANGE_BILLING_LEDGER`, and the Exchange rebuilds the manifest from its configuration. Your offer-signing keys are in your key directory, not in `fora.json`. See [Exchange Manifest](/protocol/exchange-manifest/). +Your Exchange serves its manifest at `/.well-known/fora.json`, with `role` set to `ROLE_EXCHANGE`. It tells Brokers and agents what your Exchange offers: its endpoint, `base_currency`, `supported_profiles` and `max_intermediary_hops`. In FORA Server, with the `tigerbeetle` ledger, `base_currency` is the first currency in `EXCHANGE_BILLING_LEDGER`; with the `free` or `inmemory` ledger, it is `USD`. The Exchange rebuilds the manifest from its configuration. Your offer-signing keys are in your key directory, not in `fora.json`. See [Exchange Manifest](/protocol/exchange-manifest/). `/healthz` checks the catalog database, and `/readyz` also checks the ledger. FORA Server's Broker reads the health endpoint of each Exchange in its registry and routes only to an Exchange that answers `200`. @@ -180,10 +184,14 @@ Your Exchange serves its manifest at `/.well-known/fora.json`, with `role` set t An attestation is a signed claim about a resource, by its publisher or by a verification vendor. When attestations arrive with `CatalogService.PushResources`, the protocol has the Exchange check that the signer is the provider itself or a contributor the provider's `catalog_contributors` lists, and verify the attestation's Ed25519 signature against the key in the signer's key directory. See [Resource Attestation](/protocol/content-attestation/). +FORA Server's Exchange does not check attestations: it stores the attestations a push carries and returns them on offers without verifying their signatures. + ## Usage reports and disputes `ExchangeService.ReportUsage` takes a report on a transaction your Exchange recorded and returns a `report_id`. An agent files a dispute with `ExchangeService.DisputeTransaction` at the Exchange that sold the item, and each `DisputeRequest` names the `report_id` of its usage report. The protocol standardizes the dispute's states and outcomes; how an Exchange decides a dispute is up to the Exchange. See [Dispute Resolution](/protocol/dispute-resolution/). +FORA Server's Exchange does not implement `DisputeTransaction`: the call returns `unimplemented`. It stores the evidence of each sale, and disputes are handled outside the platform. + ## Brokers An agent can buy from your Exchange directly or through a [Broker](/components/broker/overview/). A Broker sends your Exchange only the URLs it routes to you, never the agent's words, and returns your signed offers unchanged, each as a full package, in its own order of relevance. The agent decides which to buy. Your account holder is always the agent: a purchase through a Broker charges the agent's account at your Exchange, never the Broker's.