pod-creator

Source: packages/oracle-runtime-workers/src/plugins/pod-creator/

Summary

The POD Creator designs an IXO Programmable Organisational Domain (POD) end to end, then walks the user through creating it on chain. The user's Portal wallet signs every chain step; the oracle never holds a signing key for it.

1. Design. The main agent runs the design pipeline (qualify, architect, build, evaluate, package, gate) through twelve specialist sub-agents, one stage at a time. Sections enter the design only through a specialist, and the evaluate and gate specialists must record a pass before creation unlocks.
2. Create the POD (0.42.0 and later). One wallet signature creates the POD, owned by the user, with its public profile.
3. Add its domain card (0.42.0 and later). One more signature adds the POD's public domain card, as the Portal does.
4. Give it a governance group (0.44.0 and later, optional). Two signatures create a DAO DAO group and link it to the POD, so the Portal's Decisions tab and the POD's rooms use it.

Environment variables

What it contributes

• Tools:

• Sub-agents: twelve design specialists (call_<role>_agent), bound once a design exists; the model is shown only the current stage's.
• Middleware: one request middleware that keeps the specialists in stage order.
• HTTP routes: none.
• Shared state: per user, in the user's own store: one design per thread (24 hours idle) and the creation session (1 hour idle).

Creating the POD

Creation unlocks only when the design passes its gates, and goes propose, approve, sign, confirm:

1. prepare_pod_transaction({ name, description? }) takes the POD's name (1 to 100 characters) and an optional description (at most 600 characters) as the user agreed them. It checks that the user's identity is on chain and lists their account (the chain refuses the POD otherwise), reads their public key, reserves the POD's public profile on the oracle's homeserver, and prepares one MsgCreateEntity owned by the user. The summary quotes the exact name and description.
2. approve_pod_transaction must come in a later user message than the prepare, and quote every risk word for word.
3. request_pod_signature re-checks the design's gates, publishes the profile (only now, after approval), and asks the wallet to sign. The approval is single-use. If the homeserver is down, the approval is kept and nothing is sent.
4. confirm_pod_creation({ txHash }) reads the transaction on chain for up to 20 seconds, checks that it is the transaction this conversation sent and that the POD belongs to the user, and returns the POD's DID and its Portal link. When the POD is not on chain yet it says so, and can be asked again with the same hash.

add_pod_domain_card then adds the POD's public domain card, as the Portal does for a domain it creates, and asks the domain indexer to index the POD. The POD's Matrix space is created by the Portal the first time the POD is opened there.

Expected refusals of every step (identity not on chain, homeserver down, transaction not found yet) come back as results the model can explain, not errors.

Governance group

From 0.44.0, after a POD is created the model offers a governance group: with the members and approval rule the design names when it names one, otherwise as a question. It never creates a group unasked, and never invents members: each member is an ixo1… address the user gives or confirms.

1. create_pod_group({ members, threshold, name?, votingPeriodSeconds?, allowRevoting? }) creates the group the Portal creates for a POD: 1 to 12 members with one vote each, threshold yes votes to pass a proposal (1 to the number of members), and the POD's name unless another is given (at most 64 characters). The model asks the user how long voting lasts (1 hour to 30 days, default 7 days) and whether members may change their votes (default yes), explaining that with vote changes a proposal passes only when voting closes, and without them as soon as enough members vote yes. The first call sends nothing and shows the exact group: its name, every member, the threshold, both voting rules and whether the user is a member, with the risks of both signatures. The group is signed only once the user confirms in a later message.
2. link_pod_group links the group to the POD as its governing group and adds it as a controller of the POD's identity, then returns the POD's Decisions link in the Portal. The user accepted its risks with the group, and the wallet shows it.

Each is one wallet signature, once per POD. Both act only on the POD created in this conversation. For a POD made earlier, elsewhere or in the Portal, or to link a group the user already has, the model uses ixo-transaction's link_dao_group. Proposals of the group go through the ixo-transaction proposal tools.

Mainnet

NETWORK defaults to mainnet in the base schema, so an oracle that sets neither NETWORK nor POD_CREATOR_ALLOW_MAINNET gets a refusal, never a mainnet transaction. Set POD_CREATOR_ALLOW_MAINNET=true to create PODs on mainnet.

Custom chain gateway

The bundled chain gateway composes the POD's transaction and reads its results back. A fork can pass its own to new PodCreatorPlugin({ chainGateway }) in plugins, or notConfiguredChainGateway to keep on-chain creation off (the tools then report it unavailable). A fork with its own gateway must implement findPodGroup from 0.44.0: the group step reads the new group's address through it.

Known limits

• The Portal adds the Matrix space. The POD's Matrix space is created when the POD is first opened in the Portal.
• Profiles use the legacy media path. The profile URL is the unauthenticated Matrix download path, as the Portal's. A homeserver that serves new media only on the authenticated endpoint answers it with 404.
• The registry names are not owned yet. The specialists run on built-in prompts. An opt-in registry fetcher exists, but should stay off until IXO owns the design-pod-* skill names: whoever publishes under them would control the specialists' prompts.

When to use it

• The user wants to design or create a POD.
• The user wants a governance group for the POD created in the same conversation.

When NOT to use it

• A group for a POD made earlier or elsewhere, or an existing group: use link_dao_group in ixo-transaction.
• Creating on chain from a chat outside the Portal: every chain step needs the user's Portal wallet.