Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

11.3 KB
Raw Blame

three.ws on-chain contracts

Every contract and program three.ws owns lives here: the Solidity set built with Foundry, and the three Solana programs built with Anchor. Solana is the home chain; the EVM contracts are additional surfaces.

Reviewing these contracts? Start at AUDIT-README.md: scope, deploy status, where the money is, the invariant ids, and the exact commands that reproduce every coverage and static-analysis number.

You probably do not need to deploy the ERC-8004 registries. The canonical ERC-8004 reference contracts are already live at the same addresses on every major EVM chain, and ../src/erc8004/abi.js already points at them: identity 0x8004A169... on mainnets, 0x8004A818... on testnets. The registry sources here are a local reference implementation, useful if you need to fork, audit, or run a private deployment.

What is in here

Contract Source Role Deploy status
ThreeWSPayments ThreeWSPayments.sol x402 pay-per-call USDC receiver Live on BNB Smart Chain, Base, Arbitrum One. Custodies real USDC
ThreeWSFactory ThreeWSFactory.sol CREATE2 deployer behind the platform's vanity addresses Live on the same three chains
IdentityRegistry src/IdentityRegistry.sol ERC-8004 agents as ERC-721, EIP-712 delegated wallet, key/value metadata Canonical ERC-8004 address live everywhere; not deployed from this tree
ReputationRegistry src/ReputationRegistry.sol One signed score per reviewer per agent, aggregated on-chain Same as above
ValidationRegistry src/ValidationRegistry.sol Allow-listed validators attest to off-chain proofs (for example glTF-Validator reports) Not deployed from this tree; the platform uses the ERC-8004 reference registry
AgentPayments src/AgentPayments.sol Payments in, split into authority and buyback shares, buyback swaps and burns Not deployed. See AGENT_PAYMENTS.md
GreenfieldVault src/GreenfieldVault.sol Pay-to-unlock marketplace over a real BNB Greenfield cross-chain permission grant Not deployed to a public chain; proven on an anvil fork
WorldMoves src/WorldMoves.sol Event-only move stream for the Agora world. No value, no admin Not deployed to a public chain
SkinHook v4-hooks/src/SkinHook.sol Uniswap v4 hook: wearable 3D items as fixed-supply coins, wear-to-lock, in-swap creator royalty, referrer share Not deployed. See v4-hooks/README.md
AgentTierHook v4-hooks/src/AgentTierHook.sol Uniswap v4 hook: an ERC-8004 agent's reputation sets the LP fee it pays Not deployed. Fork-tested against live Base
skill_license skill-license/ Solana: a 1-of-1 NFT access key per purchased skill, revocable on refund Not deployed. Program id reserved
agent_invocation agent-invocation/ Solana: verifiable agent-to-agent invocation events Not deployed. Program id reserved
knock_escrow knock-escrow/ Solana: a priced message held in escrow that pays out only against a reply, and refunds in full otherwise Not deployed. Program id reserved

Per-address provenance and every chain id: DEPLOYMENTS.md.

Build and test the Solidity set

Install Foundry once:

curl -L https://foundry.paradigm.xyz | bash
foundryup

Then, from this directory:

forge build
forge test

242 tests across 8 suites, all passing:

Suite Tests
AgentPaymentsTest 57
GreenfieldVaultTest 41
IdentityRegistryTest 37
ReputationRegistryTest 31
ThreeWSPaymentsTest 22
ValidationRegistryTest 22
WorldMovesTest 19
ThreeWSFactoryTest 13

forge test --summary reprints that table. Dependencies (forge-std, openzeppelin-contracts) are vendored under lib/, so no forge install step is needed.

Build and test the Solana programs

The invariant suite in program-tests/ runs the real compiled SBF bytecode in LiteSVM, so the bytecode has to exist before the tests run:

cd skill-license       && cargo-build-sbf
cd ../agent-invocation && cargo-build-sbf
cd ../knock-escrow     && cargo-build-sbf
cd ../program-tests    && cargo test

cargo-build-sbf ships with the Solana (Agave) toolchain, and cargo test needs a host Rust toolchain:

sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"
export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

A cold SBF build takes minutes per program; the tests themselves run in seconds. Green is 42 tests: 21 for skill_license, 11 for agent_invocation, and 10 for knock_escrow. The harness, the invariant ids, and the reason the LiteSVM clock must be set are all documented in program-tests/README.md.

Deploy the registries to Base Sepolia

Only needed for a private or forked deployment. The platform itself reads the canonical registries.

  1. Fund a deployer wallet with Base Sepolia ETH: https://www.alchemy.com/faucets/base-sepolia

  2. Configure environment:

    cp .env.example .env
    # Fill in DEPLOYER_PK and BASESCAN_API_KEY
    
  3. Deploy and verify:

    source .env
    forge script script/Deploy.s.sol:Deploy \
        --rpc-url $BASE_SEPOLIA_RPC_URL \
        --private-key $DEPLOYER_PK \
        --broadcast \
        --verify
    

    To rehearse without spending anything, point --rpc-url at a local anvil and use one of its funded dev keys. The script prints the three addresses and the ValidationRegistry owner either way.

  4. Point the browser code at your deployment. In ../src/erc8004/abi.js, REGISTRY_DEPLOYMENTS[84532] currently references the shared TESTNET constant that all seven supported testnets point at, so editing that constant would repoint every one of them. Replace the single entry with a literal instead:

    84532: {
        identityRegistry: '0xYourIdentityRegistry',
        reputationRegistry: '0xYourReputationRegistry',
        validationRegistry: '0xYourValidationRegistry',
    },
    

Deploy the registries to Base mainnet

Same as above with $BASE_RPC_URL, replacing the 8453 entry (which references the shared MAINNET constant) the same way.

After deploy: register three.ws itself

// Browser console on three.ws with a wallet connected to Base Sepolia:
import { registerAgent } from './src/erc8004/index.js';
const r = await registerAgent({
    name: 'three.ws',
    description: 'AI-powered 3D model viewer & validation agent',
    glbFile: yourGlbFile, // a File; omit and pass glbUrl if it is already pinned
    onStatus: console.log,
});
console.log(r); // { agentId, registrationUrl, txHash, chainId }

Pinning uses the platform's built-in R2 backend by default. Pass apiToken: '<your Pinata JWT>' to pin through your own Pinata account instead. The full option list (2D image, auto thumbnail, declared services, x402 support) is documented on registerAgent in ../src/erc8004/agent-registry.js.

Then update ../public/.well-known/agent-registration.json:

"registrations": [
    { "agentId": 1, "agentRegistry": "eip155:84532:0xYourIdentityRegistryAddress" }
]

Authorize a validator (for on-chain validation records)

The registry the platform actually reads and writes is the ERC-8004 reference ValidationRegistryUpgradeable, which has no allowlist. A validator earns the right to attest per agent, from the agent's owner:

# The agent's owner opens a request naming the validator, on the Identity
# Registry's terms (owner, per-token approval, or approval for all).
cast send $VALIDATION_REGISTRY \
    "validationRequest(address,uint256,string,bytes32)" \
    $VALIDATOR_ADDR $AGENT_ID "$REPORT_URI" $REQUEST_HASH \
    --rpc-url $BASE_SEPOLIA_RPC_URL \
    --private-key $OWNER_PK

To let a validator (for example the platform's) open requests itself, the owner approves it as an operator instead: approve(validator, agentId) or setApprovalForAll(validator, true) on the Identity Registry.

The validator then answers with validationResponse(requestHash, response, responseURI, responseHash, tag), which the recordValidation() helper in ../src/erc8004/validation-recorder.js wraps (including the request leg when the same wallet owns the agent).

Uniswap launcher (Base)

src/ThreeWsUniswapLauncher.sol launches a fixed-supply token and its Uniswap V3 pool in one transaction, with a lock option (none, timelock, permanent) and fee routing. Its constructor takes (positionManager, weth, treasury, launchFeeWei, platformShareBps). Tests fork Base and run with:

export PATH=$PATH:$HOME/.foundry/bin
forge test --match-contract ThreeWsUniswapLauncherTest --fork-url $BASE_RPC_URL

Deploying it to mainnet and setting UNISWAP_LAUNCHER_ADDRESS on the API service is the owner's action. Until that is set, GET /api/launches/lanes reports the lane as unavailable. See ../docs/launch-lanes.md.

Layout

contracts/
├── ThreeWSPayments.sol          live x402 USDC receiver
├── ThreeWSFactory.sol           live CREATE2 vanity deployer
├── src/
│   ├── IdentityRegistry.sol
│   ├── ReputationRegistry.sol
│   ├── ValidationRegistry.sol
│   ├── IIdentityRegistry.sol
│   ├── AgentPayments.sol
│   ├── GreenfieldVault.sol
│   ├── WorldMoves.sol
│   └── greenfield/              BNB Greenfield precompile interfaces
├── test/                        8 Foundry suites, 242 tests
│   └── mocks/                   MockGreenfield, Reentrant
├── script/                      Foundry deploy scripts, one per contract
├── skill-license/               Anchor program + DEPLOYMENT.md
├── agent-invocation/            Anchor program
├── knock-escrow/                Anchor program, escrowed pay-per-reply
├── program-tests/               LiteSVM invariant suite over the real bytecode
├── idl/                         vendored Anchor IDLs (ours plus the launchpad
│                                interfaces the platform reads; see idl/pump/README.md)
├── audit/                       committed Slither + Clippy output
├── vanity/                      CREATE2 salt grind artifacts
├── lib/                         vendored forge-std + openzeppelin-contracts
├── AUDIT-README.md              start here for a review
├── DEPLOYMENTS.md               address provenance per chain
├── AGENT_PAYMENTS.md            AgentPayments design notes
├── foundry.toml
└── .env.example